The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Data::PrettyPrintObjects - a pretty printing module with better support for objects

SYNOPSIS

This module is a fairly powerful pretty printer useful for printing out perl data structure in a readable fashion.

The difference between this module and other data dumpers and pretty printers is that it can be configured to handle different types of references (or objects) in different ways, including using object methods to supply the printable value.

If you have simple data structures without any blessed objects embedded in them, this module behaves similar to any other pretty printers. However, if you have objects embedded in them, this module is very useful for describing the data.

Although modules such as Data::Dumper are often used for this purpose, this module is NOT a replacement for Data::Dumper, or any other similar module. Data::Dumper examines raw data (including printing out the full representation of an embedded object). A pretty printer, such as this one, is designed to print the data in a readable form, which may or may not mean displaying the raw data.

As an example, if you have data structure which includes an Archive::Zip object, you may want the printable value of that object to be a list of all files in the archive, rather than a description of the Archive::Zip object. If you have a Date::Manip::Date object, you probably want the printable value to be a date contained in the object.

DISPLAYING DATA

For displaying a data structure, the structure is examined recursively, and turned into a string. The format of the string depends on the type of data and the options described below.

Displaying scalars

Most of the time, a scalar is displayed exactly as it exists. If the scalar includes embedded quotes, commas, spaces, or newlines, it will be quoted. Embedded newlines will be emphasized by including '\n' in the string. This is not true perl quoting since embedded quotes will not be escaped.

Embedded newlines will cause the output to be quoted, and an extra space added at the start of each line. For example:

   print PPO("a\nb\nc") =>
      'a
       b
       c'

Note the leading extra space on the second and third lines. This is so printing out a multi-line scalar will correctly line up after quotes have been added.

Displaying lists

A list will be displayed as square brackets enclosing list elements.

In other words:

   [
     ELE1,
     ELE2,
     ...
     ELEN
   ]
Displaying hashes

A has will be displayed as:

   {
     KEY1    => VAL1,
     KEY2    => VAL2,
     ...
     KEYN    => VALN
   }
Displaying objects

Objects will typically be displayed using their scalar representation (i.e. what you get with the function scalar($object)), but this can be overridden using the options described below.

OPTIONS

Options may be set in one of two ways.

They may be set in a file specified by the PPO_OptionsFile function, or they may be set by passing them to PPO_Options.

The argument to PPO_Options is a hash containing option/value key pairs. The argument to PPO_OptionsFile is a file containing a YAML hash. The following keys are known:

indent

Each level of a data structure is indented a certain number of spaces relative per level. This defaults to 2, but this option can be used to change that.

list_format

When displaying a list, the list_format option defines how it will be formatted. Possible values include:

standard By default, a list is printed in a one per line format. In other words:

                [
                  a,
                  b,
                  c
                ]

indexed This is one item per line with an index. In other words:

                [
                  0: a,
                  1: b,
                  2: c
                ]
max_depth

In a nested data structure, the depth of a piece of data refers to how many levels deep it is nested. If max_depth is 0 (which is the default), all levels will be printed).

For example, one data structure might be printed as:

   [ 
     a,
     b,
     [
       c,
       [
         d
       ]
     ]
   ]

(if max_depth were 0).

