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 ([email protected])

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.