1Data::Printer(3)      User Contributed Perl Documentation     Data::Printer(3)
2
3
4

NAME

6       Data::Printer - colored pretty-print of Perl data structures and
7       objects
8

SYNOPSIS

10       Want to see what's inside a variable in a complete, colored and human-
11       friendly way?
12
13         use Data::Printer;   # or just "use DDP" for short
14
15         p @array;            # no need to pass references
16
17       Code above might output something like this (with colors!):
18
19          [
20              [0] "a",
21              [1] "b",
22              [2] undef,
23              [3] "c",
24          ]
25
26       You can also inspect objects:
27
28           my $obj = SomeClass->new;
29
30           p($obj);
31
32       Which might give you something like:
33
34         \ SomeClass  {
35             Parents       Moose::Object
36             Linear @ISA   SomeClass, Moose::Object
37             public methods (3) : bar, foo, meta
38             private methods (0)
39             internals: {
40                _something => 42,
41             }
42         }
43
44       Data::Printer is fully customizable. If you want to change how things
45       are displayed, or even its standard behavior. Take a look at the
46       available customizations. Once you figure out your own preferences,
47       create a configuration file for yourself and Data::Printer will
48       automatically use it!
49
50       That's about it! Feel free to stop reading now and start dumping your
51       data structures! For more information, including feature set, how to
52       create filters, and general tips, just keep reading :)
53
54       Oh, if you are just experimenting and/or don't want to use a
55       configuration file, you can set all options during initialization,
56       including coloring, indentation and filters!
57
58         use Data::Printer {
59             color => {
60                'regex' => 'blue',
61                'hash'  => 'yellow',
62             },
63             filters => {
64                'DateTime' => sub { $_[0]->ymd },
65                'SCALAR'   => sub { "oh noes, I found a scalar! $_[0]" },
66             },
67         };
68
69       The first "{}" block is just syntax sugar, you can safely omit it if it
70       makes things easier to read:
71
72         use DDP colored => 1;
73
74         use Data::Printer  deparse => 1, sort_keys => 0;
75

FEATURES

77       Here's what Data::Printer has to offer to Perl developers, out of the
78       box:
79
80       ·   Very sane defaults (I hope!)
81
82       ·   Highly customizable (in case you disagree with me :)
83
84       ·   Colored output by default
85
86       ·   Human-friendly output, with array index and custom separators
87
88       ·   Full object dumps including methods, inheritance and internals
89
90       ·   Exposes extra information such as tainted data and weak references
91
92       ·   Ability to easily create filters for objects and regular structures
93
94       ·   Ability to load settings from a ".dataprinter" file so you don't
95           have to write anything other than "use DDP;" in your code!
96

RATIONALE

98       Data::Dumper is a fantastic tool, meant to stringify data structures in
99       a way they are suitable for being "eval"'ed back in.
100
101       The thing is, a lot of people keep using it (and similar ones, like
102       Data::Dump) to print data structures and objects on screen for
103       inspection and debugging, and while you can use those modules for that,
104       it doesn't mean you should.
105
106       This is where Data::Printer comes in. It is meant to do one thing and
107       one thing only:
108
109       display Perl variables and objects on screen, properly formatted (to be
110       inspected by a human)
111
112       If you want to serialize/store/restore Perl data structures, this
113       module will NOT help you. Try Storable, Data::Dumper, JSON, or
114       whatever. CPAN is full of such solutions!
115

THE p() FUNCTION

