NAME

Data::Inspect - human-readable object representations

SYNOPSIS

  use Data::Inspect;
  my $insp = Data::Inspect->new;
  $insp->p($object);

  use Data::Inspect qw(p);
  p $object;

DESCRIPTION

Data::Inspect provides a human-readable representation of any Perl scalar. Classes can be extended with user-defined inspect methods. It is heavily inspired by Ruby's "p" method and inspect functionality.

The purpose of this module is to provide debugging/logging code with a more readable representation of data structures than the extremely literal form output by Data::Dumper.

It is especially useful in an object-oriented system, since each class can define its own "inspect" method, indicating how that particular object should be displayed.

The "p" method inspects its arguments and outputs them to the default filehandle. It can be exported to your package's namespace, in which case it will silently create the Inspect object with the default options, if this sort of brevity is desired.

PUBLIC METHODS

new

  my $insp = Data::Inspect->new;

Create a new Data::Inspect object.

p

  $insp->p($var1, $var2);

  use Data::Inspect qw(p);
  p $var1, $var2;

Inspects each of the provided arguments and outputs the result to the default filehandle (usually STDOUT).

"p" can be exported to the current namespace if you don't want to create a Data::Inspect object to do your inspecting for you.

pe

  $insp->pe($var1, $var2);

Exactly like "p" but outputs to STDERR instead of the default filehandle.

pf

  $insp->pf($somefh, $var1, $var2);

Like "p" and "pe" but outputs to the filehandle specified in the first argument.

Note that the filehandle must be a reference. If you want to use a filehandle that isn't a reference, you can create one using the Symbol::qualify_to_ref function.

inspect

  my $value = $insp->inspect($var);

Inspects the given scalar value and returns the result.

set_option

  $insp->set_option('truncate_strings', 30);

Set the given option to the given value. Options alter the output of Inspect.

Available options are:

truncate_strings: If set to a positive integer, truncates strings after that number of characters, replacing the end with '...'.
default: undef
sort_keys: If set to the string 'cmp' or '<=>', hashes will have their keys sorted using the specified comparison before being output.
default: undef

EXAMPLES

Inspecting built-in Perl types

In this example, we use the "p" method to output the inspected contents of a Perl hash:

  use Data::Inspect qw(p);
  p \%some_hash;

The output is something like:

  {"baz" => "qux\n\n", "foo" => "bar"}

Changing how an object looks

In this example, objects of class "Wibble" are blessed hashrefs containing a lot of data. They are uniquely identifiable by one key, "id"; so we create an inspect method that just displays that "id":

  package Wibble;
  
  sub inspect {
    my ($self, $insp) = @_;
    "#<Wibble id=$self->{id}>";
  }

If we have a hash full of Wibbles we can now see its contents easily by inspecting it:

  use Data::Inspect qw(p);
  p \%hash_of_wibbles;

The output will be something like:

  {"bar" => #<Wibble id=42>, "baz" => #<Wibble id=667>, "foo" => #<Wibble id=1>}

Recursive inspecting

$_[1] is set to the current Data::Inspect object in calls to an object's "inspect" method. This allows you to recursively inspect data structures contained within the object, such as hashes:

  package Wibble;

  sub inspect {
    my ($self, $insp) = @_;
    "#<Wibble id=$self->{id} data=".$insp->inspect($self->{data}).">";
  }

Using Data::Inspect in the OO form

The OO form provides a greater degree of flexibility than just importing the "p" method. The behaviour of Data::Inspect can be modified using the "set_option" method and there is also an "inspect" method that returns the inspected form rather than outputting it.

  use Data::Inspect;
  my $insp = Data::Inspect->new;
  
  # Strings are truncated if they are more than 10 characters long
  $insp->set_option('truncate_strings', 10);
  
  $insp->p("Supercalifragilisticexpialidocious");

Outputs:

  "Supercalif..."

CHANGES

  - 0.04 Fixed test case 7 to work with Perl 5.11.5

  - 0.03 Fixed documentation and tests further.

  - 0.02 Added support and documentation for recursive inspecting.
         Fixed tests on versions of perl built without useperlio.

  - 0.01 Initial revision

AUTHOR

Rich Daley <cpan@owl.me.uk>

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.