p()

    p @some_array;
    p %some_hash;
    p $scalar_or_ref;

Note that anonymous structures will only work if you postderef them:

    p [$foo, $bar, $baz]->@*;

you may also deref it manually:

    p %{{ foo => $foo }};

or prefix "p()" with "&":

    &p( [$foo, $bar, $baz] );    # & (note mandatory parenthesis)

You can pass custom options that will work only on that particular call:

    p @var, as => "some label", colorized => 0;
    p %var, show_memsize => 1;

By default, "p()" prints to STDERR and returns the same variable being dumped. This lets you quickly wrap variables with "p()" without worrying about changing return values. It means that if you change this:

    sub foo { my $x = shift + 13; $x }

to this:

    sub foo { my $x = shift + 13; p($x) }

The function will still return $x after printing the contents. This form of handling data even allows method chaining, so if you want to inspect what's going on in the middle of this:

    $object->foo->bar->baz;

You can just add "DDP::p" anywhere:

    $object->foo->DDP::p->bar->baz; # what happens to $object after ->foo?

Check out the customization quick reference section below for all available options, including changing the return type, output target and a lot more.

np()

The .dataprinter configuration file

    # global settings (note that only full line comments are accepted)
    max_depth       = 1
    theme           = Monokai
    class.stringify = 0

    # use quotes if you want spaces to be significant:
    hash_separator  = " => "

    # You can set rules that apply only to a specific
    # caller module (in this case, MyApp::Some::Module):
    [MyApp::Some::Module]
    max_depth    = 2
    class.expand = 0
    escape_chars = nonlatin1

    [MyApp::Other::Module]
    multiline = 0
    output    = /var/log/myapp/debug.data

Note that if you set custom properties as arguments to "p()" or "np()", you should group suboptions as a hashref. So while the ".dataprinter" file has ""class.expand = 0"" and ""class.inherited = none"", the equivalent code is ""class => { expand => 0, inherited => 'none' }"".

Properties Quick Reference

    # scalar options
    show_tainted      = 1
    show_unicode      = 1
    show_lvalue       = 1
    print_escapes     = 0
    scalar_quotes     = "
    escape_chars      = none
    string_max        = 4096
    string_preserve   = begin
    string_overflow   = '(...skipping __SKIPPED__ chars...)'
    unicode_charnames = 0

    # array options
    array_max      = 100
    array_preserve = begin
    array_overflow = '(...skipping __SKIPPED__ items...)'
    index          = 1

    # hash options
    hash_max       = 100
    hash_preserve  = begin
    hash_overflow  = '(...skipping __SKIPPED__ keys...)'
    hash_separator = '   '
    align_hash     = 1
    sort_keys      = 1
    quote_keys     = auto

    # general options
    name           = var
    return_value   = pass
    output         = stderr
    use_prototypes = 1
    indent         = 4
    show_readonly  = 1
    show_tied      = 1
    show_dualvar   = lax
    show_weak      = 1
    show_refcount  = 0
    show_memsize   = 0
    memsize_unit   = auto
    separator      = ,
    end_separator  = 0
    caller_info    = 0
    caller_message = 'Printing in line __LINE__ of __FILENAME__'
    max_depth      = 0
    deparse        = 0
    alias          = p
    warnings       = 1

    # colorization (see Colors & Themes below)
    colored = auto
    theme   = Material

    # object output
    class_method             = _data_printer
    class.parents            = 1
    class.linear_isa         = auto
    class.universal          = 1
    class.expand             = 1
    class.stringify          = 1
    class.show_reftype       = 0
    class.show_overloads     = 1
    class.show_methods       = all
    class.sort_methods       = 1
    class.inherited          = none
    class.format_inheritance = string
    class.parent_filters     = 1
    class.internals          = 1

Settings' shortcuts

• as - prints a string before the dump. So:

      p $some_var, as => 'here!';
      

  is a shortcut to:

      p $some_var, caller_info => 1, caller_message => 'here!';
      

• multiline - lets you create shorter dumps. By setting it to 0, we use a single space as linebreak and disable the array index. Setting it to 1 (the default) goes back to using "\n" as linebreak and restore whatever array index you had originally.
• fulldump - when set to 1, disables all max string/hash/array values. Use this to generate complete (full) dumps of all your content, which is trimmed by default.

Colors & Themes

See Data::Printer::Theme for the full list of labels, ways to represent and customize colors, and even how to group them in your own custom theme.