In this example, 'a' and 'b' are both at depth 1, 'c' is at depth 2, and 'd' is at depth 3. Sometimes, you may only want to print out the top levels. By setting a max_depth to N, every scalar value (or object who's printable value is a scalar) who's depth is N or smaller will be printed out. It will not recurse into more deeply nested data structures, but instead will print them out using the max_depth_method described next.

In this example, setting max_depth to 2 might result in the following output:

   [
     a,
     b,
     [
       c,
       ARRAY(0x111111)
     ]
   ]

The format used to display the structures more deeply nested depend on the max_depth_method.

max_depth_method

When max_depth is set, structure that is more deeply nested than that depth are displayed in some method to indicated that the structure is there, but it is not recursed into to display the actual data contained there.

The possible values for max_depth_method are:

ref This is the default, and means to display the memory reference of the structure. For example, an array reference would be displayed:

            ARRAY(0x111111)

         and an object with a non-scalar printable
         value would include the class, so an Archive::Zip
         object (who's printable value might be defined to
         be a list of files contained in the archive) might
         be:

            Archive::Zip=HASH(0x15c8e50)

         If the printable value of an object is a scalar,
         it will be printed using the methods defined for
         that object.

type This is a simpler version when you are only interested in seeing the type of structure/object but not the memory reference. They might be displayed as:

            ARRAY
            Archive::Zip
duplicates

If a data structure has circular references, or structure/objects embedded in it multiple times, there are different ways to display it.

For example, if you have the code:

   $a  = [1];
   $d1 = [$a,$a]

   $d2 = [];
   push(@$d2,2,$d2);

the structures '$d1' and '$d2' will be displayed depending on the value of the duplicates option. The value may be one of the following:

link This is the default. In this case, the first occurence of a data structure is displayed normally, and the second (or higher) occurence is listed as a link to the first one.

         '$d1' would be printed as:

            [
              [
                1
              ],
              $VAR->[0]
            ]

         and '$d2' would be printed as:

            [
              2,
              $VAR
            ]

reflink This adds memory references to all duplicates. So the '$d1' and '$d2' would be displayed as:

            [
              ARRAY(0x111111) [
                1
              ],
              ARRAY(0x111111) $VAR->[0]
            ]

         and

            ARRAY(0x111111) [
              2,
              ARRAY(0x111111) $VAR
            ]

ref This simply prints second (or higher) occurrences as memory references (but doesn't indicate what it duplicates):

            [
              [
                1
              ],
              ARRAY(0x111111)
            ]

         and

            [
              2,
              ARRAY(0x111111)
            ]
objs

The objs option is used to set the options for each type of object. The value of this is a hash described in the OBJECT OPTIONS section below.

OBJECT OPTIONS

The value of the objs option is a hash. The keys in this hash are the full names for various objects. The value for each entry is a hash containing the options for that object.

For example, to set options for displaying an Archive::Zip object, you would need to pass in the following to the PPO_Options function:

   %obj_opts = ( 'Archive::Zip'  => { OPT => VAL, OPT => VAL, ... } );
   PPO_Options(..., objs => \%obj_opts );

The object options include the following:

print

This tells how the printable value of an object should be obtained. Values can be:

ref The object will be printed out as a reference:

             Archive::Zip(0x111111)

          This is the default method.

method If this is passed in, the value is a string which is a method name that can be used to return the printable value.

          In other words, if $obj is an object, the
          printable value is obtained by calling:

             $obj->METHOD(ARGS)

          where METHOD is the value of the B<func> option, and ARGS is
          the value of the B<args> option.  The arguments are passed
          unmodified.

func This can either be the name of a function, or a function reference. The printable value for the object is obtained by calling:

             &FUNC(ARGS)

          where FUNC is the value of the B<func> option and
          ARGS is the value of the B<args> option.

          Exactly one of the ARGS should be the
          literal string '$OBJ' which will be
          replaced with the actual object.

          FUNC is looked for in the namespace of the
          caller, the namespace of the object, and the main
          namespace (in that order).

data This treats the object as a data structure and displays it.

func

This is the name of the method or function used to get the printable value of an object. It must be defined if print is 'method' or 'func'. There is no default value.

args

This is a list of arguments to pass to the method or function.

type

This is only used if the value of the print option is method or func. The output from the method/function will be treated as a scalar by default, but if this is set to any of the following, the output will be treated as that type of structure:

   scalar
   list
   hash

If the return value is a scalar that is a reference, it will be displayed using the rules for that type of data.

ref

If this option is set to a non-zero value, the reference will be output along with the printable value. For example, if the object is an Archive::Zip object, and (using the method or func method) the printable value is defined to be the list of files, the printable version will be either:

   [
     file1,
     file2
   ]

or

   Archive::Zip(0x111111) [
     file1,
     file2
   ]

The second will be used if this is non-zero.

This option is ignored if the print method is 'ref'.

FUNCTIONS

PPO_Options
PPO_OptionsFile
   use Data::PrettyPrintObjects;
   Options(%options);
   OptionsFile($file);

This sets any of the options described above. Any options already set which are not included in the %options argument are left unmodified.

This does not hold true for the object options. If you set the object options for a type of object, it overrides completely all options previously set for that type of object.

Any file passed in to OptionsFile must be a valid YAML file containing an %options hash.

PPO
   $string = PPO($var);

This formats $var (which can be any type of data structure) into a printable string.

KNOWN BUGS

None known.

BUGS AND QUESTIONS

Please send bug reports to the author.

LICENSE

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

AUTHOR

Sullivan Beck (sbeck@cpan.org)