1Data::Dmp(3)          User Contributed Perl Documentation         Data::Dmp(3)
2
3
4

NAME

6       Data::Dmp - Dump Perl data structures as Perl code
7

VERSION

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

SYNOPSIS

13        use Data::Dmp; # exports dd() and dmp()
14        dd [1, 2, 3]; # prints "[1,2,3]"
15        $var = dmp({a => 1}); # -> "{a=>1}"
16
17       Print truncated dump (capped at
18       "$Data::Dmp::OPT_MAX_DUMP_LEN_BEFORE_ELLIPSIS" characters):
19
20        use Data::Dmp qw(dd_ellipsis dmp_ellipsis);
21        dd_ellipsis [1..100];
22

DESCRIPTION

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

VARIABLES

37   $Data::Dmp::OPT_PERL_VERSION
38       String, default: 5.010.
39
40       Set target Perl version. If you set this to, say 5.010, then the dumped
41       code will keep compatibility with Perl 5.10.0. This is used in the
42       following ways:
43
44       •   passed to Regexp::Stringify
45
46       •   when dumping code references
47
48           For example, in perls earlier than 5.016, feature.pm does not
49           understand:
50
51            no feature ':all';
52
53           so we replace it with:
54
55            no feature;
56
57   $Data::Dmp::OPT_REMOVE_PRAGMAS
58       Bool, default: 0.
59
60       If set to 1, then pragmas at the start of coderef dump will be removed.
61       Coderef dump is produced by B::Deparse and is of the form like:
62
63        sub { use feature 'current_sub', 'evalbytes', 'fc', 'say', 'state', 'switch', 'unicode_strings', 'unicode_eval'; $a <=> $b }
64
65       If you want to dump short coderefs, the pragmas might be distracting.
66       You can turn turn on this option which will make the above dump become:
67
68        sub { $a <=> $b }
69
70       Note that without the pragmas, the dump might be incorrect.
71
72   $Data::Dmp::OPT_DEPARSE
73       Bool, default: 1.
74
75       Can be set to 0 to skip deparsing code. Coderefs will be dumped as
76       "sub{"DUMMY"}" instead, like in Data::Dump.
77
78   $Data::Dmp::OPT_STRINGIFY_NUMBERS
79       Bool, default: 0.
80
81       If set to true, will dump numbers as quoted string, e.g. 123 as "123"
82       instead of 123. This might be helpful if you want to compute the hash
83       of or get a canonical representation of data structure.
84
85   $Data::Dmp::OPT_MAX_DUMP_LEN_BEFORE_ELLIPSIS
86       Int, default: 70.
87
88       Used by "dd_ellipsis" and "dmp_ellipsis".
89

BENCHMARKS

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

FUNCTIONS

110   dd
111       Usage:
112
113        dd($data, ...); # returns $data
114
115       Exported by default. Like "Data::Dump"'s "dd" (a.k.a. "dump"), print
116       one or more data to STDOUT. Unlike "Data::Dump"'s "dd", it always
117       prints and return the original data (like XXX), making it convenient to
118       insert into expressions. This also removes ambiguity and saves one
119       wantarray() call.
120
121   dmp
122       Usage:
123
124        my $dump = dmp($data, ...);
125
126       Exported by default. Return dump result as string. Unlike
127       "Data::Dump"'s "dd" (a.k.a. "dump"), it never prints and only return
128       the dump result.
129
130   dd_ellipsis
131       Usage:
132
133        dd_ellipsis($data, ...); # returns data
134
135       Just like "dd", except will truncate its output to
136       "$Data::Dmp::OPT_MAX_DUMP_LEN_BEFORE_ELLIPSIS" characters if dump is
137       too long.  Note that truncated dump will probably not be valid Perl
138       code.
139
140   dmp_ellipsis
141       Usage:
142
143        my $dump = dd_ellipsis($data, ...); # returns data
144
145       Just like "dmp", except will truncate dump result to
146       "$Data::Dmp::OPT_MAX_DUMP_LEN_BEFORE_ELLIPSIS" characters if dump is
147       too long.  Note that truncated dump will probably not be valid Perl
148       code.
149

FAQ

151   When to use Data::Dmp? How does it compare to other dumper modules?
152       Data::Dmp might be suitable for you if you want a relatively fast pure-
153       Perl data structure dumper to eval-able Perl code. It produces compact,
154       single-line Perl code but offers little/no formatting options.
155       Data::Dmp and Data::Dump module family usually produce Perl code that
156       is "more eval-able", e.g. it can recreate circular structure.
157
158       Data::Dump produces visually nicer output (some alignment, use of range
159       operator to shorten lists, use of base64 for binary data, etc) but no
160       built-in option to produce compact/single-line output. It's more
161       suitable for debugging.  It's also relatively slow. I usually use its
162       variant, Data::Dump::Color, for console debugging.
163
164       Data::Dumper is a core module, offers a lot of formatting options (like
165       disabling hash key sorting, setting verboseness/indent level, and so
166       on) but you usually have to configure it quite a bit before it does
167       exactly like you want (that's why there are modules on CPAN that are
168       just wrapping Data::Dumper with some configuration, like
169       Data::Dumper::Concise et al). It does not support dumping Perl code
170       that can recreate circular structures.
171
172       Of course, dumping to eval-able Perl code is slow (not to mention the
173       cost of re-loading the code back to in-memory data, via eval-ing)
174       compared to dumping to JSON, YAML, Sereal, or other format. So you need
175       to decide first whether this is the appropriate route you want to take.
176       (But note that there is also Data::Dumper::Limited and Data::Undump
177       which uses a format similar to Data::Dumper but lets you load the
178       serialized data without eval-ing them, thus achieving the speed
179       comparable to JSON::XS).
180
181   Is the output guaranteed to be single line dump?
182       No. Some things can still produce multiline dump, e.g. newline in
183       regular expression.
184

HOMEPAGE

186       Please visit the project's homepage at
187       <https://metacpan.org/release/Data-Dmp>.
188

SOURCE

190       Source repository is at <https://github.com/perlancar/perl-Data-Dmp>.
191

SEE ALSO

193       Data::Dump and other variations/derivate works in Data::Dump::*.
194
195       Data::Dumper and its variants.
196
197       Data::Printer.
198
199       YAML, JSON, Storable, Sereal, and other serialization formats.
200

AUTHOR

202       perlancar <perlancar@cpan.org>
203

CONTRIBUTING

205       To contribute, you can send patches by email/via RT, or send pull
206       requests on GitHub.
207
208       Most of the time, you don't need to build the distribution yourself.
209       You can simply modify the code, then test via:
210
211        % prove -l
212
213       If you want to build the distribution (e.g. to try to install it
214       locally on your system), you can install Dist::Zilla,
215       Dist::Zilla::PluginBundle::Author::PERLANCAR,
216       Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two
217       other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps
218       required beyond that are considered a bug and can be reported to me.
219
221       This software is copyright (c) 2022, 2021, 2020, 2017, 2016, 2015, 2014
222       by perlancar <perlancar@cpan.org>.
223
224       This is free software; you can redistribute it and/or modify it under
225       the same terms as the Perl 5 programming language system itself.
226

BUGS

228       Please report any bugs or feature requests on the bugtracker website
229       <https://rt.cpan.org/Public/Dist/Display.html?Name=Data-Dmp>
230
231       When submitting a bug or request, please include a test-file or a patch
232       to an existing test-file that illustrates the bug or desired feature.
233
234
235
236perl v5.38.0                      2023-07-20                      Data::Dmp(3)
Impressum