117       Once you load Data::Printer, the "p()" function will be imported into
118       your namespace and available to you. It will pretty-print into STDERR
119       (or any other output target) whatever variable you pass to it.
120
121   Changing output targets
122       By default, "p()" will be set to use STDERR. As of version 0.27, you
123       can set up the 'output' property so Data::Printer outputs to several
124       different places:
125
126       ·   "output => 'stderr'" - Standard error. Same as *STDERR
127
128       ·   "output => 'stdout'" - Standard output. Same as *STDOUT
129
130       ·   "output => $filename" - Appends to filename.
131
132       ·   "output => $file_handle" - Appends to opened handle
133
134       ·   "output => \$scalar" - Appends to that variable's content
135
136   Return Value
137       As of version 0.36, Data::Printer's return value defaults to "pass-
138       through", meaning it will dump the variable to STDERR (or wherever you
139       set the output to) and will return the variable itself.
140
141       If for whatever reason you want to mangle with the output string
142       instead of printing it, you can either use the (also exported) "np()"
143       function which always returns the string to be printed:
144
145           use DDP;
146
147           # move to a string
148           my $string = np @some_array;
149
150           # send as a warning
151           warn np($some_string);
152
153           # output to STDOUT instead of STDERR
154           print np(%some_hash);
155
156       or change the return value to 'dump' and ask for p()'s return value
157       instead: value:
158
159         use DDP return_value => 'dump';
160
161         # move to a string
162         my $string = p @some_array;
163
164         # output to STDOUT instead of STDERR;
165         print p(%some_hash);
166
167       Note that, in this case, Data::Printer will not colorize the returned
168       string unless you explicitly set the "colored" option to 1:
169
170         print p(%some_hash, colored => 1); # now with colors!
171
172       You can - and should - of course, set this during you ""use"" call:
173
174         use Data::Printer colored => 1;
175         print p( %some_hash );  # will be colored
176
177       Or by adding the setting to your ".dataprinter" file.
178
179       As most of Data::Printer, the return value is also configurable. You do
180       this by setting the "return_value" option. There are three options
181       available:
182
183       ·   'dump'
184
185               p %var;               # prints the dump to STDERR (void context)
186               my $string = p %var;  # returns the dump *without* printing
187
188       ·   'void':
189
190               p %var;               # prints the dump to STDERR, never returns.
191               my $string = p %var;  # $string is undef. Data still printed in STDERR
192
193       ·   'pass' (default as of 0.36):
194
195               p %var;               # prints the dump to STDERR, returns %var
196               my %copy = p %var;    # %copy = %var. Data still printed in STDERR
197

COLORS AND COLORIZATION

199       Below are all the available colorizations and their default values.
200       Note that both spellings ('color' and 'colour') will work.
201
202          use Data::Printer {
203            color => {
204               array       => 'bright_white',  # array index numbers
205               number      => 'bright_blue',   # numbers
206               string      => 'bright_yellow', # strings
207               class       => 'bright_green',  # class names
208               method      => 'bright_green',  # method names
209               undef       => 'bright_red',    # the 'undef' value
210               hash        => 'magenta',       # hash keys
211               regex       => 'yellow',        # regular expressions
212               code        => 'green',         # code references
213               glob        => 'bright_cyan',   # globs (usually file handles)
214               vstring     => 'bright_blue',   # version strings (v5.16.0, etc)
215               repeated    => 'white on_red',  # references to seen values
216               caller_info => 'bright_cyan',   # details on what's being printed
217               weak        => 'cyan',          # weak references
218               tainted     => 'red',           # tainted content
219               escaped     => 'bright_red',    # escaped characters (\t, \n, etc)
220
221               # potential new Perl datatypes, unknown to Data::Printer
222               unknown     => 'bright_yellow on_blue',
223            },
224          };
225
226       Don't fancy colors? Disable them with:
227
228         use Data::Printer colored => 0;
229
230       By default, 'colored' is set to "auto", which means Data::Printer will
231       colorize only when not being used to return the dump string, nor when
232       the output (default: STDERR) is being piped. If you're not seeing
233       colors, try forcing it with:
234
235         use Data::Printer colored => 1;
236
237       Also worth noticing that Data::Printer will honor the
238       "ANSI_COLORS_DISABLED" environment variable unless you force a colored
239       output by setting 'colored' to 1.
240
241       Remember to put your preferred settings in the ".dataprinter" file so
242       you never have to type them at all!
243

ALIASING

245       Data::Printer provides the nice, short, "p()" function to dump your
246       data structures and objects. In case you rather use a more explicit
247       name, already have a "p()" function (why?) in your code and want to
248       avoid clashing, or are just used to other function names for that
249       purpose, you can easily rename it:
250
251         use Data::Printer alias => 'Dumper';
252
253         Dumper( %foo );
254

CUSTOMIZATION

