Data::Printer is fully customizable. If you want to change how things are displayed, or even its standard behavior. Take a look at the available customizations. Once you figure out your own preferences, create a configuration file for yourself and Data::Printer will automatically use it!

That's about it! Feel free to stop reading now and start dumping your data structures! For more information, including feature set, how to create filters, and general tips, just keep reading :)

Oh, if you are just experimenting and/or don't want to use a configuration file, you can set all options during initialization, including coloring, identation and filters!

The first {} block is just syntax sugar, you can safely ommit it if it makes things easier to read:

use DDP colored => 1;
use Data::Printer deparse => 1, sort_keys => 0;

FEATURES

Here's what Data::Printer has to offer to Perl developers, out of the box:

Very sane defaults (I hope!)

Highly customizable (in case you disagree with me :)

Colored output by default

Human-friendly output, with array index and custom separators

Full object dumps including methods, inheritance and internals

Exposes extra information such as tainted data and weak references

Ability to easily create filters for objects and regular structures

Ability to load settings from a .dataprinter file so you don't have to write anything other than "use DDP;" in your code!

RATIONALE

Data::Dumper is a fantastic tool, meant to stringify data structures in a way they are suitable for being eval'ed back in.

The thing is, a lot of people keep using it (and similar ones, like Data::Dump) to print data structures and objects on screen for inspection and debugging, and while you can use those modules for that, it doesn't mean mean you should.

This is where Data::Printer comes in. It is meant to do one thing and one thing only:

display Perl variables and objects on screen, properly formatted (to be inspected by a human)

If you want to serialize/store/restore Perl data structures, this module will NOT help you. Try Storable, Data::Dumper, JSON, or whatever. CPAN is full of such solutions!

THE p() FUNCTION

Once you load Data::Printer, the p() function will be imported into your namespace and available to you. It will pretty-print into STDERR (or any other output target) whatever variabe you pass to it.

Changing output targets

By default, p() will be set to use STDERR. As of version 0.27, you can set up the 'output' property so Data::Printer outputs to several different places:

output => 'stderr' - Standard error. Same as *STDERR

output => 'stdout' - Standard output. Same as *STDOUT

output => $filename - Appends to filename.

output => $file_handle - Appends to opened handle

output => \$scalar - Appends to that variable's content

Return Value

If for whatever reason you want to mangle with the output string instead of printing it, you can simply ask for a return value:

By default, 'colored' is set to "auto", which means Data::Printer will colorize only when not being used to return the dump string, nor when the output (default: STDERR) is being piped. If you're not seeing colors, try forcing it with:

use Data::Printer colored => 1;

Also worth noticing that Data::Printer will honor the ANSI_COLORS_DISABLED environment variable unless you force a colored output by setting 'colored' to 1.

Remember to put your preferred settings in the .dataprinter file so you never have to type them at all!

ALIASING

Data::Printer provides the nice, short, p() function to dump your data structures and objects. In case you rather use a more explicit name, already have a p() function (why?) in your code and want to avoid clashing, or are just used to other function names for that purpose, you can easily rename it:

use Data::Printer alias => 'Dumper';
Dumper( %foo );

CUSTOMIZATION

I tried to provide sane defaults for Data::Printer, so you'll never have to worry about anything other than typing "p( $var )" in your code. That said, and besides coloring and filtering, there are several other customization options available, as shown below (with default values):

FILTERS

Data::Printer offers you the ability to use filters to override any kind of data display. The filters are placed on a hash, where keys are the types - or class names - and values are anonymous subs that receive two arguments: the item itself as first parameter, and the properties hashref (in case your filter wants to read from it). This lets you quickly override the way Data::Printer handles and displays data types and, in particular, objects.

Perl types are named as ref calls them: SCALAR, ARRAY, HASH, REF, CODE, Regexp and GLOB. As for objects, just use the class' name, as shown above.

As of version 0.13, you may also use the '-class' filter, which will be called for all non-perl types (objects).

Your filters are supposed to return a defined value (usually, the string you want to print). If you don't, Data::Printer will let the next filter of that same type have a go, or just fallback to the defaults. You can also use an array reference to pass more than one filter for the same type or class.

Note: If you plan on calling p() from within an inline filter, please make sure you are passing only REFERENCES as arguments. See "CAVEATS" below.

You may also like to specify standalone filter modules. Please see Data::Printer::Filter for further information on a more powerful filter interface for Data::Printer, including useful filters that are shipped as part of this distribution.

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

