view release on metacpan or  search on metacpan

lib/Data/Dmp.pm  view on Meta::CPAN

This document describes version 0.242 of Data::Dmp (from Perl distribution Data-Dmp), released on 2022-08-28.

=head1 SYNOPSIS

 use Data::Dmp; # exports dd() and dmp()
 dd [1, 2, 3]; # prints "[1,2,3]"
 $var = dmp({a => 1}); # -> "{a=>1}"

Print truncated dump (capped at L</$Data::Dmp::OPT_MAX_DUMP_LEN_BEFORE_ELLIPSIS>
characters):

 use Data::Dmp qw(dd_ellipsis dmp_ellipsis);
 dd_ellipsis [1..100];

=head1 DESCRIPTION

Data::Dmp is a Perl dumper like L<Data::Dumper>. It's compact (only about 200
lines of code long), starts fast and does not use any non-core modules except
L<Regexp::Stringify> when dumping regexes. It produces compact single-line
output (similar to L<Data::Dumper::Concise>). It roughly has the same speed as
Data::Dumper (usually a bit faster for smaller structures) and faster than
L<Data::Dump>, but does not offer the various formatting options. It supports
dumping objects, regexes, circular structures, coderefs. Its code is first based
on L<Data::Dump>: I removed all the parts that I don't need, particularly the
pretty formatting stuffs) and added some features that I need like proper regex
dumping and coderef deparsing.

=head1 VARIABLES

=head2 $Data::Dmp::OPT_PERL_VERSION

String, default: 5.010.

Set target Perl version. If you set this to, say C<5.010>, then the dumped code
will keep compatibility with Perl 5.10.0. This is used in the following ways:

=over

=item * passed to L<Regexp::Stringify>

=item * when dumping code references

For example, in perls earlier than 5.016, feature.pm does not understand:

 no feature ':all';

so we replace it with:

 no feature;

=back

=head2 $Data::Dmp::OPT_REMOVE_PRAGMAS

Bool, default: 0.

If set to 1, then pragmas at the start of coderef dump will be removed. Coderef
dump is produced by L<B::Deparse> and is of the form like:

 sub { use feature 'current_sub', 'evalbytes', 'fc', 'say', 'state', 'switch', 'unicode_strings', 'unicode_eval'; $a <=> $b }

If you want to dump short coderefs, the pragmas might be distracting. You can
turn turn on this option which will make the above dump become:

 sub { $a <=> $b }

Note that without the pragmas, the dump might be incorrect.

=head2 $Data::Dmp::OPT_DEPARSE

Bool, default: 1.

Can be set to 0 to skip deparsing code. Coderefs will be dumped as
C<sub{"DUMMY"}> instead, like in Data::Dump.

=head2 $Data::Dmp::OPT_STRINGIFY_NUMBERS

Bool, default: 0.

If set to true, will dump numbers as quoted string, e.g. 123 as "123" instead of
123. This might be helpful if you want to compute the hash of or get a canonical
representation of data structure.

=head2 $Data::Dmp::OPT_MAX_DUMP_LEN_BEFORE_ELLIPSIS

Int, default: 70.

Used by L</dd_ellipsis> and L</dmp_ellipsis>.

=head1 BENCHMARKS

 [1..10]:
              Rate/s Precision/s  Data::Dump Data::Dumper Data::Dmp
 Data::Dump    24404          95          --       -61.6%    -75.6%
 Data::Dumper  63580         210 160.5+-1.3%           --    -36.4%
 Data::Dmp     99940         130 309.5+-1.7% 57.18+-0.55%        --
 
 [1..100]:
               Rate/s Precision/s  Data::Dump Data::Dumper Data::Dmp
 Data::Dump    2934.3         7.8          --       -75.3%    -76.2%
 Data::Dumper   11873          32 304.6+-1.5%           --     -3.7%
 Data::Dmp    12323.4           4   320+-1.1%   3.8+-0.28%        --
 
 Some mixed structure:
              Rate/s Precision/s   Data::Dump   Data::Dmp Data::Dumper
 Data::Dump     7161          12           --      -69.3%       -78.7%
 Data::Dmp     23303          29 225.43+-0.7%          --       -30.6%
 Data::Dumper  33573          56  368.8+-1.1% 44.07+-0.3%           --

=head1 FUNCTIONS

=head2 dd

Usage:

 dd($data, ...); # returns $data

Exported by default. Like C<Data::Dump>'s C<dd> (a.k.a. C<dump>), print one or
more data to STDOUT. Unlike C<Data::Dump>'s C<dd>, it I<always> prints and
return I<the original data> (like L<XXX>), making it convenient to insert into