256       I tried to provide sane defaults for Data::Printer, so you'll never
257       have to worry about anything other than typing "p( $var )" in your
258       code.  That said, and besides coloring and filtering, there are several
259       other customization options available, as shown below (with default
260       values):
261
262         use Data::Printer {
263             name           => 'var',   # name to display on cyclic references
264             indent         => 4,       # how many spaces in each indent
265             hash_separator => '   ',   # what separates keys from values
266             align_hash     => 1,       # align values in hash
267             colored        => 'auto',  # colorize output (1 for always, 0 for never)
268             index          => 1,       # display array indices
269             multiline      => 1,       # display in multiple lines (see note below)
270             max_depth      => 0,       # how deep to traverse the data (0 for all)
271             sort_keys      => 1,       # sort hash keys
272             deparse        => 0,       # use B::Deparse to expand (expose) subroutines
273             show_tied      => 1,       # expose tied variables
274             show_tainted   => 1,       # expose tainted variables
275             show_unicode   => 0,       # show unicode flag if it exists
276             show_weak      => 1,       # expose weak references
277             show_readonly  => 0,       # expose scalar variables marked as read-only
278             show_lvalue    => 1,       # expose lvalue types
279             print_escapes  => 0,       # print non-printable chars as "\n", "\t", etc.
280             escape_chars   => 'none',  # escape chars into \x{...} form.  Values are
281                                        # "none", "nonascii", "nonlatin1", "all"
282             quote_keys     => 'auto',  # quote hash keys (1 for always, 0 for never).
283                                        # 'auto' will quote when key is empty/space-only.
284             scalar_quotes  => '"',     # the quote symbols to enclose scalar values
285             separator      => ',',     # uses ',' to separate array/hash elements
286             end_separator  => 0,       # prints the separator after last element in array/hash.
287                                        # the default is 0 that means not to print
288
289             caller_info    => 0,       # include information on what's being printed
290             use_prototypes => 1,       # allow p(%foo), but prevent anonymous data
291             return_value   => 'dump',  # what should p() return? See 'Return Value' above.
292             output         => 'stderr',# where to print the output. See
293                                        # 'Changing output targets' above.
294
295             class_method   => '_data_printer', # make classes aware of Data::Printer
296                                                # and able to dump themselves.
297
298             class => {
299                 internals  => 1,       # show internal data structures of classes
300
301                 inherited  => 'none',  # show inherited methods,
302                                        # can also be 'all', 'private', or 'public'.
303
304                 universal  => 1,       # include UNIVERSAL methods in inheritance list
305
306                 parents    => 1,       # show parents, if there are any
307                 linear_isa => 'auto',  # show the entire @ISA, linearized, whenever
308                                        # the object has more than one parent. Can
309                                        # also be set to 1 (always show) or 0 (never).
310
311                 expand     => 1,       # how deep to traverse the object (in case
312                                        # it contains other objects). Defaults to
313                                        # 1, meaning expand only itself. Can be any
314                                        # number, 0 for no class expansion, and 'all'
315                                        # to expand everything.
316
317                 sort_methods => 1,     # sort public and private methods
318
319                 show_methods => 'all'  # method list. Also 'none', 'public', 'private'
320             },
321         };
322
323       Note: setting "multiline" to 0 will also set "index" and "indent" to 0.
324

FILTERS

326       Data::Printer offers you the ability to use filters to override any
327       kind of data display. The filters are placed on a hash, where keys are
328       the types - or class names - and values are anonymous subs that receive
329       two arguments: the item itself as first parameter, and the properties
330       hashref (in case your filter wants to read from it). This lets you
331       quickly override the way Data::Printer handles and displays data types
332       and, in particular, objects.
333
334         use Data::Printer filters => {
335                   'DateTime'      => sub { $_[0]->ymd },
336                   'HTTP::Request' => sub { $_[0]->uri },
337         };
338
339       Perl types are named as "ref" calls them: SCALAR, ARRAY, HASH, REF,
340       CODE, Regexp and GLOB. As for objects, just use the class' name, as
341       shown above.
342
343       As of version 0.13, you may also use the '-class' filter, which will be
344       called for all non-perl types (objects).
345
346       Your filters are supposed to return a defined value (usually, the
347       string you want to print). If you don't, Data::Printer will let the
348       next filter of that same type have a go, or just fallback to the
349       defaults. You can also use an array reference to pass more than one
350       filter for the same type or class.
351
352       Note: If you plan on calling "p()" from within an inline filter, please
353       make sure you are passing only REFERENCES as arguments. See "CAVEATS"
354       below.
355
356       You may also like to specify standalone filter modules. Please see
357       Data::Printer::Filter for further information on a more powerful filter
358       interface for Data::Printer, including useful filters that are shipped
359       as part of this distribution.
360

MAKING YOUR CLASSES DDP-AWARE (WITHOUT ADDING ANY DEPS)