Whenever printing the contents of a class, Data::Printer first checks to see if that class implements a sub called '_data_printer' (or whatever you set the "class_method" option to in your settings, see "CUSTOMIZATION" below).

If a sub with that exact name is available in the target object, Data::Printer will use it to get the string to print instead of making a regular class dump.

Having a filter for that particular class will of course override this setting.

CONFIGURATION FILE (RUN CONTROL)

Data::Printer tries to let you easily customize as much as possible regarding the visualization of your data structures and objects. But we don't want you to keep repeating yourself every time you want to use it!

To avoid this, you can simply create a file called .dataprinter in your home directory (usually /home/username in Linux), and put your configuration hash reference in there.

Note that all we did was remove the "use Data::Printer" bit when writing the .dataprinter file. From then on all you have to do while debugging scripts is:

use Data::Printer;

and it will load your custom settings every time :)

Loading RC files in custom locations

If your RC file is somewhere other than .dataprinter in your home dir, you can load whichever file you want via the 'rc_file' parameter:

use Data::Printer rc_file => '/path/to/my/rcfile.conf';

You can even set this to undef or to a non-existing file to disable your RC file at will.

The RC file location can also be specified with the DATAPRINTERRC environment variable. Using rc_file in code will override the environment variable.

RC File Security

The .dataprinter RC file is nothing but a Perl hash that gets eval'd back into the code. This means that whatever is in your RC file WILL BE INTERPRETED BY PERL AT RUNTIME. This can be quite worrying if you're not the one in control of the RC file.

For this reason, Data::Printer takes extra precaution before loading the file:

The file has to be in your home directory unless you specifically point elsewhere via the 'rc_file' property or the DATAPRINTERRC environment variable;

The file must be a plain file, never a symbolic link, named pipe or socket;

The file must be owned by you (i.e. the effective user id that ran the script using Data::Printer);

The file must be read-only for everyone but your user. This usually means permissions 0644, 0640 or 0600 in Unix-like systems. THIS IS NOT CHECKED IN WIN32;

The file will NOT be loaded in Taint mode, unless you specifically load Data::Printer with the 'allow_tainted' option set to true. And even if you do that, Data::Printer will still issue a warning before loading the file. But seriously, don't do that.

Failure to comply with the security rules above will result in the RC file not being loaded (likely with a warning on what went wrong).

THE "DDP" PACKAGE ALIAS

You're likely to add/remove Data::Printer from source code being developed and debugged all the time, and typing it might feel too long. Because of this, the 'DDP' package is provided as a shorter alias to Data::Printer:

use DDP;
p %some_var;

CALLER INFORMATION

If you set caller_info to a true value, Data::Printer will prepend every call with an informational message. For example:

use Data::Printer caller_info => 1;
my $var = 42;
p $var;

will output something like:

Printing in line 4 of myapp.pl:
42

The default message is 'Printing in line __LINE__ of __FILENAME__:'. The special strings __LINE__, __FILENAME__ and __PACKAGE__ will be interpolated into their according value so you can customize them at will:

This happens because your filter function is compiled before Data::Printer itself loads, so the filter does not see the function prototype. As a way to avoid unpleasant surprises, if you forget to pass a reference, Data::Printer will generate an exception for you with the following message:

Another way to avoid this is to use the much more complete Data::Printer::Filter interface for standalone filters.

EXTRA TIPS

Circumventing prototypes

The p() function uses prototypes by default, allowing you to say:

p %var;

instead of always having to pass references, like:

p \%var;

There are cases, however, where you may want to pass anonymous structures, like:

p { foo => $bar }; # this blows up, don't use

and because of prototypes, you can't. If this is your case, just set "use_prototypes" option to 0. Note, with this option, you will have to pass your variables as references:

use Data::Printer use_prototypes => 0;
p { foo => 'bar' }; # doesn't blow up anymore, works just fine.
p %var; # but now this blows up...
p \%var; # ...so do this instead
p [ $foo, $bar, \@baz ]; # this way you can even pass
# several variables at once

Versions prior to 0.17 don't have the "use_prototypes" option. If you're stuck in an older version you can write &p() instead of p() to circumvent prototypes and pass elements (including anonymous variables) as REFERENCES. This notation, however, requires enclosing parentheses:

&p( { foo => $bar } ); # this is ok, use at will
&p( \"DEBUGGING THIS BIT" ); # this works too

Or you could just create a very simple wrapper function:

sub pp { p @_ };

And use it just as you use p().

Minding the return value of p()

(contributed by Matt S. Trout (mst))

