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:
-
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 hashIf 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)