362       Whenever printing the contents of a class, Data::Printer first checks
363       to see if that class implements a sub called '_data_printer' (or
364       whatever you set the "class_method" option to in your settings, see
365       "CUSTOMIZATION" below).
366
367       If a sub with that exact name is available in the target object,
368       Data::Printer will use it to get the string to print instead of making
369       a regular class dump.
370
371       This means you could have the following in one of your classes:
372
373         sub _data_printer {
374             my ($self, $properties) = @_;
375             return 'Hey, no peeking! But foo contains ' . $self->foo;
376         }
377
378       Notice you don't have to depend on Data::Printer at all, just write
379       your sub and it will use that to pretty-print your objects.
380
381       If you want to use colors and filter helpers, and still not add
382       Data::Printer to your dependencies, remember you can import them during
383       runtime:
384
385         sub _data_printer {
386             require Data::Printer::Filter;
387             Data::Printer::Filter->import;
388
389             # now we have 'indent', outdent', 'linebreak', 'p' and 'colored'
390             my ($self, $properties) = @_;
391             ...
392         }
393
394       Having a filter for that particular class will of course override this
395       setting.
396

CONFIGURATION FILE (RUN CONTROL)

398       Data::Printer tries to let you easily customize as much as possible
399       regarding the visualization of your data structures and objects.  But
400       we don't want you to keep repeating yourself every time you want to use
401       it!
402
403       To avoid this, you can simply create a file called ".dataprinter" in
404       your home directory (usually "/home/username" in Linux), and put your
405       configuration hash reference in there.
406
407       This way, instead of doing something like:
408
409          use Data::Printer {
410            colour => {
411               array => 'bright_blue',
412            },
413            filters => {
414                'Catalyst::Request' => sub {
415                    my $req = shift;
416                    return "Cookies: " . p($req->cookies)
417                },
418            },
419          };
420
421       You can create a .dataprinter file that looks like this:
422
423          {
424            colour => {
425               array => 'bright_blue',
426            },
427            filters => {
428                'Catalyst::Request' => sub {
429                    my $req = shift;
430                    return "Cookies: " . p($req->cookies)
431                },
432            },
433          };
434
435       Note that all we did was remove the "use Data::Printer" bit when
436       writing the ".dataprinter" file. From then on all you have to do while
437       debugging scripts is:
438
439         use Data::Printer;
440
441       and it will load your custom settings every time :)
442
443   Loading RC files in custom locations
444       If your RC file is somewhere other than ".dataprinter" in your home
445       dir, you can load whichever file you want via the 'rc_file' parameter:
446
447         use Data::Printer rc_file => '/path/to/my/rcfile.conf';
448
449       You can even set this to undef or to a non-existing file to disable
450       your RC file at will.
451
452       The RC file location can also be specified with the "DATAPRINTERRC"
453       environment variable. Using "rc_file" in code will override the
454       environment variable.
455
456   RC File Security
457       The ".dataprinter" RC file is nothing but a Perl hash that gets
458       "eval"'d back into the code. This means that whatever is in your RC
459       file WILL BE INTERPRETED BY PERL AT RUNTIME.  This can be quite
460       worrying if you're not the one in control of the RC file.
461
462       For this reason, Data::Printer takes extra precaution before loading
463       the file:
464
465       ·   The file has to be in your home directory unless you specifically
466           point elsewhere via the '"rc_file"' property or the DATAPRINTERRC
467           environment variable;
468
469       ·   The file must be a plain file, never a symbolic link, named pipe or
470           socket;
471
472       ·   The file must be owned by you (i.e. the effective user id that ran
473           the script using Data::Printer);
474
475       ·   The file must be read-only for everyone but your user.  This
476           usually means permissions 0644, 0640 or 0600 in Unix-like systems.
477           THIS IS NOT CHECKED IN WIN32;
478
479       ·   The file will NOT be loaded in Taint mode, unless you specifically
480           load Data::Printer with the 'allow_tainted' option set to true. And
481           even if you do that, Data::Printer will still issue a warning
482           before loading the file. But seriously, don't do that.
483
484       Failure to comply with the security rules above will result in the RC
485       file not being loaded (likely with a warning on what went wrong).
486

THE "DDP" PACKAGE ALIAS

488       You're likely to add/remove Data::Printer from source code being
489       developed and debugged all the time, and typing it might feel too long.
490       Because of this, the 'DDP' package is provided as a shorter alias to
491       Data::Printer:
492
493          use DDP;
494          p %some_var;
495

CALLER INFORMATION

497       If you set caller_info to a true value, Data::Printer will prepend
498       every call with an informational message. For example:
499
500         use Data::Printer caller_info => 1;
501
502         my $var = 42;
503         p $var;
504
505       will output something like:
506
507         Printing in line 4 of myapp.pl:
508         42
509
510       The default message is 'Printing in line __LINE__ of __FILENAME__:'.
511       The special strings "__LINE__", "__FILENAME__" and "__PACKAGE__" will
512       be interpolated into their according value so you can customize them at
513       will:
514
515         use Data::Printer
516           caller_info => 1,
517           caller_message => "Okay, __PACKAGE__, let's dance!"
518           color => {
519               caller_info => 'bright_red',
520           };
521
522       As shown above, you may also set a color for "caller_info" in your
523       color hash. Default is cyan.
524