There is a reason why explicit return statements are recommended unless you know what you're doing. By default, Data::Printer's return value depends on how it was called. When not in void context, it returns the serialized form of the dump.

It's tempting to trust your own p() calls with that approach, but if this is your last statement in a function, you should keep in mind your debugging code will behave differently depending on how your function was called!

To prevent that, set the return_value property to either 'void' or 'pass'. You won't be able to retrieve the dumped string but, hey, who does that anyway :)

Assuming you have set the pass-through ('pass') property in your .dataprinter file, another stunningly useful thing you can do with it is change code that says:

return $obj->foo;

with:

use DDP;
return p $obj->foo;

You can even add it to chained calls if you wish to see the dump of a particular state, changing this:

$obj->foo->bar->baz;

to:

$obj->foo->DDP::p->bar->baz

And things will "Just Work".

Using p() in some/all of your loaded modules

(contributed by Matt S. Trout (mst))

While debugging your software, you may want to use Data::Printer in some or all loaded modules and not bother having to load it in each and every one of them. To do this, in any module loaded by myapp.pl, simply write:

::p( @myvar ); # note the '::' in front of p()

Then call your program like:

perl -MDDP myapp.pl

This also has the great advantage that if you leave one p() call in by accident, it will fail without the -M, making it easier to spot :)

If you really want to have p() imported into your loaded modules, use the next tip instead.

Adding p() to all your loaded modules

(contributed by Árpád Szász)

If you wish to automatically add Data::Printer's p() function to every loaded module in you app, you can do something like this to your main program:

WARNING This will override all locally defined subroutines/methods that are named p, if they exist, in every loaded module. If you already have a subroutine named 'p()', be sure to change $alias to something custom.

If you rather avoid namespace manipulation altogether, use the previous tip instead.

Using Data::Printer from the Perl debugger

(contributed by Árpád Szász and Marcel Grünauer (hanekomu))

With DB::Pluggable, you can easily set the perl debugger to use Data::Printer to print variable information, replacing the debugger's standard p() function. All you have to do is add these lines to your .perldb file:

Now Data::Printer's p() command will be used instead of the debugger's!

See perldebug for more information on how to use the perl debugger, and DB::Pluggable for extra functionality and other plugins.

If you can't or don't wish to use DB::Pluggable, or simply want to keep the debugger's p() function and add an extended version using Data::Printer (let's call it px() for instance), you can add these lines to your .perldb file instead:

Printing stack traces with arguments expanded using Data::Printer

(contributed by Sergey Aleynikov (randir))

There are times where viewing the current state of a variable is not enough, and you want/need to see a full stack trace of a function call.

The Devel::PrettyTrace module uses Data::Printer to provide you just that. It exports a bt() function that pretty-prints detailed information on each function in your stack, making it easier to spot any issues!

Troubleshooting apps in real time without changing a single line of your code

(contributed by Marcel Grünauer (hanekomu))

dip is a dynamic instrumentation framework for troubleshooting Perl programs, similar to DTrace. In a nutshell, dip lets you create probes for certain conditions in your application that, once met, will perform a specific action. Since it uses Aspect-oriented programming, it's very lightweight and you only pay for what you use.

dip can be very useful since it allows you to debug your software without changing a single line of your original code. And Data::Printer comes bundled with it, so you can use the p() function to view your data structures too!

# Print a stack trace every time the name is changed,
# except when reading from the database.
dip -e 'before { print longmess(p $_->{args}[1]) if $_->{args}[1] }
call "MyObj::name" & !cflow("MyObj::read")' myapp.pl

You can check you dip's own documentation for more information and options.

Sample output for color fine-tuning

(contributed by Yanick Champoux (yanick))

The "examples/try_me.pl" file included in this distribution has a sample dump with a complex data structure to let you quickly test color schemes.

creating fiddling filters

(contributed by dirk)

Sometimes, you may want to take advantage of Data::Printer's original dump, but add/change some of the original data to enhance your debugging ability. Say, for example, you have an HTTP::Response object you want to print but the content is encoded. The basic approach, of course, would be to just dump the decoded content:

But what if you want to see the rest of the original object? Dumping it would be a no-go, because you would just recurse forever in your own filter.

Never fear! When you create a filter in Data::Printer, you're not replacing the original one, you're just stacking yours on top of it. To forward your data to the original filter, all you have to do is return an undefined value. This means you can rewrite your HTTP::Response filter like so, if you want:

LICENSE AND COPYRIGHT

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

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.