The colorization is set by the "colored" property. It can be set to 0 (never colorize), 1 (always colorize) or 'auto' (the default), which will colorize "p()" only when there is no "ANSI_COLORS_DISABLED" environment variable, the output is going to the terminal (STDOUT or STDERR) and your terminal actually supports colors.

Profiles

    use DDP profile => 'ProfileName';

See Data::Printer::Profile for all the ways to load a profile, a list of available profiles and how to make one yourself.

Filters

Data::Printer also comes with filter bundles that can be quickly activated to make it easier to debug binary data and many popular CPAN modules that handle date and time, databases (yes, even DBIx::Class), message digests like MD5 and SHA1, and JSON and Web content like HTTP requests and responses.

So much so we recommend everyone to activate all bundled filters by putting the following line on your ".dataprinter" file:

    filters = ContentType, DateTime, DB, Digest, Web

Creating your custom filters is very easy, and you're encouraged to upload them to CPAN. There are many options available under the "Data::Printer::Filter::*" namespace. Check Data::Printer::Filter for more information!

Making your classes DDP-aware (without adding any dependencies!)

This means you could have the following in one of your classes:

  sub _data_printer {
      my ($self, $ddp) = @_;
      return 'Hey, no peeking! But foo contains ' . $self->foo;
  }

Notice that you can do this without adding Data::Printer as a dependency to your project! Just write your sub and it will be called with the object to be printed and a $ddp object ready for you. See Data::Printer::Object for how to use it to pretty-print your data.

Finally, if your object implements string overload or provides a method called "to_string", "as_string" or "stringify", Data::Printer will use it. To disable this behaviour, set "class.stringify = 0" on your ".dataprinter" file, or call p() with "class => { stringify => 0 }".

Loading a filter for that particular class will of course override these settings.

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

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 advantage that if you leave one p() call in by accident, it will trigger a compile-time failure 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

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:

    BEGIN {
        {
            no strict 'refs';
            require Data::Printer;
            my $alias = 'p';
            foreach my $package ( keys %main:: ) {
                if ( $package =~ m/::$/ ) {
                    *{ $package . $alias } = \&Data::Printer::p;
                }
            }
        }
    }

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

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:

  use DB::Pluggable;
  DB::Pluggable->run_with_config( \'[DataPrinter]' );  # note the '\'

Then call the perl debugger as you normally would:

  perl -d myapp.pl

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 want 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:

    $DB::alias{px} = 's/px/DB::px/';
    sub px {
        my $expr = shift;
        require Data::Printer;
        print Data::Printer::p($expr);
    }

Now, inside the Perl debugger, you can pass as reference to "px" expressions to be dumped using Data::Printer.

Using Data::Printer in a perl shell (REPL)

Just install Devel::REPL::Plugin::DataPrinter and add the following line to your re.pl configuration file (usually ".re.pl/repl.rc" in your home dir):

  load_plugin('DataPrinter');

The next time you run "re.pl", it should dump all your REPL using Data::Printer!

Easily rendering Data::Printer's output as HTML

  use HTML::FromANSI;
  use Data::Printer;

  my $html_output = ansi2html( np($object, colored => 1) );

In the example above, the $html_output variable contains the HTML escaped output of "p($object)", so you can print it for later inspection or render it (if it's a web app).

Using Data::Printer with Template Toolkit

If you use Template Toolkit and want to dump your variables using Data::Printer, install the Template::Plugin::DataPrinter module and load it in your template:

   [% USE DataPrinter %]

The provided methods match those of "Template::Plugin::Dumper":

   ansi-colored dump of the data structure in "myvar":
   [% DataPrinter.dump( myvar ) %]

   html-formatted, colored dump of the same data structure:
   [% DataPrinter.dump_html( myvar ) %]

The module allows several customization options, even letting you load it as a complete drop-in replacement for Template::Plugin::Dumper so you don't even have to change your previous templates!

Migrating from Data::Dumper to Data::Printer

  use Data::Dumper;

with something like:

  use Data::Printer;
  sub Dumper { np @_, colored => 1 }

this sub will accept multiple variables just like Data::Dumper.

Unified interface for Data::Printer and other debug formatters

If you want a really unified approach to easily flip between debugging outputs, use Any::Renderer and its plugins, like Any::Renderer::Data::Printer.

Printing stack traces with arguments expanded using Data::Printer

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

dip is a dynamic instrumentation framework for troubleshooting Perl programs, similar to DTrace <http://opensolaris.org/os/community/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(np $_->{args}[1], colored => 1)
   if $_->{args}[1] } call "MyObj::name" & !cflow("MyObj::read")' myapp.pl

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

Sample output for color fine-tuning

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.