EXPERIMENTAL FEATURES

526       The following are volatile parts of the API which are subject to change
527       at any given version. Use them at your own risk.
528
529   Local Configuration (experimental!)
530       You can override global configurations by writing them as the second
531       parameter for p(). For example:
532
533         p( %var, color => { hash => 'green' } );
534
535   Filter classes
536       As of Data::Printer 0.11, you can create complex filters as a separate
537       module. Those can even be uploaded to CPAN and used by other people!
538       See Data::Printer::Filter for further information.
539

CAVEATS

541       You can't pass more than one variable at a time.
542
543          p($foo, $bar); # wrong
544          p($foo);       # right
545          p($bar);       # right
546
547       You can't use it in variable declarations (it will most likely not do
548       what you want):
549
550           p my @array = qw(a b c d);         # wrong
551           my @array = qw(a b c d); p @array; # right
552
553       The default mode is to use prototypes, in which you are supposed to
554       pass variables, not anonymous structures:
555
556          p( { foo => 'bar' } ); # wrong
557
558          p %somehash;        # right
559          p $hash_ref;        # also right
560
561       To pass anonymous structures, set "use_prototypes" option to 0. But
562       remember you'll have to pass your variables as references:
563
564          use Data::Printer use_prototypes => 0;
565
566          p( { foo => 'bar' } ); # was wrong, now is right.
567
568          p( %foo  ); # was right, but fails without prototypes
569          p( \%foo ); # do this instead
570
571       If you are using inline filters, and calling p() (or whatever name you
572       aliased it to) from inside those filters, you must pass the arguments
573       to "p()" as a reference:
574
575         use Data::Printer {
576             filters => {
577                 ARRAY => sub {
578                     my $listref = shift;
579                     my $string = '';
580                     foreach my $item (@$listref) {
581                         $string .= p( \$item );      # p( $item ) will not work!
582                     }
583                     return $string;
584                 },
585             },
586         };
587
588       This happens because your filter function is compiled before
589       Data::Printer itself loads, so the filter does not see the function
590       prototype. As a way to avoid unpleasant surprises, if you forget to
591       pass a reference, Data::Printer will generate an exception for you with
592       the following message:
593
594           'When calling p() without prototypes, please pass arguments as references'
595
596       Another way to avoid this is to use the much more complete
597       Data::Printer::Filter interface for standalone filters.
598

EXTRA TIPS

