Codebase list libdata-printer-perl / 1d5ebb2
doc updates Breno G. de Oliveira 3 years ago
1 changed file(s) with 45 addition(s) and 32 deletion(s). Raw diff Collapse all Expand all
+45
-32
lib/Data/Printer.pm less more
239239
240240 =head1 NAME
241241
242 Data::Printer - colored & full-featured pretty-print of Perl data structures and objects
242 Data::Printer - colored & full-featured pretty print of Perl data structures and objects
243243
244244 =head1 SYNOPSIS
245245
257257 # for anonymous array/hash references, use postderef (on perl 5.24 or later):
258258 p [ $one, $two, $three ]->@*;
259259 p { foo => $foo, bar => $bar }->%*;
260
261 # or deref the anonymous ref:
262 p @{[ $one, $two, $three ]};
263 p %{{ foo => $foo, bar => $bar }};
260264
261265 # or put '&' in front of the call:
262266 &p( [ $one, $two, $three ] );
317321
318322 =item * B<< L<Filters|/Filters> for specific data structures and objects >> to make
319323 debugging much, much easier. Includes filters for many popular classes
320 from CPAN like JSON::\*, URI, HTTP::\*, LWP, Digest::\*, DBI and DBIx::Class.
324 from CPAN like JSON::*, URI, HTTP::*, LWP, Digest::*, DBI and DBIx::Class.
321325 printing what really matters to developers debugging code. It also lets you
322326 create your own custom filters easily.
323327
406410 p %some_hash;
407411 p $scalar_or_ref;
408412
409 Note that anonymous structures will only work if you either use postderef
413 Note that anonymous structures will only work if you postderef them:
414
415 p [$foo, $bar, $baz]->@*;
416
417 you may also deref it manually:
418
419 p %{{ foo => $foo }};
420
410421 or prefix C<p()> with C<&>:
411422
412 p [$foo, $bar, $baz]->@*; # postderef
413423 &p( [$foo, $bar, $baz] ); # & (note mandatory parenthesis)
414424
415425 You can pass custom options that will work only on that particular call:
417427 p @var, as => "some label", colorized => 0;
418428 p %var, show_memsize => 1;
419429
420 By default C<p()> will print to STDERR and return the same variable being
430 By default, C<p()> prints to STDERR and returns the same variable being
421431 dumped. This lets you quickly wrap variables with C<p()> without worrying
422432 about changing return values. It means that if you change this:
423433
456466
457467 There are 3 possible ways to customize Data::Printer:
458468
459 1. Creating a C<.dataprinter> file on your home directory, on your
460 project's base directory or wherever you set the C<DATAPRINTERRC>
461 environment variable to.
469 1. B<[RECOMMENDED]> Creating a C<.dataprinter> file either on your home
470 directory or your project's base directory, or both, or wherever you set
471 the C<DATAPRINTERRC> environment variable to.
462472
463473 2. Setting custom properties on module load. This will override any
464 setting from (1) on the namespace (package/module) it was called:
474 setting from your config file on the namespace (package/module) it was called:
465475
466476 use DDP max_depth => 2, deparse => 1;
467477
577587 class.internals = 1
578588
579589
580 =head3 Settings shortcuts
590 =head3 Settings' shortcuts
581591
582592 =over 4
583593
641651 and Moo(se) objects and is even aware of Role::Tiny.
642652
643653 Data::Printer also comes with filter bundles that can be quickly activated
644 to make it easier to debug L<Data::Printer::Filter::ContentType|binary data>
654 to make it easier to debug L<binary data|Data::Printer::Filter::ContentType>
645655 and many popular CPAN modules that handle
646 L<Data::Printer::Filter::DateTime|date and time>,
647 L<Data::Printer::Filter::DB|databases> (yes, even DBIx::Class),
648 L<Data::Printer::Filter::Digest|message digests> like MD5 and SHA1, and
649 L<Data::Printer::Filter::Web|JSON and Web> content like HTTP requests and responses.
656 L<date and time|Data::Printer::Filter::DateTime>,
657 L<databases|Data::Printer::Filter::DB> (yes, even DBIx::Class),
658 L<message digests|Data::Printer::Filter::Digest> like MD5 and SHA1, and
659 L<JSON and Web|Data::Printer::Filter::Web> content like HTTP requests and
660 responses.
650661
651662 So much so we recommend everyone to activate all bundled filters by putting
652663 the following line on your C<.dataprinter> file:
675686
676687 Notice that B<< you can do this without adding Data::Printer as a dependency >>
677688 to your project! Just write your sub and it will be called with the object to
678 be printed and a C<$ddp> object ready for you. See L<Data::Printer::Object> for
679 how to use it to pretty-print your data.
689 be printed and a C<$ddp> object ready for you. See
690 L<< Data::Printer::Object|/Data::Printer::Object/"Methods and Accessors for Filter Writers" >>
691 for how to use it to pretty-print your data.
680692
681693 Finally, if your object implements string overload or provides a method called
682694 "to_string", "as_string" or "stringify", Data::Printer will use it. To disable
699711 p my @array = qw(a b c d); # wrong
700712 my @array = qw(a b c d); p @array; # right
701713
702 On the default mode of C<< use_prototypes = 1 >>, you cannot pass anonymous
703 data:
714 If you pass a nonexistant key/index to DDP using prototypes, they
715 will trigger autovivification:
716
717 use DDP;
718 my %foo;
719 p $foo{bar}; # undef, but will create the 'bar' key (with undef)
720
721 my @x;
722 p $x[5]; # undef, but will initialize the array with 5 elements (all undef)
723
724 Finally, as mentioned before, you cannot pass anonymous references on the
725 default mode of C<< use_prototypes = 1 >>:
704726
705727 p { foo => 1 }; # wrong!
706728 p %{{ foo => 1 }}; # right
709731 sub pp { p @_ }; # wrapping it also lets you use anonymous data.
710732
711733 use DDP use_prototypes => 0;
712 p { foo => 1 }; # works, but now you must always pass a reference to p()
713
714 If you pass a nonexistant key/index to DDP using prototypes, they
715 will trigger autovivification:
716
717 use DDP;
718 my %foo;
719 p $foo{bar}; # undef, but will create the 'bar' key (with undef)
720
721 my @x;
722 p $x[5]; # undef, but will initialize the array with 5 elements (all undef)
734 p { foo => 1 }; # works, but now p(@foo) will fail, you must always pass a ref,
735 # e.g. p(\@foo)
723736
724737 =head1 BACKWARDS INCOMPATIBLE CHANGES
725738
737750 =item * 1.00 - new C<.dataprinter> file format.
738751 I<< This should only affect you if you have a C<.dataprinter> file. >>
739752 The change was required to avoid calling C<eval> on potentially tainted/unknown
740 code. It also provided a much clearer interface.
753 code. It also provided a much cleaner interface.
741754
742755 =item * 1.00 - new way of creating external filters.
743756 I<< This only affects you if you write or use external filters. >>
754767 C<< filters => [{ ... }] >> and you must replace C<< -external => [1,2] >>
755768 with C<< filters => [1, 2] >>, or C<< filters => [1, 2, {...}] >> if you
756769 also have inline filters. This allowed us much more power and flexibility
757 with filters, and hopefully also makes things cleaner.
770 with filters, and hopefully also makes things clearer.
758771
759772 =item * 0.36 - C<p()>'s default return value changed from 'dump' to 'pass'.
760773 This was a very important change to ensure chained calls and to prevent