view release on metacpan or  search on metacpan

script/_ppgrep  view on Meta::CPAN

#
#=pod
#
#=encoding UTF-8
#
#=head1 NAME
#
#Data::Dmp - Dump Perl data structures as Perl code
#
#=head1 VERSION
#
#This document describes version 0.23 of Data::Dmp (from Perl distribution Data-Dmp), released on 2017-01-30.
#
#=head1 SYNOPSIS
#
# use Data::Dmp; # exports dd() and dmp()
# dd [1, 2, 3]; # prints "[1,2,3]"
# $a = dmp({a => 1}); # -> "{a=>1}"
#
#=head1 DESCRIPTION
#
#Data::Dmp is a Perl dumper like L<Data::Dumper>. It's compact (only about 175
#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 SETTINGS
#
#=head2 $Data::Dmp::OPT_PERL_VERSION => str (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.
#
#=head1 BENCHMARKS
#
# [1..10]:
#                       Rate    Data::Dump Data::Dumper Data::Dmp
# Data::Dump     30417+-55/s            --       -66.2%    -74.0%
# Data::Dumper   89888+-79/s  195.52+-0.6%           --    -23.1%
# Data::Dmp    116890+-160/s 284.29+-0.87% 30.04+-0.21%        --
# 
# [1..100]:
#                        Rate    Data::Dump  Data::Dmp Data::Dumper
# Data::Dump    3712.3+-7.9/s            --     -73.9%       -74.9%
# Data::Dmp    14211.3+-4.9/s 282.82+-0.82%         --        -3.8%
# Data::Dumper    14771+-28/s   297.9+-1.1% 3.94+-0.2%           --
# 
# Some mixed structure:
#                     Rate    Data::Dump    Data::Dmp Data::Dumper
# Data::Dump    8764+-16/s            --       -67.6%       -80.1%
# Data::Dmp    27016+-36/s  208.28+-0.7%           --       -38.6%
# Data::Dumper 43995+-13/s 402.02+-0.95% 62.85+-0.22%           --
#
#=head1 FUNCTIONS
#
#=head2 dd($data, ...) => $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
#expressions. This also removes ambiguity and saves one C<wantarray()> call.
#
#=head2 dmp($data, ...) => $str
#
#Exported by default. Return dump result as string. Unlike C<Data::Dump>'s C<dd>
#(a.k.a. C<dump>), it I<never> prints and only return the data.
#
#=head1 FAQ
#
#=head2 When to use Data::Dmp? How does it compare to other dumper modules?
#
#Data::Dmp might be suitable for you if you want a relatively fast pure-Perl data
#structure dumper to eval-able Perl code. It produces compact, single-line Perl
#code but offers little/no formatting options. Data::Dmp and Data::Dump module