600   Circumventing prototypes
601       The "p()" function uses prototypes by default, allowing you to say:
602
603         p %var;
604
605       instead of always having to pass references, like:
606
607         p \%var;
608
609       There are cases, however, where you may want to pass anonymous
610       structures, like:
611
612         p { foo => $bar };   # this blows up, don't use
613
614       and because of prototypes, you can't. If this is your case, just set
615       "use_prototypes" option to 0. Note, with this option, you will have to
616       pass your variables as references:
617
618         use Data::Printer use_prototypes => 0;
619
620          p { foo => 'bar' }; # doesn't blow up anymore, works just fine.
621
622          p %var;  # but now this blows up...
623          p \%var; # ...so do this instead
624
625          p [ $foo, $bar, \@baz ]; # this way you can even pass
626                                   # several variables at once
627
628       Versions prior to 0.17 don't have the "use_prototypes" option. If
629       you're stuck in an older version you can write "&p()" instead of "p()"
630       to circumvent prototypes and pass elements (including anonymous
631       variables) as REFERENCES. This notation, however, requires enclosing
632       parentheses:
633
634         &p( { foo => $bar } );        # this is ok, use at will
635         &p( \"DEBUGGING THIS BIT" );  # this works too
636
637       Or you could just create a very simple wrapper function:
638
639         sub pp { p @_ };
640
641       And use it just as you use "p()".
642
643   Minding the return value of p()
644       (contributed by Matt S. Trout (mst))
645
646       There is a reason why explicit return statements are recommended unless
647       you know what you're doing. By default, Data::Printer's return value
648       depends on how it was called. When not in void context, it returns the
649       serialized form of the dump.
650
651       It's tempting to trust your own p() calls with that approach, but if
652       this is your last statement in a function, you should keep in mind your
653       debugging code will behave differently depending on how your function
654       was called!
655
656       To prevent that, set the "return_value" property to either 'void' or
657       'pass'. You won't be able to retrieve the dumped string but, hey, who
658       does that anyway :)
659
660       Assuming you have set the pass-through ('pass') property in your
661       ".dataprinter" file, another stunningly useful thing you can do with it
662       is change code that says:
663
664          return $obj->foo;
665
666       with:
667
668          use DDP;
669
670          return p $obj->foo;
671
672       You can even add it to chained calls if you wish to see the dump of a
673       particular state, changing this:
674
675          $obj->foo->bar->baz;
676
677       to:
678
679          $obj->foo->DDP::p->bar->baz
680
681       And things will "Just Work".
682
683   Using p() in some/all of your loaded modules
684       (contributed by Matt S. Trout (mst))
685
686       While debugging your software, you may want to use Data::Printer in
687       some or all loaded modules and not bother having to load it in each and
688       every one of them. To do this, in any module loaded by "myapp.pl",
689       simply write:
690
691         ::p( @myvar );  # note the '::' in front of p()
692
693       Then call your program like:
694
695         perl -MDDP myapp.pl
696
697       This also has the great advantage that if you leave one p() call in by
698       accident, it will fail without the -M, making it easier to spot :)
699
700       If you really want to have p() imported into your loaded modules, use
701       the next tip instead.
702
703   Adding p() to all your loaded modules
704       (contributed by Árpád Szász)
705
706       If you wish to automatically add Data::Printer's "p()" function to
707       every loaded module in you app, you can do something like this to your
708       main program:
709
710           BEGIN {
711               {
712                   no strict 'refs';
713                   require Data::Printer;
714                   my $alias = 'p';
715                   foreach my $package ( keys %main:: ) {
716                       if ( $package =~ m/::$/ ) {
717                           *{ $package . $alias } = \&Data::Printer::p;
718                       }
719                   }
720               }
721           }
722
723       WARNING This will override all locally defined subroutines/methods that
724       are named "p", if they exist, in every loaded module. If you already
725       have a subroutine named '"p()"', be sure to change $alias to something
726       custom.
727
728       If you rather avoid namespace manipulation altogether, use the previous
729       tip instead.
730
731   Using Data::Printer from the Perl debugger
732       (contributed by Árpád Szász and Marcel Grünauer (hanekomu))
733
734       With DB::Pluggable, you can easily set the perl debugger to use
735       Data::Printer to print variable information, replacing the debugger's
736       standard "p()" function. All you have to do is add these lines to your
737       ".perldb" file:
738
739         use DB::Pluggable;
740         DB::Pluggable->run_with_config( \'[DataPrinter]' );  # note the '\'
741
742       Then call the perl debugger as you normally would:
743
744         perl -d myapp.pl
745
746       Now Data::Printer's "p()" command will be used instead of the
747       debugger's!
748
749       See perldebug for more information on how to use the perl debugger, and
750       DB::Pluggable for extra functionality and other plugins.
751
752       If you can't or don't wish to use DB::Pluggable, or simply want to keep
753       the debugger's "p()" function and add an extended version using
754       Data::Printer (let's call it "px()" for instance), you can add these
755       lines to your ".perldb" file instead:
756
757           $DB::alias{px} = 's/px/DB::px/';
758           sub px {
759               my $expr = shift;
760               require Data::Printer;
761               print Data::Printer::p($expr);
762           }
763
764       Now, inside the Perl debugger, you can pass as reference to "px"
765       expressions to be dumped using Data::Printer.
766
767   Using Data::Printer in a perl shell (REPL)
768       Some people really enjoy using a REPL shell to quickly try Perl code.
769       One of the most famous ones out there is Devel::REPL. If you use it,
770       now you can also see its output with Data::Printer!
771
772       Just install Devel::REPL::Plugin::DataPrinter and add the following
773       line to your re.pl configuration file (usually ".re.pl/repl.rc" in your
774       home dir):
775
776         load_plugin('DataPrinter');
777
778       The next time you run "re.pl", it should dump all your REPL using
779       Data::Printer!
780
781   Easily rendering Data::Printer's output as HTML
782       To turn Data::Printer's output into HTML, you can do something like:
783
784         use HTML::FromANSI;
785         use Data::Printer;
786
787         my $html_output = ansi2html( p($object, colored => 1) );
788
789       In the example above, the $html_output variable contains the HTML
790       escaped output of "p($object)", so you can print it for later
791       inspection or render it (if it's a web app).
792
793   Using Data::Printer with Template Toolkit
794       (contributed by Stephen Thirlwall (sdt))
795
796       If you use Template Toolkit and want to dump your variables using
797       Data::Printer, install the Template::Plugin::DataPrinter module and
798       load it in your template:
799
800          [% USE DataPrinter %]
801
802       The provided methods match those of "Template::Plugin::Dumper":
803
804          ansi-colored dump of the data structure in "myvar":
805          [% DataPrinter.dump( myvar ) %]
806
807          html-formatted, colored dump of the same data structure:
808          [% DataPrinter.dump_html( myvar ) %]
809
810       The module allows several customization options, even letting you load
811       it as a complete drop-in replacement for Template::Plugin::Dumper so
812       you don't even have to change your previous templates!
813
814   Unified interface for Data::Printer and other debug formatters
815       (contributed by Kevin McGrath (catlgrep))
816
817       If you are porting your code to use Data::Printer instead of
818       Data::Dumper or similar, you can just replace:
819
820         use Data::Dumper;
821
822       with:
823
824         use Data::Printer alias => 'Dumper';
825         # use Data::Dumper;
826
827       making sure to provide Data::Printer with the proper alias for the
828       previous dumping function.
829
830       If, however, you want a really unified approach where you can easily
831       flip between debugging outputs, use Any::Renderer and its plugins, like
832       Any::Renderer::Data::Printer.
833
834   Printing stack traces with arguments expanded using Data::Printer
835       (contributed by Sergey Aleynikov (randir))
836
837       There are times where viewing the current state of a variable is not
838       enough, and you want/need to see a full stack trace of a function call.
839
840       The Devel::PrettyTrace module uses Data::Printer to provide you just
841       that. It exports a "bt()" function that pretty-prints detailed
842       information on each function in your stack, making it easier to spot
843       any issues!
844
845   Troubleshooting apps in real time without changing a single line of your
846       code
847       (contributed by Marcel Grünauer (hanekomu))
848
849       dip is a dynamic instrumentation framework for troubleshooting Perl
850       programs, similar to DTrace
851       <http://opensolaris.org/os/community/dtrace/>.  In a nutshell, "dip"
852       lets you create probes for certain conditions in your application that,
853       once met, will perform a specific action. Since it uses Aspect-oriented
854       programming, it's very lightweight and you only pay for what you use.
855
856       "dip" can be very useful since it allows you to debug your software
857       without changing a single line of your original code. And Data::Printer
858       comes bundled with it, so you can use the "p()" function to view your
859       data structures too!
860
861          # Print a stack trace every time the name is changed,
862          # except when reading from the database.
863          dip -e 'before { print longmess(p $_->{args}[1]) if $_->{args}[1] }
864            call "MyObj::name" & !cflow("MyObj::read")' myapp.pl
865
866       You can check you dip's own documentation for more information and
867       options.
868
869   Sample output for color fine-tuning
870       (contributed by Yanick Champoux (yanick))
871
872       The "examples/try_me.pl" file included in this distribution has a
873       sample dump with a complex data structure to let you quickly test color
874       schemes.
875
876   creating fiddling filters
877       (contributed by dirk)
878
879       Sometimes, you may want to take advantage of Data::Printer's original
880       dump, but add/change some of the original data to enhance your
881       debugging ability.  Say, for example, you have an "HTTP::Response"
882       object you want to print but the content is encoded. The basic
883       approach, of course, would be to just dump the decoded content:
884
885         use DDP filter {
886           'HTTP::Response' => sub { p( \shift->decoded_content, %{shift} );
887         };
888
889       But what if you want to see the rest of the original object? Dumping it
890       would be a no-go, because you would just recurse forever in your own
891       filter.
892
893       Never fear! When you create a filter in Data::Printer, you're not
894       replacing the original one, you're just stacking yours on top of it. To
895       forward your data to the original filter, all you have to do is return
896       an undefined value. This means you can rewrite your "HTTP::Response"
897       filter like so, if you want:
898
899         use DDP filters => {
900           'HTTP::Response' => sub {
901             my ($res, $p) = @_;
902
903             # been here before? Switch to original handler
904             return if exists $res->{decoded_content};
905
906             # first timer? Come on in!
907             my $clone = $res->clone;
908             $clone->{decoded_content} = $clone->decoded_content;
909             return p($clone, %$p);
910           }
911         };
912
913       And voilà! Your fiddling filter now works like a charm :)
914

BUGS

916       If you find any, please file a bug report.
917

SEE ALSO

919       Data::Dumper
920
921       Data::Dump
922
923       Data::Dumper::Concise
924
925       Data::Dump::Streamer
926
927       Data::PrettyPrintObjects
928
929       Data::TreeDumper
930

AUTHOR

932       Breno G. de Oliveira "<garu at cpan.org>"
933

CONTRIBUTORS

935       Many thanks to everyone that helped design and develop this module with
936       patches, bug reports, wishlists, comments and tests. They are
937       (alphabetically):
938
939       ·   Adam Rosenstein
940
941       ·   Allan Whiteford
942
943       ·   Andreas König
944
945       ·   Andy Bach
946
947       ·   Árpád Szász
948
949       ·   Athanasios Douitsis (aduitsis)
950
951       ·   Baldur Kristinsson
952
953       ·   brian d foy
954
955       ·   Chad Granum (exodist)
956
957       ·   Chris Prather (perigrin)
958
959       ·   Dave Mitchell
960
961       ·   David D Lowe (Flimm)
962
963       ·   David Golden (xdg)
964
965       ·   David Precious (bigpresh)
966
967       ·   David Raab
968
969       ·   Damien Krotkine (dams)
970
971       ·   Denis Howe
972
973       ·   Dotan Dimet
974
975       ·   Eden Cardim (edenc)
976
977       ·   Elliot Shank (elliotjs)
978
979       ·   Fernando Corrêa (SmokeMachine)
980
981       ·   Fitz Elliott
982
983       ·   Frew Schmidt (frew)
984
985       ·   Ivan Bessarabov (bessarabv)
986
987       ·   J Mash
988
989       ·   Jay Allen (jayallen)
990
991       ·   Jesse Luehrs (doy)
992
993       ·   Jim Keenan (jkeenan)
994
995       ·   Joel Berger (jberger)
996
997       ·   John S. Anderson (genehack)
998
999       ·   Kartik Thakore (kthakore)
1000
1001       ·   Kevin Dawson (bowtie)
1002
1003       ·   Kevin McGrath (catlgrep)
1004
1005       ·   Kip Hampton (ubu)
1006
1007       ·   Marcel Grünauer (hanekomu)
1008
1009       ·   Marco Masetti (grubert65)
1010
1011       ·   Mark Fowler (Trelane)
1012
1013       ·   Matt S. Trout (mst)
1014
1015       ·   Maxim Vuets
1016
1017       ·   Michael Conrad
1018
1019       ·   Mike Doherty (doherty)
1020
1021       ·   Nuba Princigalli (nuba)
1022
1023       ·   Olaf Alders (oalders)
1024
1025       ·   Paul Evans (LeoNerd)
1026
1027       ·   Pedro Melo (melo)
1028
1029       ·   Przemysław Wesołek (jest)
1030
1031       ·   Rebecca Turner (iarna)
1032
1033       ·   Renato Cron (renatoCRON)
1034
1035       ·   Ricardo Signes (rjbs)
1036
1037       ·   Rob Hoelz (hoelzro)
1038
1039       ·   sawyer
1040
1041       ·   Sebastian Willing (Sewi)
1042
1043       ·   Sergey Aleynikov (randir)
1044
1045       ·   Stanislaw Pusep (syp)
1046
1047       ·   Stephen Thirlwall (sdt)
1048
1049       ·   sugyan
1050
1051       ·   Tatsuhiko Miyagawa (miyagawa)
1052
1053       ·   Thomas Sibley (tsibley)
1054
1055       ·   Tim Heaney (oylenshpeegul)
1056
1057       ·   Torsten Raudssus (Getty)
1058
1059       ·   Tokuhiro Matsuno (tokuhirom)
1060
1061       ·   vividsnow
1062
1063       ·   Wesley Dal`Col (blabos)
1064
1065       ·   Yanick Champoux (yanick)
1066
1067       ·   Zefram
1068
1069       If I missed your name, please drop me a line!
1070
1072       Copyright 2011-2017 Breno G. de Oliveira "<garu at cpan.org>". All
1073       rights reserved.
1074
1075       This module is free software; you can redistribute it and/or modify it
1076       under the same terms as Perl itself. See perlartistic.
1077

DISCLAIMER OF WARRANTY

1079       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
1080       FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
1081       WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
1082       PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
1083       EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
1084       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
1085       ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
1086       YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
1087       NECESSARY SERVICING, REPAIR, OR CORRECTION.
1088
1089       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
1090       WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
1091       REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
1092       TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
1093       CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
1094       SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
1095       RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
1096       FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
1097       SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
1098       DAMAGES.
1099
1100
1101
1102perl v5.30.1                      2020-01-29                  Data::Printer(3)
Impressum