This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Make Data::Dumper XS ignore Freezer return value
[perl5.git] / dist / Data-Dumper / Dumper.pm
CommitLineData
823edd99
GS
1#
2# Data/Dumper.pm
3#
4# convert perl data structures into perl syntax suitable for both printing
5# and eval
6#
7# Documentation at the __END__
8#
9
10package Data::Dumper;
11
d036e907 12BEGIN {
be022d23 13 $VERSION = '2.141'; # Don't forget to set version and release
5aaab254 14} # date in POD below!
823edd99
GS
15
16#$| = 1;
17
3b825e41 18use 5.006_001;
823edd99 19require Exporter;
823edd99
GS
20require overload;
21
22use Carp;
23
907e5114
JB
24BEGIN {
25 @ISA = qw(Exporter);
26 @EXPORT = qw(Dumper);
27 @EXPORT_OK = qw(DumperX);
823edd99 28
907e5114
JB
29 # if run under miniperl, or otherwise lacking dynamic loading,
30 # XSLoader should be attempted to load, or the pure perl flag
31 # toggled on load failure.
32 eval {
33 require XSLoader;
1e9285c2
FC
34 XSLoader::load( 'Data::Dumper' );
35 1
d036e907 36 }
1e9285c2 37 or $Useperl = 1;
907e5114 38}
823edd99
GS
39
40# module vars and their defaults
907e5114
JB
41$Indent = 2 unless defined $Indent;
42$Purity = 0 unless defined $Purity;
43$Pad = "" unless defined $Pad;
44$Varname = "VAR" unless defined $Varname;
45$Useqq = 0 unless defined $Useqq;
46$Terse = 0 unless defined $Terse;
47$Freezer = "" unless defined $Freezer;
48$Toaster = "" unless defined $Toaster;
49$Deepcopy = 0 unless defined $Deepcopy;
50$Quotekeys = 1 unless defined $Quotekeys;
51$Bless = "bless" unless defined $Bless;
52#$Expdepth = 0 unless defined $Expdepth;
53$Maxdepth = 0 unless defined $Maxdepth;
54$Pair = ' => ' unless defined $Pair;
55$Useperl = 0 unless defined $Useperl;
56$Sortkeys = 0 unless defined $Sortkeys;
57$Deparse = 0 unless defined $Deparse;
d424882c 58$Sparseseen = 0 unless defined $Sparseseen;
823edd99
GS
59
60#
61# expects an arrayref of values to be dumped.
62# can optionally pass an arrayref of names for the values.
63# names must have leading $ sign stripped. begin the name with *
64# to cause output of arrays and hashes rather than refs.
65#
66sub new {
67 my($c, $v, $n) = @_;
68
69 croak "Usage: PACKAGE->new(ARRAYREF, [ARRAYREF])"
70 unless (defined($v) && (ref($v) eq 'ARRAY'));
b09a1111 71 $n = [] unless (defined($n) && (ref($n) eq 'ARRAY'));
823edd99
GS
72
73 my($s) = {
74 level => 0, # current recursive depth
75 indent => $Indent, # various styles of indenting
76 pad => $Pad, # all lines prefixed by this string
77 xpad => "", # padding-per-level
78 apad => "", # added padding for hash keys n such
79 sep => "", # list separator
30b4f386 80 pair => $Pair, # hash key/value separator: defaults to ' => '
823edd99
GS
81 seen => {}, # local (nested) refs (id => [name, val])
82 todump => $v, # values to dump []
83 names => $n, # optional names for values []
84 varname => $Varname, # prefix to use for tagging nameless ones
85 purity => $Purity, # degree to which output is evalable
86 useqq => $Useqq, # use "" for strings (backslashitis ensues)
87 terse => $Terse, # avoid name output (where feasible)
88 freezer => $Freezer, # name of Freezer method for objects
89 toaster => $Toaster, # name of method to revive objects
90 deepcopy => $Deepcopy, # dont cross-ref, except to stop recursion
91 quotekeys => $Quotekeys, # quote hash keys
92 'bless' => $Bless, # keyword to use for "bless"
93# expdepth => $Expdepth, # cutoff depth for explicit dumping
a2126434 94 maxdepth => $Maxdepth, # depth beyond which we give up
31a725b3
JH
95 useperl => $Useperl, # use the pure Perl implementation
96 sortkeys => $Sortkeys, # flag or filter for sorting hash keys
8e5f9a6e 97 deparse => $Deparse, # use B::Deparse for coderefs
d424882c 98 noseen => $Sparseseen, # do not populate the seen hash unless necessary
823edd99
GS
99 };
100
101 if ($Indent > 0) {
102 $s->{xpad} = " ";
103 $s->{sep} = "\n";
104 }
105 return bless($s, $c);
106}
107
53095d08 108# Packed numeric addresses take less memory. Plus pack is faster than sprintf
e52c0e5a 109
53095d08
NC
110# Most users of current versions of Data::Dumper will be 5.008 or later.
111# Anyone on 5.6.1 and 5.6.2 upgrading will be rare (particularly judging by
112# the bug reports from users on those platforms), so for the common case avoid
113# complexity, and avoid even compiling the unneeded code.
114
115sub init_refaddr_format {
116}
117
118sub format_refaddr {
e52c0e5a
NC
119 require Scalar::Util;
120 pack "J", Scalar::Util::refaddr(shift);
53095d08
NC
121};
122
123if ($] < 5.008) {
124 eval <<'EOC' or die;
125 no warnings 'redefine';
126 my $refaddr_format;
127 sub init_refaddr_format {
128 require Config;
129 my $f = $Config::Config{uvxformat};
130 $f =~ tr/"//d;
131 $refaddr_format = "0x%" . $f;
132 }
133
134 sub format_refaddr {
135 require Scalar::Util;
136 sprintf $refaddr_format, Scalar::Util::refaddr(shift);
137 }
138
139 1
140EOC
2728842d
RGS
141}
142
823edd99
GS
143#
144# add-to or query the table of already seen references
145#
146sub Seen {
147 my($s, $g) = @_;
148 if (defined($g) && (ref($g) eq 'HASH')) {
3b5b1125 149 init_refaddr_format();
823edd99
GS
150 my($k, $v, $id);
151 while (($k, $v) = each %$g) {
152 if (defined $v and ref $v) {
2728842d 153 $id = format_refaddr($v);
823edd99
GS
154 if ($k =~ /^[*](.*)$/) {
155 $k = (ref $v eq 'ARRAY') ? ( "\\\@" . $1 ) :
156 (ref $v eq 'HASH') ? ( "\\\%" . $1 ) :
157 (ref $v eq 'CODE') ? ( "\\\&" . $1 ) :
158 ( "\$" . $1 ) ;
159 }
160 elsif ($k !~ /^\$/) {
161 $k = "\$" . $k;
162 }
163 $s->{seen}{$id} = [$k, $v];
164 }
165 else {
166 carp "Only refs supported, ignoring non-ref item \$$k";
167 }
168 }
169 return $s;
170 }
171 else {
172 return map { @$_ } values %{$s->{seen}};
173 }
174}
175
176#
177# set or query the values to be dumped
178#
179sub Values {
180 my($s, $v) = @_;
181 if (defined($v) && (ref($v) eq 'ARRAY')) {
182 $s->{todump} = [@$v]; # make a copy
183 return $s;
184 }
185 else {
186 return @{$s->{todump}};
187 }
188}
189
190#
191# set or query the names of the values to be dumped
192#
193sub Names {
194 my($s, $n) = @_;
195 if (defined($n) && (ref($n) eq 'ARRAY')) {
196 $s->{names} = [@$n]; # make a copy
197 return $s;
198 }
199 else {
200 return @{$s->{names}};
201 }
202}
203
204sub DESTROY {}
205
0f1923bd
GS
206sub Dump {
207 return &Dumpxs
31a725b3 208 unless $Data::Dumper::Useperl || (ref($_[0]) && $_[0]->{useperl}) ||
8e5f9a6e
RGS
209 $Data::Dumper::Useqq || (ref($_[0]) && $_[0]->{useqq}) ||
210 $Data::Dumper::Deparse || (ref($_[0]) && $_[0]->{deparse});
0f1923bd
GS
211 return &Dumpperl;
212}
213
823edd99
GS
214#
215# dump the refs in the current dumper object.
216# expects same args as new() if called via package name.
217#
0f1923bd 218sub Dumpperl {
823edd99
GS
219 my($s) = shift;
220 my(@out, $val, $name);
221 my($i) = 0;
222 local(@post);
2728842d 223 init_refaddr_format();
823edd99
GS
224
225 $s = $s->new(@_) unless ref $s;
226
227 for $val (@{$s->{todump}}) {
228 my $out = "";
229 @post = ();
230 $name = $s->{names}[$i++];
231 if (defined $name) {
232 if ($name =~ /^[*](.*)$/) {
233 if (defined $val) {
234 $name = (ref $val eq 'ARRAY') ? ( "\@" . $1 ) :
235 (ref $val eq 'HASH') ? ( "\%" . $1 ) :
236 (ref $val eq 'CODE') ? ( "\*" . $1 ) :
237 ( "\$" . $1 ) ;
238 }
239 else {
240 $name = "\$" . $1;
241 }
242 }
243 elsif ($name !~ /^\$/) {
244 $name = "\$" . $name;
245 }
246 }
247 else {
248 $name = "\$" . $s->{varname} . $i;
249 }
250
251 my $valstr;
252 {
253 local($s->{apad}) = $s->{apad};
d34e9bd9 254 $s->{apad} .= ' ' x (length($name) + 3) if $s->{indent} >= 2 and !$s->{terse};
823edd99
GS
255 $valstr = $s->_dump($val, $name);
256 }
257
258 $valstr = "$name = " . $valstr . ';' if @post or !$s->{terse};
259 $out .= $s->{pad} . $valstr . $s->{sep};
260 $out .= $s->{pad} . join(';' . $s->{sep} . $s->{pad}, @post)
261 . ';' . $s->{sep} if @post;
262
263 push @out, $out;
264 }
265 return wantarray ? @out : join('', @out);
266}
267
d0c214fd
AF
268# wrap string in single quotes (escaping if needed)
269sub _quote {
270 my $val = shift;
271 $val =~ s/([\\\'])/\\$1/g;
272 return "'" . $val . "'";
273}
274
d036e907
FC
275# Old Perls (5.14-) have trouble resetting vstring magic when it is no
276# longer valid.
277use constant _bad_vsmg => defined &_vstring && (_vstring(~v0)||'') eq "v0";
278
823edd99
GS
279#
280# twist, toil and turn;
281# and recurse, of course.
31a725b3
JH
282# sometimes sordidly;
283# and curse if no recourse.
823edd99
GS
284#
285sub _dump {
286 my($s, $val, $name) = @_;
287 my($sname);
288 my($out, $realpack, $realtype, $type, $ipad, $id, $blesspad);
289
823edd99
GS
290 $type = ref $val;
291 $out = "";
292
293 if ($type) {
294
c5f7c514
ST
295 # Call the freezer method if it's specified and the object has the
296 # method. Trap errors and warn() instead of die()ing, like the XS
297 # implementation.
298 my $freezer = $s->{freezer};
299 if ($freezer and UNIVERSAL::can($val, $freezer)) {
300 eval { $val->$freezer() };
301 warn "WARNING(Freezer method call failed): $@" if $@;
823edd99
GS
302 }
303
2728842d
RGS
304 require Scalar::Util;
305 $realpack = Scalar::Util::blessed($val);
306 $realtype = $realpack ? Scalar::Util::reftype($val) : ref $val;
307 $id = format_refaddr($val);
a2126434 308
7820172a
GS
309 # if it has a name, we need to either look it up, or keep a tab
310 # on it so we know when we hit it later
311 if (defined($name) and length($name)) {
312 # keep a tab on it so that we dont fall into recursive pit
313 if (exists $s->{seen}{$id}) {
314# if ($s->{expdepth} < $s->{level}) {
315 if ($s->{purity} and $s->{level} > 0) {
316 $out = ($realtype eq 'HASH') ? '{}' :
317 ($realtype eq 'ARRAY') ? '[]' :
5df59fb6 318 'do{my $o}' ;
7820172a 319 push @post, $name . " = " . $s->{seen}{$id}[0];
823edd99
GS
320 }
321 else {
7820172a
GS
322 $out = $s->{seen}{$id}[0];
323 if ($name =~ /^([\@\%])/) {
324 my $start = $1;
325 if ($out =~ /^\\$start/) {
326 $out = substr($out, 1);
327 }
328 else {
329 $out = $start . '{' . $out . '}';
330 }
331 }
332 }
333 return $out;
334# }
335 }
336 else {
337 # store our name
338 $s->{seen}{$id} = [ (($name =~ /^[@%]/) ? ('\\' . $name ) :
339 ($realtype eq 'CODE' and
340 $name =~ /^[*](.*)$/) ? ('\\&' . $1 ) :
341 $name ),
342 $val ];
823edd99 343 }
823edd99 344 }
4ab99479
YO
345 my $no_bless = 0;
346 my $is_regex = 0;
347 if ( $realpack and ($] >= 5.009005 ? re::is_regexp($val) : $realpack eq 'Regexp') ) {
348 $is_regex = 1;
349 $no_bless = $realpack eq 'Regexp';
a2126434
JN
350 }
351
352 # If purity is not set and maxdepth is set, then check depth:
353 # if we have reached maximum depth, return the string
354 # representation of the thing we are currently examining
355 # at this depth (i.e., 'Foo=ARRAY(0xdeadbeef)').
356 if (!$s->{purity}
357 and $s->{maxdepth} > 0
358 and $s->{level} >= $s->{maxdepth})
359 {
360 return qq['$val'];
361 }
362
363 # we have a blessed ref
4ab99479 364 if ($realpack and !$no_bless) {
a2126434
JN
365 $out = $s->{'bless'} . '( ';
366 $blesspad = $s->{apad};
367 $s->{apad} .= ' ' if ($s->{indent} >= 2);
7894fbab
GS
368 }
369
823edd99
GS
370 $s->{level}++;
371 $ipad = $s->{xpad} x $s->{level};
372
4ab99479
YO
373 if ($is_regex) {
374 my $pat;
375 # This really sucks, re:regexp_pattern is in ext/re/re.xs and not in
376 # universal.c, and even worse we cant just require that re to be loaded
377 # we *have* to use() it.
378 # We should probably move it to universal.c for 5.10.1 and fix this.
379 # Currently we only use re::regexp_pattern when the re is blessed into another
380 # package. This has the disadvantage of meaning that a DD dump won't round trip
381 # as the pattern will be repeatedly wrapped with the same modifiers.
382 # This is an aesthetic issue so we will leave it for now, but we could use
383 # regexp_pattern() in list context to get the modifiers separately.
384 # But since this means loading the full debugging engine in process we wont
385 # bother unless its necessary for accuracy.
192c1e27 386 if (($realpack ne 'Regexp') && defined(*re::regexp_pattern{CODE})) {
4ab99479
YO
387 $pat = re::regexp_pattern($val);
388 } else {
389 $pat = "$val";
390 }
de5ef703 391 $pat =~ s <(\\.)|/> { $1 || '\\/' }ge;
4ab99479
YO
392 $out .= "qr/$pat/";
393 }
d036e907
FC
394 elsif ($realtype eq 'SCALAR' || $realtype eq 'REF'
395 || $realtype eq 'VSTRING') {
823edd99 396 if ($realpack) {
7820172a 397 $out .= 'do{\\(my $o = ' . $s->_dump($$val, "\${$name}") . ')}';
823edd99
GS
398 }
399 else {
7820172a 400 $out .= '\\' . $s->_dump($$val, "\${$name}");
823edd99
GS
401 }
402 }
403 elsif ($realtype eq 'GLOB') {
7820172a 404 $out .= '\\' . $s->_dump($$val, "*{$name}");
823edd99
GS
405 }
406 elsif ($realtype eq 'ARRAY') {
a36ee16f 407 my($pad, $mname);
823edd99
GS
408 my($i) = 0;
409 $out .= ($name =~ /^\@/) ? '(' : '[';
410 $pad = $s->{sep} . $s->{pad} . $s->{apad};
411 ($name =~ /^\@(.*)$/) ? ($mname = "\$" . $1) :
7820172a
GS
412 # omit -> if $foo->[0]->{bar}, but not ${$foo->[0]}->{bar}
413 ($name =~ /^\\?[\%\@\*\$][^{].*[]}]$/) ? ($mname = $name) :
414 ($mname = $name . '->');
823edd99 415 $mname .= '->' if $mname =~ /^\*.+\{[A-Z]+\}$/;
a36ee16f 416 for my $v (@$val) {
823edd99
GS
417 $sname = $mname . '[' . $i . ']';
418 $out .= $pad . $ipad . '#' . $i if $s->{indent} >= 3;
419 $out .= $pad . $ipad . $s->_dump($v, $sname);
420 $out .= "," if $i++ < $#$val;
421 }
422 $out .= $pad . ($s->{xpad} x ($s->{level} - 1)) if $i;
423 $out .= ($name =~ /^\@/) ? ')' : ']';
424 }
425 elsif ($realtype eq 'HASH') {
30b4f386 426 my($k, $v, $pad, $lpad, $mname, $pair);
823edd99
GS
427 $out .= ($name =~ /^\%/) ? '(' : '{';
428 $pad = $s->{sep} . $s->{pad} . $s->{apad};
429 $lpad = $s->{apad};
30b4f386 430 $pair = $s->{pair};
7820172a
GS
431 ($name =~ /^\%(.*)$/) ? ($mname = "\$" . $1) :
432 # omit -> if $foo->[0]->{bar}, but not ${$foo->[0]}->{bar}
433 ($name =~ /^\\?[\%\@\*\$][^{].*[]}]$/) ? ($mname = $name) :
434 ($mname = $name . '->');
823edd99 435 $mname .= '->' if $mname =~ /^\*.+\{[A-Z]+\}$/;
31a725b3
JH
436 my ($sortkeys, $keys, $key) = ("$s->{sortkeys}");
437 if ($sortkeys) {
438 if (ref($s->{sortkeys}) eq 'CODE') {
439 $keys = $s->{sortkeys}($val);
440 unless (ref($keys) eq 'ARRAY') {
441 carp "Sortkeys subroutine did not return ARRAYREF";
442 $keys = [];
443 }
444 }
445 else {
446 $keys = [ sort keys %$val ];
447 }
448 }
b36d99fa
AV
449
450 # Ensure hash iterator is reset
451 keys(%$val);
452
31a725b3
JH
453 while (($k, $v) = ! $sortkeys ? (each %$val) :
454 @$keys ? ($key = shift(@$keys), $val->{$key}) :
455 () )
456 {
823edd99
GS
457 my $nk = $s->_dump($k, "");
458 $nk = $1 if !$s->{quotekeys} and $nk =~ /^[\"\']([A-Za-z_]\w*)[\"\']$/;
459 $sname = $mname . '{' . $nk . '}';
30b4f386 460 $out .= $pad . $ipad . $nk . $pair;
823edd99
GS
461
462 # temporarily alter apad
463 $s->{apad} .= (" " x (length($nk) + 4)) if $s->{indent} >= 2;
464 $out .= $s->_dump($val->{$k}, $sname) . ",";
465 $s->{apad} = $lpad if $s->{indent} >= 2;
466 }
467 if (substr($out, -1) eq ',') {
468 chop $out;
469 $out .= $pad . ($s->{xpad} x ($s->{level} - 1));
470 }
471 $out .= ($name =~ /^\%/) ? ')' : '}';
472 }
473 elsif ($realtype eq 'CODE') {
8e5f9a6e
RGS
474 if ($s->{deparse}) {
475 require B::Deparse;
476 my $sub = 'sub ' . (B::Deparse->new)->coderef2text($val);
41a63c2f 477 $pad = $s->{sep} . $s->{pad} . $s->{apad} . $s->{xpad} x ($s->{level} - 1);
8e5f9a6e
RGS
478 $sub =~ s/\n/$pad/gse;
479 $out .= $sub;
480 } else {
481 $out .= 'sub { "DUMMY" }';
482 carp "Encountered CODE ref, using dummy placeholder" if $s->{purity};
483 }
823edd99
GS
484 }
485 else {
486 croak "Can\'t handle $realtype type.";
487 }
488
4ab99479 489 if ($realpack and !$no_bless) { # we have a blessed ref
d0c214fd 490 $out .= ', ' . _quote($realpack) . ' )';
823edd99
GS
491 $out .= '->' . $s->{toaster} . '()' if $s->{toaster} ne '';
492 $s->{apad} = $blesspad;
493 }
494 $s->{level}--;
495
496 }
497 else { # simple scalar
498
499 my $ref = \$_[1];
d036e907 500 my $v;
823edd99
GS
501 # first, catalog the scalar
502 if ($name ne '') {
2728842d 503 $id = format_refaddr($ref);
823edd99 504 if (exists $s->{seen}{$id}) {
7820172a
GS
505 if ($s->{seen}{$id}[2]) {
506 $out = $s->{seen}{$id}[0];
507 #warn "[<$out]\n";
508 return "\${$out}";
509 }
823edd99
GS
510 }
511 else {
7820172a
GS
512 #warn "[>\\$name]\n";
513 $s->{seen}{$id} = ["\\$name", $ref];
823edd99
GS
514 }
515 }
c1205a1e
FC
516 $ref = \$val;
517 if (ref($ref) eq 'GLOB') { # glob
823edd99 518 my $name = substr($val, 1);
58cee0f7 519 if ($name =~ /^[A-Za-z_][\w:]*$/ && $name ne 'main::') {
823edd99
GS
520 $name =~ s/^main::/::/;
521 $sname = $name;
522 }
523 else {
ad08c923
FC
524 $sname = $s->_dump(
525 $name eq 'main::' || $] < 5.007 && $name eq "main::\0"
526 ? ''
527 : $name,
528 "",
529 );
823edd99
GS
530 $sname = '{' . $sname . '}';
531 }
532 if ($s->{purity}) {
533 my $k;
534 local ($s->{level}) = 0;
535 for $k (qw(SCALAR ARRAY HASH)) {
7820172a
GS
536 my $gval = *$val{$k};
537 next unless defined $gval;
538 next if $k eq "SCALAR" && ! defined $$gval; # always there
539
823edd99
GS
540 # _dump can push into @post, so we hold our place using $postlen
541 my $postlen = scalar @post;
542 $post[$postlen] = "\*$sname = ";
543 local ($s->{apad}) = " " x length($post[$postlen]) if $s->{indent} >= 2;
7820172a 544 $post[$postlen] .= $s->_dump($gval, "\*$sname\{$k\}");
823edd99
GS
545 }
546 }
547 $out .= '*' . $sname;
548 }
7820172a
GS
549 elsif (!defined($val)) {
550 $out .= "undef";
551 }
d036e907
FC
552 elsif (defined &_vstring and $v = _vstring($val)
553 and !_bad_vsmg || eval $v eq $val) {
554 $out .= $v;
555 }
556 elsif (!defined &_vstring
c1205a1e 557 and ref $ref eq 'VSTRING' || eval{Scalar::Util::isvstring($val)}) {
d036e907
FC
558 $out .= sprintf "%vd", $val;
559 }
c4cce848 560 elsif ($val =~ /^(?:0|-?[1-9]\d{0,8})\z/) { # safe decimal number
823edd99
GS
561 $out .= $val;
562 }
563 else { # string
c4cce848 564 if ($s->{useqq} or $val =~ tr/\0-\377//c) {
38a44b82 565 # Fall back to qq if there's Unicode
7820172a 566 $out .= qquote($val, $s->{useqq});
823edd99
GS
567 }
568 else {
d0c214fd 569 $out .= _quote($val);
823edd99
GS
570 }
571 }
572 }
7820172a
GS
573 if ($id) {
574 # if we made it this far, $id was added to seen list at current
575 # level, so remove it to get deep copies
576 if ($s->{deepcopy}) {
577 delete($s->{seen}{$id});
578 }
579 elsif ($name) {
580 $s->{seen}{$id}[2] = 1;
581 }
582 }
823edd99
GS
583 return $out;
584}
585
586#
587# non-OO style of earlier version
588#
589sub Dumper {
590 return Data::Dumper->Dump([@_]);
591}
592
0f1923bd 593# compat stub
823edd99
GS
594sub DumperX {
595 return Data::Dumper->Dumpxs([@_], []);
596}
597
598sub Dumpf { return Data::Dumper->Dump(@_) }
599
600sub Dumpp { print Data::Dumper->Dump(@_) }
601
602#
603# reset the "seen" cache
604#
605sub Reset {
606 my($s) = shift;
607 $s->{seen} = {};
608 return $s;
609}
610
611sub Indent {
612 my($s, $v) = @_;
613 if (defined($v)) {
614 if ($v == 0) {
615 $s->{xpad} = "";
616 $s->{sep} = "";
617 }
618 else {
619 $s->{xpad} = " ";
620 $s->{sep} = "\n";
621 }
622 $s->{indent} = $v;
623 return $s;
624 }
625 else {
626 return $s->{indent};
627 }
628}
629
30b4f386 630sub Pair {
631 my($s, $v) = @_;
632 defined($v) ? (($s->{pair} = $v), return $s) : $s->{pair};
633}
634
823edd99
GS
635sub Pad {
636 my($s, $v) = @_;
637 defined($v) ? (($s->{pad} = $v), return $s) : $s->{pad};
638}
639
640sub Varname {
641 my($s, $v) = @_;
642 defined($v) ? (($s->{varname} = $v), return $s) : $s->{varname};
643}
644
645sub Purity {
646 my($s, $v) = @_;
647 defined($v) ? (($s->{purity} = $v), return $s) : $s->{purity};
648}
649
650sub Useqq {
651 my($s, $v) = @_;
652 defined($v) ? (($s->{useqq} = $v), return $s) : $s->{useqq};
653}
654
655sub Terse {
656 my($s, $v) = @_;
657 defined($v) ? (($s->{terse} = $v), return $s) : $s->{terse};
658}
659
660sub Freezer {
661 my($s, $v) = @_;
662 defined($v) ? (($s->{freezer} = $v), return $s) : $s->{freezer};
663}
664
665sub Toaster {
666 my($s, $v) = @_;
667 defined($v) ? (($s->{toaster} = $v), return $s) : $s->{toaster};
668}
669
670sub Deepcopy {
671 my($s, $v) = @_;
672 defined($v) ? (($s->{deepcopy} = $v), return $s) : $s->{deepcopy};
673}
674
675sub Quotekeys {
676 my($s, $v) = @_;
677 defined($v) ? (($s->{quotekeys} = $v), return $s) : $s->{quotekeys};
678}
679
680sub Bless {
681 my($s, $v) = @_;
682 defined($v) ? (($s->{'bless'} = $v), return $s) : $s->{'bless'};
683}
684
a2126434
JN
685sub Maxdepth {
686 my($s, $v) = @_;
687 defined($v) ? (($s->{'maxdepth'} = $v), return $s) : $s->{'maxdepth'};
688}
689
31a725b3
JH
690sub Useperl {
691 my($s, $v) = @_;
692 defined($v) ? (($s->{'useperl'} = $v), return $s) : $s->{'useperl'};
693}
694
695sub Sortkeys {
696 my($s, $v) = @_;
697 defined($v) ? (($s->{'sortkeys'} = $v), return $s) : $s->{'sortkeys'};
698}
699
8e5f9a6e
RGS
700sub Deparse {
701 my($s, $v) = @_;
702 defined($v) ? (($s->{'deparse'} = $v), return $s) : $s->{'deparse'};
703}
a2126434 704
d424882c
SM
705sub Sparseseen {
706 my($s, $v) = @_;
707 defined($v) ? (($s->{'noseen'} = $v), return $s) : $s->{'noseen'};
708}
709
7820172a
GS
710# used by qquote below
711my %esc = (
712 "\a" => "\\a",
713 "\b" => "\\b",
714 "\t" => "\\t",
715 "\n" => "\\n",
716 "\f" => "\\f",
717 "\r" => "\\r",
718 "\e" => "\\e",
719);
720
823edd99
GS
721# put a string value in double quotes
722sub qquote {
723 local($_) = shift;
7820172a 724 s/([\\\"\@\$])/\\$1/g;
dc71dc59
JH
725 my $bytes; { use bytes; $bytes = length }
726 s/([^\x00-\x7f])/'\x{'.sprintf("%x",ord($1)).'}'/ge if $bytes > length;
0407a77b
GS
727 return qq("$_") unless
728 /[^ !"\#\$%&'()*+,\-.\/0-9:;<=>?\@A-Z[\\\]^_`a-z{|}~]/; # fast exit
7820172a
GS
729
730 my $high = shift || "";
731 s/([\a\b\t\n\f\r\e])/$esc{$1}/g;
732
0407a77b
GS
733 if (ord('^')==94) { # ascii
734 # no need for 3 digits in escape for these
735 s/([\0-\037])(?!\d)/'\\'.sprintf('%o',ord($1))/eg;
736 s/([\0-\037\177])/'\\'.sprintf('%03o',ord($1))/eg;
43948175 737 # all but last branch below not supported --BEHAVIOR SUBJECT TO CHANGE--
0407a77b
GS
738 if ($high eq "iso8859") {
739 s/([\200-\240])/'\\'.sprintf('%o',ord($1))/eg;
740 } elsif ($high eq "utf8") {
741# use utf8;
742# $str =~ s/([^\040-\176])/sprintf "\\x{%04x}", ord($1)/ge;
743 } elsif ($high eq "8bit") {
744 # leave it as it is
745 } else {
746 s/([\200-\377])/'\\'.sprintf('%03o',ord($1))/eg;
c4cce848 747 s/([^\040-\176])/sprintf "\\x{%04x}", ord($1)/ge;
0407a77b
GS
748 }
749 }
750 else { # ebcdic
43948175
GS
751 s{([^ !"\#\$%&'()*+,\-.\/0-9:;<=>?\@A-Z[\\\]^_`a-z{|}~])(?!\d)}
752 {my $v = ord($1); '\\'.sprintf(($v <= 037 ? '%o' : '%03o'), $v)}eg;
753 s{([^ !"\#\$%&'()*+,\-.\/0-9:;<=>?\@A-Z[\\\]^_`a-z{|}~])}
754 {'\\'.sprintf('%03o',ord($1))}eg;
7820172a 755 }
0407a77b 756
7820172a 757 return qq("$_");
823edd99
GS
758}
759
fec5e1eb
IM
760# helper sub to sort hash keys in Perl < 5.8.0 where we don't have
761# access to sortsv() from XS
762sub _sortkeys { [ sort keys %{$_[0]} ] }
763
823edd99
GS
7641;
765__END__
766
767=head1 NAME
768
769Data::Dumper - stringified perl data structures, suitable for both printing and C<eval>
770
823edd99
GS
771=head1 SYNOPSIS
772
773 use Data::Dumper;
774
775 # simple procedural interface
776 print Dumper($foo, $bar);
777
778 # extended usage with names
779 print Data::Dumper->Dump([$foo, $bar], [qw(foo *ary)]);
780
781 # configuration variables
782 {
82df27e1 783 local $Data::Dumper::Purity = 1;
823edd99
GS
784 eval Data::Dumper->Dump([$foo, $bar], [qw(foo *ary)]);
785 }
786
787 # OO usage
788 $d = Data::Dumper->new([$foo, $bar], [qw(foo *ary)]);
789 ...
790 print $d->Dump;
791 ...
792 $d->Purity(1)->Terse(1)->Deepcopy(1);
793 eval $d->Dump;
794
795
796=head1 DESCRIPTION
797
798Given a list of scalars or reference variables, writes out their contents in
5e603302 799perl syntax. The references can also be objects. The content of each
823edd99
GS
800variable is output in a single Perl statement. Handles self-referential
801structures correctly.
802
803The return value can be C<eval>ed to get back an identical copy of the
fc3a748c 804original reference structure.
823edd99
GS
805
806Any references that are the same as one of those passed in will be named
807C<$VAR>I<n> (where I<n> is a numeric suffix), and other duplicate references
808to substructures within C<$VAR>I<n> will be appropriately labeled using arrow
809notation. You can specify names for individual values to be dumped if you
810use the C<Dump()> method, or you can change the default C<$VAR> prefix to
811something else. See C<$Data::Dumper::Varname> and C<$Data::Dumper::Terse>
812below.
813
814The default output of self-referential structures can be C<eval>ed, but the
815nested references to C<$VAR>I<n> will be undefined, since a recursive
816structure cannot be constructed using one Perl statement. You should set the
817C<Purity> flag to 1 to get additional statements that will correctly fill in
fc3a748c
RGS
818these references. Moreover, if C<eval>ed when strictures are in effect,
819you need to ensure that any variables it accesses are previously declared.
823edd99
GS
820
821In the extended usage form, the references to be dumped can be given
822user-specified names. If a name begins with a C<*>, the output will
823describe the dereferenced type of the supplied reference for hashes and
824arrays, and coderefs. Output of names will be avoided where possible if
825the C<Terse> flag is set.
826
827In many cases, methods that are used to set the internal state of the
828object will return the object itself, so method calls can be conveniently
829chained together.
830
831Several styles of output are possible, all controlled by setting
832the C<Indent> flag. See L<Configuration Variables or Methods> below
833for details.
834
835
836=head2 Methods
837
838=over 4
839
840=item I<PACKAGE>->new(I<ARRAYREF [>, I<ARRAYREF]>)
841
842Returns a newly created C<Data::Dumper> object. The first argument is an
843anonymous array of values to be dumped. The optional second argument is an
844anonymous array of names for the values. The names need not have a leading
845C<$> sign, and must be comprised of alphanumeric characters. You can begin
846a name with a C<*> to specify that the dereferenced type must be dumped
847instead of the reference itself, for ARRAY and HASH references.
848
849The prefix specified by C<$Data::Dumper::Varname> will be used with a
850numeric suffix if the name for a value is undefined.
851
852Data::Dumper will catalog all references encountered while dumping the
853values. Cross-references (in the form of names of substructures in perl
854syntax) will be inserted at all possible points, preserving any structural
855interdependencies in the original set of values. Structure traversal is
856depth-first, and proceeds in order from the first supplied value to
857the last.
858
859=item I<$OBJ>->Dump I<or> I<PACKAGE>->Dump(I<ARRAYREF [>, I<ARRAYREF]>)
860
861Returns the stringified form of the values stored in the object (preserving
862the order in which they were supplied to C<new>), subject to the
91e74348 863configuration options below. In a list context, it returns a list
823edd99
GS
864of strings corresponding to the supplied values.
865
866The second form, for convenience, simply calls the C<new> method on its
867arguments before dumping the object immediately.
868
823edd99
GS
869=item I<$OBJ>->Seen(I<[HASHREF]>)
870
871Queries or adds to the internal table of already encountered references.
872You must use C<Reset> to explicitly clear the table if needed. Such
873references are not dumped; instead, their names are inserted wherever they
874are encountered subsequently. This is useful especially for properly
875dumping subroutine references.
876
d1be9408 877Expects an anonymous hash of name => value pairs. Same rules apply for names
823edd99 878as in C<new>. If no argument is supplied, will return the "seen" list of
91e74348 879name => value pairs, in a list context. Otherwise, returns the object
823edd99
GS
880itself.
881
882=item I<$OBJ>->Values(I<[ARRAYREF]>)
883
884Queries or replaces the internal array of values that will be dumped.
885When called without arguments, returns the values. Otherwise, returns the
886object itself.
887
888=item I<$OBJ>->Names(I<[ARRAYREF]>)
889
890Queries or replaces the internal array of user supplied names for the values
891that will be dumped. When called without arguments, returns the names.
892Otherwise, returns the object itself.
893
894=item I<$OBJ>->Reset
895
896Clears the internal table of "seen" references and returns the object
897itself.
898
899=back
900
901=head2 Functions
902
903=over 4
904
905=item Dumper(I<LIST>)
906
907Returns the stringified form of the values in the list, subject to the
908configuration options below. The values will be named C<$VAR>I<n> in the
909output, where I<n> is a numeric suffix. Will return a list of strings
91e74348 910in a list context.
823edd99 911
823edd99
GS
912=back
913
914=head2 Configuration Variables or Methods
915
916Several configuration variables can be used to control the kind of output
917generated when using the procedural interface. These variables are usually
918C<local>ized in a block so that other parts of the code are not affected by
919the change.
920
921These variables determine the default state of the object created by calling
922the C<new> method, but cannot be used to alter the state of the object
923thereafter. The equivalent method names should be used instead to query
924or set the internal state of the object.
925
926The method forms return the object itself when called with arguments,
927so that they can be chained together nicely.
928
929=over 4
930
28bf64cc
JH
931=item *
932
933$Data::Dumper::Indent I<or> I<$OBJ>->Indent(I<[NEWVAL]>)
823edd99
GS
934
935Controls the style of indentation. It can be set to 0, 1, 2 or 3. Style 0
936spews output without any newlines, indentation, or spaces between list
937items. It is the most compact format possible that can still be called
938valid perl. Style 1 outputs a readable form with newlines but no fancy
939indentation (each level in the structure is simply indented by a fixed
940amount of whitespace). Style 2 (the default) outputs a very readable form
941which takes into account the length of hash keys (so the hash value lines
942up). Style 3 is like style 2, but also annotates the elements of arrays
943with their index (but the comment is on its own line, so array output
944consumes twice the number of lines). Style 2 is the default.
945
28bf64cc
JH
946=item *
947
948$Data::Dumper::Purity I<or> I<$OBJ>->Purity(I<[NEWVAL]>)
823edd99
GS
949
950Controls the degree to which the output can be C<eval>ed to recreate the
951supplied reference structures. Setting it to 1 will output additional perl
952statements that will correctly recreate nested references. The default is
9530.
954
28bf64cc
JH
955=item *
956
957$Data::Dumper::Pad I<or> I<$OBJ>->Pad(I<[NEWVAL]>)
823edd99
GS
958
959Specifies the string that will be prefixed to every line of the output.
960Empty string by default.
961
28bf64cc
JH
962=item *
963
964$Data::Dumper::Varname I<or> I<$OBJ>->Varname(I<[NEWVAL]>)
823edd99
GS
965
966Contains the prefix to use for tagging variable names in the output. The
967default is "VAR".
968
28bf64cc
JH
969=item *
970
971$Data::Dumper::Useqq I<or> I<$OBJ>->Useqq(I<[NEWVAL]>)
823edd99
GS
972
973When set, enables the use of double quotes for representing string values.
974Whitespace other than space will be represented as C<[\n\t\r]>, "unsafe"
975characters will be backslashed, and unprintable characters will be output as
976quoted octal integers. Since setting this variable imposes a performance
0f1923bd
GS
977penalty, the default is 0. C<Dump()> will run slower if this flag is set,
978since the fast XSUB implementation doesn't support it yet.
823edd99 979
28bf64cc
JH
980=item *
981
982$Data::Dumper::Terse I<or> I<$OBJ>->Terse(I<[NEWVAL]>)
823edd99
GS
983
984When set, Data::Dumper will emit single, non-self-referential values as
985atoms/terms rather than statements. This means that the C<$VAR>I<n> names
986will be avoided where possible, but be advised that such output may not
987always be parseable by C<eval>.
988
28bf64cc
JH
989=item *
990
991$Data::Dumper::Freezer I<or> $I<OBJ>->Freezer(I<[NEWVAL]>)
823edd99
GS
992
993Can be set to a method name, or to an empty string to disable the feature.
994Data::Dumper will invoke that method via the object before attempting to
995stringify it. This method can alter the contents of the object (if, for
996instance, it contains data allocated from C), and even rebless it in a
997different package. The client is responsible for making sure the specified
998method can be called via the object, and that the object ends up containing
999only perl data types after the method has been called. Defaults to an empty
1000string.
1001
c5f7c514
ST
1002If an object does not support the method specified (determined using
1003UNIVERSAL::can()) then the call will be skipped. If the method dies a
1004warning will be generated.
1005
28bf64cc
JH
1006=item *
1007
1008$Data::Dumper::Toaster I<or> $I<OBJ>->Toaster(I<[NEWVAL]>)
823edd99
GS
1009
1010Can be set to a method name, or to an empty string to disable the feature.
1011Data::Dumper will emit a method call for any objects that are to be dumped
8e5f9a6e 1012using the syntax C<bless(DATA, CLASS)-E<gt>METHOD()>. Note that this means that
823edd99
GS
1013the method specified will have to perform any modifications required on the
1014object (like creating new state within it, and/or reblessing it in a
1015different package) and then return it. The client is responsible for making
1016sure the method can be called via the object, and that it returns a valid
1017object. Defaults to an empty string.
1018
28bf64cc
JH
1019=item *
1020
1021$Data::Dumper::Deepcopy I<or> $I<OBJ>->Deepcopy(I<[NEWVAL]>)
823edd99
GS
1022
1023Can be set to a boolean value to enable deep copies of structures.
1024Cross-referencing will then only be done when absolutely essential
1025(i.e., to break reference cycles). Default is 0.
1026
28bf64cc
JH
1027=item *
1028
1029$Data::Dumper::Quotekeys I<or> $I<OBJ>->Quotekeys(I<[NEWVAL]>)
823edd99
GS
1030
1031Can be set to a boolean value to control whether hash keys are quoted.
1032A false value will avoid quoting hash keys when it looks like a simple
1033string. Default is 1, which will always enclose hash keys in quotes.
1034
28bf64cc
JH
1035=item *
1036
1037$Data::Dumper::Bless I<or> $I<OBJ>->Bless(I<[NEWVAL]>)
823edd99
GS
1038
1039Can be set to a string that specifies an alternative to the C<bless>
1040builtin operator used to create objects. A function with the specified
1041name should exist, and should accept the same arguments as the builtin.
1042Default is C<bless>.
1043
28bf64cc
JH
1044=item *
1045
30b4f386 1046$Data::Dumper::Pair I<or> $I<OBJ>->Pair(I<[NEWVAL]>)
1047
1048Can be set to a string that specifies the separator between hash keys
1049and values. To dump nested hash, array and scalar values to JavaScript,
1050use: C<$Data::Dumper::Pair = ' : ';>. Implementing C<bless> in JavaScript
1051is left as an exercise for the reader.
1052A function with the specified name exists, and accepts the same arguments
1053as the builtin.
1054
1055Default is: C< =E<gt> >.
1056
1057=item *
1058
28bf64cc 1059$Data::Dumper::Maxdepth I<or> $I<OBJ>->Maxdepth(I<[NEWVAL]>)
a2126434
JN
1060
1061Can be set to a positive integer that specifies the depth beyond which
5e603302 1062we don't venture into a structure. Has no effect when
a2126434
JN
1063C<Data::Dumper::Purity> is set. (Useful in debugger when we often don't
1064want to see more than enough). Default is 0, which means there is
1065no maximum depth.
1066
28bf64cc
JH
1067=item *
1068
1069$Data::Dumper::Useperl I<or> $I<OBJ>->Useperl(I<[NEWVAL]>)
31a725b3
JH
1070
1071Can be set to a boolean value which controls whether the pure Perl
1072implementation of C<Data::Dumper> is used. The C<Data::Dumper> module is
1073a dual implementation, with almost all functionality written in both
1074pure Perl and also in XS ('C'). Since the XS version is much faster, it
1075will always be used if possible. This option lets you override the
1076default behavior, usually for testing purposes only. Default is 0, which
1077means the XS implementation will be used if possible.
1078
28bf64cc
JH
1079=item *
1080
1081$Data::Dumper::Sortkeys I<or> $I<OBJ>->Sortkeys(I<[NEWVAL]>)
31a725b3
JH
1082
1083Can be set to a boolean value to control whether hash keys are dumped in
1084sorted order. A true value will cause the keys of all hashes to be
1085dumped in Perl's default sort order. Can also be set to a subroutine
1086reference which will be called for each hash that is dumped. In this
1087case C<Data::Dumper> will call the subroutine once for each hash,
1088passing it the reference of the hash. The purpose of the subroutine is
1089to return a reference to an array of the keys that will be dumped, in
1090the order that they should be dumped. Using this feature, you can
1091control both the order of the keys, and which keys are actually used. In
1092other words, this subroutine acts as a filter by which you can exclude
1093certain keys from being dumped. Default is 0, which means that hash keys
1094are not sorted.
1095
28bf64cc
JH
1096=item *
1097
1098$Data::Dumper::Deparse I<or> $I<OBJ>->Deparse(I<[NEWVAL]>)
8e5f9a6e
RGS
1099
1100Can be set to a boolean value to control whether code references are
1101turned into perl source code. If set to a true value, C<B::Deparse>
1102will be used to get the source of the code reference. Using this option
1103will force using the Perl implementation of the dumper, since the fast
1104XSUB implementation doesn't support it.
1105
1106Caution : use this option only if you know that your coderefs will be
1107properly reconstructed by C<B::Deparse>.
1108
d424882c
SM
1109=item *
1110
1111$Data::Dumper::Sparseseen I<or> $I<OBJ>->Sparseseen(I<[NEWVAL]>)
1112
1113By default, Data::Dumper builds up the "seen" hash of scalars that
1114it has encountered during serialization. This is very expensive.
1115This seen hash is necessary to support and even just detect circular
1116references. It is exposed to the user via the C<Seen()> call both
1117for writing and reading.
1118
1119If you, as a user, do not need explicit access to the "seen" hash,
1120then you can set the C<Sparseseen> option to allow Data::Dumper
1121to eschew building the "seen" hash for scalars that are known not
1122to possess more than one reference. This speeds up serialization
1123considerably if you use the XS implementation.
1124
1125Note: If you turn on C<Sparseseen>, then you must not rely on the
1126content of the seen hash since its contents will be an
1127implementation detail!
1128
823edd99
GS
1129=back
1130
1131=head2 Exports
1132
1133=over 4
1134
1135=item Dumper
1136
1137=back
1138
1139=head1 EXAMPLES
1140
1141Run these code snippets to get a quick feel for the behavior of this
1142module. When you are through with these examples, you may want to
1143add or change the various configuration variables described above,
1144to see their behavior. (See the testsuite in the Data::Dumper
1145distribution for more examples.)
1146
1147
1148 use Data::Dumper;
1149
1150 package Foo;
1151 sub new {bless {'a' => 1, 'b' => sub { return "foo" }}, $_[0]};
1152
1153 package Fuz; # a weird REF-REF-SCALAR object
1154 sub new {bless \($_ = \ 'fu\'z'), $_[0]};
1155
1156 package main;
1157 $foo = Foo->new;
1158 $fuz = Fuz->new;
1159 $boo = [ 1, [], "abcd", \*foo,
1160 {1 => 'a', 023 => 'b', 0x45 => 'c'},
1161 \\"p\q\'r", $foo, $fuz];
3cb6de81 1162
823edd99
GS
1163 ########
1164 # simple usage
1165 ########
1166
1167 $bar = eval(Dumper($boo));
1168 print($@) if $@;
1169 print Dumper($boo), Dumper($bar); # pretty print (no array indices)
1170
b877fea2
FC
1171 $Data::Dumper::Terse = 1; # don't output names where feasible
1172 $Data::Dumper::Indent = 0; # turn off all pretty print
823edd99
GS
1173 print Dumper($boo), "\n";
1174
b877fea2 1175 $Data::Dumper::Indent = 1; # mild pretty print
823edd99
GS
1176 print Dumper($boo);
1177
b877fea2 1178 $Data::Dumper::Indent = 3; # pretty print with array indices
823edd99
GS
1179 print Dumper($boo);
1180
b877fea2 1181 $Data::Dumper::Useqq = 1; # print strings in double quotes
823edd99 1182 print Dumper($boo);
3cb6de81 1183
b877fea2 1184 $Data::Dumper::Pair = " : "; # specify hash key/value separator
30b4f386 1185 print Dumper($boo);
1186
3cb6de81 1187
823edd99
GS
1188 ########
1189 # recursive structures
1190 ########
3cb6de81 1191
823edd99
GS
1192 @c = ('c');
1193 $c = \@c;
1194 $b = {};
1195 $a = [1, $b, $c];
1196 $b->{a} = $a;
1197 $b->{b} = $a->[1];
1198 $b->{c} = $a->[2];
1199 print Data::Dumper->Dump([$a,$b,$c], [qw(a b c)]);
3cb6de81
GS
1200
1201
823edd99
GS
1202 $Data::Dumper::Purity = 1; # fill in the holes for eval
1203 print Data::Dumper->Dump([$a, $b], [qw(*a b)]); # print as @a
1204 print Data::Dumper->Dump([$b, $a], [qw(*b a)]); # print as %b
3cb6de81
GS
1205
1206
823edd99
GS
1207 $Data::Dumper::Deepcopy = 1; # avoid cross-refs
1208 print Data::Dumper->Dump([$b, $a], [qw(*b a)]);
3cb6de81
GS
1209
1210
823edd99
GS
1211 $Data::Dumper::Purity = 0; # avoid cross-refs
1212 print Data::Dumper->Dump([$b, $a], [qw(*b a)]);
3cb6de81 1213
a2126434
JN
1214 ########
1215 # deep structures
1216 ########
3cb6de81 1217
a2126434
JN
1218 $a = "pearl";
1219 $b = [ $a ];
1220 $c = { 'b' => $b };
1221 $d = [ $c ];
1222 $e = { 'd' => $d };
1223 $f = { 'e' => $e };
1224 print Data::Dumper->Dump([$f], [qw(f)]);
1225
1226 $Data::Dumper::Maxdepth = 3; # no deeper than 3 refs down
1227 print Data::Dumper->Dump([$f], [qw(f)]);
1228
3cb6de81 1229
823edd99
GS
1230 ########
1231 # object-oriented usage
1232 ########
3cb6de81 1233
823edd99
GS
1234 $d = Data::Dumper->new([$a,$b], [qw(a b)]);
1235 $d->Seen({'*c' => $c}); # stash a ref without printing it
1236 $d->Indent(3);
1237 print $d->Dump;
1238 $d->Reset->Purity(0); # empty the seen cache
1239 print join "----\n", $d->Dump;
3cb6de81
GS
1240
1241
823edd99
GS
1242 ########
1243 # persistence
1244 ########
3cb6de81 1245
823edd99
GS
1246 package Foo;
1247 sub new { bless { state => 'awake' }, shift }
1248 sub Freeze {
1249 my $s = shift;
1250 print STDERR "preparing to sleep\n";
1251 $s->{state} = 'asleep';
1252 return bless $s, 'Foo::ZZZ';
1253 }
3cb6de81 1254
823edd99
GS
1255 package Foo::ZZZ;
1256 sub Thaw {
1257 my $s = shift;
1258 print STDERR "waking up\n";
1259 $s->{state} = 'awake';
1260 return bless $s, 'Foo';
1261 }
3cb6de81 1262
823edd99
GS
1263 package Foo;
1264 use Data::Dumper;
1265 $a = Foo->new;
1266 $b = Data::Dumper->new([$a], ['c']);
1267 $b->Freezer('Freeze');
1268 $b->Toaster('Thaw');
1269 $c = $b->Dump;
1270 print $c;
1271 $d = eval $c;
1272 print Data::Dumper->Dump([$d], ['d']);
3cb6de81
GS
1273
1274
823edd99
GS
1275 ########
1276 # symbol substitution (useful for recreating CODE refs)
1277 ########
3cb6de81 1278
823edd99
GS
1279 sub foo { print "foo speaking\n" }
1280 *other = \&foo;
1281 $bar = [ \&other ];
1282 $d = Data::Dumper->new([\&other,$bar],['*other','bar']);
1283 $d->Seen({ '*foo' => \&foo });
1284 print $d->Dump;
1285
1286
31a725b3
JH
1287 ########
1288 # sorting and filtering hash keys
1289 ########
1290
1291 $Data::Dumper::Sortkeys = \&my_filter;
1292 my $foo = { map { (ord, "$_$_$_") } 'I'..'Q' };
1293 my $bar = { %$foo };
1294 my $baz = { reverse %$foo };
1295 print Dumper [ $foo, $bar, $baz ];
1296
1297 sub my_filter {
1298 my ($hash) = @_;
1299 # return an array ref containing the hash keys to dump
1300 # in the order that you want them to be dumped
1301 return [
1302 # Sort the keys of %$foo in reverse numeric order
1303 $hash eq $foo ? (sort {$b <=> $a} keys %$hash) :
1304 # Only dump the odd number keys of %$bar
1305 $hash eq $bar ? (grep {$_ % 2} keys %$hash) :
1306 # Sort keys in default order for all other hashes
1307 (sort keys %$hash)
1308 ];
1309 }
1310
823edd99
GS
1311=head1 BUGS
1312
1313Due to limitations of Perl subroutine call semantics, you cannot pass an
1314array or hash. Prepend it with a C<\> to pass its reference instead. This
8e5f9a6e
RGS
1315will be remedied in time, now that Perl has subroutine prototypes.
1316For now, you need to use the extended usage form, and prepend the
823edd99
GS
1317name with a C<*> to output it as a hash or array.
1318
1319C<Data::Dumper> cheats with CODE references. If a code reference is
8e5f9a6e
RGS
1320encountered in the structure being processed (and if you haven't set
1321the C<Deparse> flag), an anonymous subroutine that
823edd99
GS
1322contains the string '"DUMMY"' will be inserted in its place, and a warning
1323will be printed if C<Purity> is set. You can C<eval> the result, but bear
1324in mind that the anonymous sub that gets created is just a placeholder.
1325Someday, perl will have a switch to cache-on-demand the string
1326representation of a compiled piece of code, I hope. If you have prior
1327knowledge of all the code refs that your data structures are likely
1328to have, you can use the C<Seen> method to pre-seed the internal reference
00baac8f 1329table and make the dumped output point to them, instead. See L</EXAMPLES>
823edd99
GS
1330above.
1331
8e5f9a6e
RGS
1332The C<Useqq> and C<Deparse> flags makes Dump() run slower, since the
1333XSUB implementation does not support them.
823edd99
GS
1334
1335SCALAR objects have the weirdest looking C<bless> workaround.
1336
fec5e1eb
IM
1337Pure Perl version of C<Data::Dumper> escapes UTF-8 strings correctly
1338only in Perl 5.8.0 and later.
1339
504f80c1
JH
1340=head2 NOTE
1341
1342Starting from Perl 5.8.1 different runs of Perl will have different
1343ordering of hash keys. The change was done for greater security,
1344see L<perlsec/"Algorithmic Complexity Attacks">. This means that
1345different runs of Perl will have different Data::Dumper outputs if
1346the data contains hashes. If you need to have identical Data::Dumper
1347outputs from different runs of Perl, use the environment variable
1348PERL_HASH_SEED, see L<perlrun/PERL_HASH_SEED>. Using this restores
1349the old (platform-specific) ordering: an even prettier solution might
1350be to use the C<Sortkeys> filter of Data::Dumper.
823edd99
GS
1351
1352=head1 AUTHOR
1353
6e238990 1354Gurusamy Sarathy gsar@activestate.com
823edd99
GS
1355
1356Copyright (c) 1996-98 Gurusamy Sarathy. All rights reserved.
1357This program is free software; you can redistribute it and/or
1358modify it under the same terms as Perl itself.
1359
823edd99
GS
1360=head1 VERSION
1361
be022d23 1362Version 2.141 (January 13 2013)
823edd99
GS
1363
1364=head1 SEE ALSO
1365
1366perl(1)
1367
1368=cut