This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
First steps of making builds outside the source
[perl5.git] / ext / 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
c8984b0b 12$VERSION = $VERSION = '2.101';
823edd99
GS
13
14#$| = 1;
15
16require 5.004;
17require Exporter;
18require DynaLoader;
19require overload;
20
21use Carp;
22
23@ISA = qw(Exporter DynaLoader);
24@EXPORT = qw(Dumper);
25@EXPORT_OK = qw(DumperX);
26
27bootstrap Data::Dumper;
28
29# module vars and their defaults
30$Indent = 2 unless defined $Indent;
31$Purity = 0 unless defined $Purity;
32$Pad = "" unless defined $Pad;
33$Varname = "VAR" unless defined $Varname;
34$Useqq = 0 unless defined $Useqq;
35$Terse = 0 unless defined $Terse;
36$Freezer = "" unless defined $Freezer;
37$Toaster = "" unless defined $Toaster;
38$Deepcopy = 0 unless defined $Deepcopy;
39$Quotekeys = 1 unless defined $Quotekeys;
40$Bless = "bless" unless defined $Bless;
41#$Expdepth = 0 unless defined $Expdepth;
42#$Maxdepth = 0 unless defined $Maxdepth;
43
44#
45# expects an arrayref of values to be dumped.
46# can optionally pass an arrayref of names for the values.
47# names must have leading $ sign stripped. begin the name with *
48# to cause output of arrays and hashes rather than refs.
49#
50sub new {
51 my($c, $v, $n) = @_;
52
53 croak "Usage: PACKAGE->new(ARRAYREF, [ARRAYREF])"
54 unless (defined($v) && (ref($v) eq 'ARRAY'));
55 $n = [] unless (defined($n) && (ref($v) eq 'ARRAY'));
56
57 my($s) = {
58 level => 0, # current recursive depth
59 indent => $Indent, # various styles of indenting
60 pad => $Pad, # all lines prefixed by this string
61 xpad => "", # padding-per-level
62 apad => "", # added padding for hash keys n such
63 sep => "", # list separator
64 seen => {}, # local (nested) refs (id => [name, val])
65 todump => $v, # values to dump []
66 names => $n, # optional names for values []
67 varname => $Varname, # prefix to use for tagging nameless ones
68 purity => $Purity, # degree to which output is evalable
69 useqq => $Useqq, # use "" for strings (backslashitis ensues)
70 terse => $Terse, # avoid name output (where feasible)
71 freezer => $Freezer, # name of Freezer method for objects
72 toaster => $Toaster, # name of method to revive objects
73 deepcopy => $Deepcopy, # dont cross-ref, except to stop recursion
74 quotekeys => $Quotekeys, # quote hash keys
75 'bless' => $Bless, # keyword to use for "bless"
76# expdepth => $Expdepth, # cutoff depth for explicit dumping
77# maxdepth => $Maxdepth, # depth beyond which we give up
78 };
79
80 if ($Indent > 0) {
81 $s->{xpad} = " ";
82 $s->{sep} = "\n";
83 }
84 return bless($s, $c);
85}
86
87#
88# add-to or query the table of already seen references
89#
90sub Seen {
91 my($s, $g) = @_;
92 if (defined($g) && (ref($g) eq 'HASH')) {
93 my($k, $v, $id);
94 while (($k, $v) = each %$g) {
95 if (defined $v and ref $v) {
96 ($id) = (overload::StrVal($v) =~ /\((.*)\)$/);
97 if ($k =~ /^[*](.*)$/) {
98 $k = (ref $v eq 'ARRAY') ? ( "\\\@" . $1 ) :
99 (ref $v eq 'HASH') ? ( "\\\%" . $1 ) :
100 (ref $v eq 'CODE') ? ( "\\\&" . $1 ) :
101 ( "\$" . $1 ) ;
102 }
103 elsif ($k !~ /^\$/) {
104 $k = "\$" . $k;
105 }
106 $s->{seen}{$id} = [$k, $v];
107 }
108 else {
109 carp "Only refs supported, ignoring non-ref item \$$k";
110 }
111 }
112 return $s;
113 }
114 else {
115 return map { @$_ } values %{$s->{seen}};
116 }
117}
118
119#
120# set or query the values to be dumped
121#
122sub Values {
123 my($s, $v) = @_;
124 if (defined($v) && (ref($v) eq 'ARRAY')) {
125 $s->{todump} = [@$v]; # make a copy
126 return $s;
127 }
128 else {
129 return @{$s->{todump}};
130 }
131}
132
133#
134# set or query the names of the values to be dumped
135#
136sub Names {
137 my($s, $n) = @_;
138 if (defined($n) && (ref($n) eq 'ARRAY')) {
139 $s->{names} = [@$n]; # make a copy
140 return $s;
141 }
142 else {
143 return @{$s->{names}};
144 }
145}
146
147sub DESTROY {}
148
149#
150# dump the refs in the current dumper object.
151# expects same args as new() if called via package name.
152#
153sub Dump {
154 my($s) = shift;
155 my(@out, $val, $name);
156 my($i) = 0;
157 local(@post);
158
159 $s = $s->new(@_) unless ref $s;
160
161 for $val (@{$s->{todump}}) {
162 my $out = "";
163 @post = ();
164 $name = $s->{names}[$i++];
165 if (defined $name) {
166 if ($name =~ /^[*](.*)$/) {
167 if (defined $val) {
168 $name = (ref $val eq 'ARRAY') ? ( "\@" . $1 ) :
169 (ref $val eq 'HASH') ? ( "\%" . $1 ) :
170 (ref $val eq 'CODE') ? ( "\*" . $1 ) :
171 ( "\$" . $1 ) ;
172 }
173 else {
174 $name = "\$" . $1;
175 }
176 }
177 elsif ($name !~ /^\$/) {
178 $name = "\$" . $name;
179 }
180 }
181 else {
182 $name = "\$" . $s->{varname} . $i;
183 }
184
185 my $valstr;
186 {
187 local($s->{apad}) = $s->{apad};
188 $s->{apad} .= ' ' x (length($name) + 3) if $s->{indent} >= 2;
189 $valstr = $s->_dump($val, $name);
190 }
191
192 $valstr = "$name = " . $valstr . ';' if @post or !$s->{terse};
193 $out .= $s->{pad} . $valstr . $s->{sep};
194 $out .= $s->{pad} . join(';' . $s->{sep} . $s->{pad}, @post)
195 . ';' . $s->{sep} if @post;
196
197 push @out, $out;
198 }
199 return wantarray ? @out : join('', @out);
200}
201
202#
203# twist, toil and turn;
204# and recurse, of course.
205#
206sub _dump {
207 my($s, $val, $name) = @_;
208 my($sname);
209 my($out, $realpack, $realtype, $type, $ipad, $id, $blesspad);
210
823edd99
GS
211 $type = ref $val;
212 $out = "";
213
214 if ($type) {
215
216 # prep it, if it looks like an object
217 if ($type =~ /[a-z_:]/) {
218 my $freezer = $s->{freezer};
7820172a 219 $val->$freezer() if $freezer && UNIVERSAL::can($val, $freezer);
823edd99
GS
220 }
221
222 ($realpack, $realtype, $id) =
223 (overload::StrVal($val) =~ /^(?:(.*)\=)?([^=]*)\(([^\(]*)\)$/);
224
7820172a
GS
225 # if it has a name, we need to either look it up, or keep a tab
226 # on it so we know when we hit it later
227 if (defined($name) and length($name)) {
228 # keep a tab on it so that we dont fall into recursive pit
229 if (exists $s->{seen}{$id}) {
230# if ($s->{expdepth} < $s->{level}) {
231 if ($s->{purity} and $s->{level} > 0) {
232 $out = ($realtype eq 'HASH') ? '{}' :
233 ($realtype eq 'ARRAY') ? '[]' :
234 "''" ;
235 push @post, $name . " = " . $s->{seen}{$id}[0];
823edd99
GS
236 }
237 else {
7820172a
GS
238 $out = $s->{seen}{$id}[0];
239 if ($name =~ /^([\@\%])/) {
240 my $start = $1;
241 if ($out =~ /^\\$start/) {
242 $out = substr($out, 1);
243 }
244 else {
245 $out = $start . '{' . $out . '}';
246 }
247 }
248 }
249 return $out;
250# }
251 }
252 else {
253 # store our name
254 $s->{seen}{$id} = [ (($name =~ /^[@%]/) ? ('\\' . $name ) :
255 ($realtype eq 'CODE' and
256 $name =~ /^[*](.*)$/) ? ('\\&' . $1 ) :
257 $name ),
258 $val ];
823edd99 259 }
823edd99
GS
260 }
261
f6b3007c
JH
262 if ($realpack) {
263 if ($realpack eq 'Regexp') {
264 $out = "$val";
265 $out =~ s,/,\\/,g;
266 return "qr/$out/";
267 }
268 else { # we have a blessed ref
269 $out = $s->{'bless'} . '( ';
270 $blesspad = $s->{apad};
271 $s->{apad} .= ' ' if ($s->{indent} >= 2);
272 }
273 }
274
823edd99
GS
275 $s->{level}++;
276 $ipad = $s->{xpad} x $s->{level};
277
823edd99
GS
278
279 if ($realtype eq 'SCALAR') {
280 if ($realpack) {
7820172a 281 $out .= 'do{\\(my $o = ' . $s->_dump($$val, "\${$name}") . ')}';
823edd99
GS
282 }
283 else {
7820172a 284 $out .= '\\' . $s->_dump($$val, "\${$name}");
823edd99
GS
285 }
286 }
287 elsif ($realtype eq 'GLOB') {
7820172a 288 $out .= '\\' . $s->_dump($$val, "*{$name}");
823edd99
GS
289 }
290 elsif ($realtype eq 'ARRAY') {
291 my($v, $pad, $mname);
292 my($i) = 0;
293 $out .= ($name =~ /^\@/) ? '(' : '[';
294 $pad = $s->{sep} . $s->{pad} . $s->{apad};
295 ($name =~ /^\@(.*)$/) ? ($mname = "\$" . $1) :
7820172a
GS
296 # omit -> if $foo->[0]->{bar}, but not ${$foo->[0]}->{bar}
297 ($name =~ /^\\?[\%\@\*\$][^{].*[]}]$/) ? ($mname = $name) :
298 ($mname = $name . '->');
823edd99
GS
299 $mname .= '->' if $mname =~ /^\*.+\{[A-Z]+\}$/;
300 for $v (@$val) {
301 $sname = $mname . '[' . $i . ']';
302 $out .= $pad . $ipad . '#' . $i if $s->{indent} >= 3;
303 $out .= $pad . $ipad . $s->_dump($v, $sname);
304 $out .= "," if $i++ < $#$val;
305 }
306 $out .= $pad . ($s->{xpad} x ($s->{level} - 1)) if $i;
307 $out .= ($name =~ /^\@/) ? ')' : ']';
308 }
309 elsif ($realtype eq 'HASH') {
310 my($k, $v, $pad, $lpad, $mname);
311 $out .= ($name =~ /^\%/) ? '(' : '{';
312 $pad = $s->{sep} . $s->{pad} . $s->{apad};
313 $lpad = $s->{apad};
7820172a
GS
314 ($name =~ /^\%(.*)$/) ? ($mname = "\$" . $1) :
315 # omit -> if $foo->[0]->{bar}, but not ${$foo->[0]}->{bar}
316 ($name =~ /^\\?[\%\@\*\$][^{].*[]}]$/) ? ($mname = $name) :
317 ($mname = $name . '->');
823edd99
GS
318 $mname .= '->' if $mname =~ /^\*.+\{[A-Z]+\}$/;
319 while (($k, $v) = each %$val) {
320 my $nk = $s->_dump($k, "");
321 $nk = $1 if !$s->{quotekeys} and $nk =~ /^[\"\']([A-Za-z_]\w*)[\"\']$/;
322 $sname = $mname . '{' . $nk . '}';
323 $out .= $pad . $ipad . $nk . " => ";
324
325 # temporarily alter apad
326 $s->{apad} .= (" " x (length($nk) + 4)) if $s->{indent} >= 2;
327 $out .= $s->_dump($val->{$k}, $sname) . ",";
328 $s->{apad} = $lpad if $s->{indent} >= 2;
329 }
330 if (substr($out, -1) eq ',') {
331 chop $out;
332 $out .= $pad . ($s->{xpad} x ($s->{level} - 1));
333 }
334 $out .= ($name =~ /^\%/) ? ')' : '}';
335 }
336 elsif ($realtype eq 'CODE') {
c8984b0b 337 $out .= 'sub { "DUMMY" }';
823edd99
GS
338 carp "Encountered CODE ref, using dummy placeholder" if $s->{purity};
339 }
340 else {
341 croak "Can\'t handle $realtype type.";
342 }
343
344 if ($realpack) { # we have a blessed ref
345 $out .= ', \'' . $realpack . '\'' . ' )';
346 $out .= '->' . $s->{toaster} . '()' if $s->{toaster} ne '';
347 $s->{apad} = $blesspad;
348 }
349 $s->{level}--;
350
351 }
352 else { # simple scalar
353
354 my $ref = \$_[1];
355 # first, catalog the scalar
356 if ($name ne '') {
357 ($id) = ("$ref" =~ /\(([^\(]*)\)$/);
358 if (exists $s->{seen}{$id}) {
7820172a
GS
359 if ($s->{seen}{$id}[2]) {
360 $out = $s->{seen}{$id}[0];
361 #warn "[<$out]\n";
362 return "\${$out}";
363 }
823edd99
GS
364 }
365 else {
7820172a
GS
366 #warn "[>\\$name]\n";
367 $s->{seen}{$id} = ["\\$name", $ref];
823edd99
GS
368 }
369 }
370 if (ref($ref) eq 'GLOB' or "$ref" =~ /=GLOB\([^()]+\)$/) { # glob
371 my $name = substr($val, 1);
372 if ($name =~ /^[A-Za-z_][\w:]*$/) {
373 $name =~ s/^main::/::/;
374 $sname = $name;
375 }
376 else {
377 $sname = $s->_dump($name, "");
378 $sname = '{' . $sname . '}';
379 }
380 if ($s->{purity}) {
381 my $k;
382 local ($s->{level}) = 0;
383 for $k (qw(SCALAR ARRAY HASH)) {
7820172a
GS
384 my $gval = *$val{$k};
385 next unless defined $gval;
386 next if $k eq "SCALAR" && ! defined $$gval; # always there
387
823edd99
GS
388 # _dump can push into @post, so we hold our place using $postlen
389 my $postlen = scalar @post;
390 $post[$postlen] = "\*$sname = ";
391 local ($s->{apad}) = " " x length($post[$postlen]) if $s->{indent} >= 2;
7820172a 392 $post[$postlen] .= $s->_dump($gval, "\*$sname\{$k\}");
823edd99
GS
393 }
394 }
395 $out .= '*' . $sname;
396 }
7820172a
GS
397 elsif (!defined($val)) {
398 $out .= "undef";
399 }
45b49486 400 elsif ($val =~ /^(?:0|-?[1-9]\d{0,8})$/) { # safe decimal number
823edd99
GS
401 $out .= $val;
402 }
403 else { # string
404 if ($s->{useqq}) {
7820172a 405 $out .= qquote($val, $s->{useqq});
823edd99
GS
406 }
407 else {
408 $val =~ s/([\\\'])/\\$1/g;
409 $out .= '\'' . $val . '\'';
410 }
411 }
412 }
7820172a
GS
413 if ($id) {
414 # if we made it this far, $id was added to seen list at current
415 # level, so remove it to get deep copies
416 if ($s->{deepcopy}) {
417 delete($s->{seen}{$id});
418 }
419 elsif ($name) {
420 $s->{seen}{$id}[2] = 1;
421 }
422 }
823edd99
GS
423 return $out;
424}
425
426#
427# non-OO style of earlier version
428#
429sub Dumper {
430 return Data::Dumper->Dump([@_]);
431}
432
433#
434# same, only calls the XS version
435#
436sub DumperX {
437 return Data::Dumper->Dumpxs([@_], []);
438}
439
440sub Dumpf { return Data::Dumper->Dump(@_) }
441
442sub Dumpp { print Data::Dumper->Dump(@_) }
443
444#
445# reset the "seen" cache
446#
447sub Reset {
448 my($s) = shift;
449 $s->{seen} = {};
450 return $s;
451}
452
453sub Indent {
454 my($s, $v) = @_;
455 if (defined($v)) {
456 if ($v == 0) {
457 $s->{xpad} = "";
458 $s->{sep} = "";
459 }
460 else {
461 $s->{xpad} = " ";
462 $s->{sep} = "\n";
463 }
464 $s->{indent} = $v;
465 return $s;
466 }
467 else {
468 return $s->{indent};
469 }
470}
471
472sub Pad {
473 my($s, $v) = @_;
474 defined($v) ? (($s->{pad} = $v), return $s) : $s->{pad};
475}
476
477sub Varname {
478 my($s, $v) = @_;
479 defined($v) ? (($s->{varname} = $v), return $s) : $s->{varname};
480}
481
482sub Purity {
483 my($s, $v) = @_;
484 defined($v) ? (($s->{purity} = $v), return $s) : $s->{purity};
485}
486
487sub Useqq {
488 my($s, $v) = @_;
489 defined($v) ? (($s->{useqq} = $v), return $s) : $s->{useqq};
490}
491
492sub Terse {
493 my($s, $v) = @_;
494 defined($v) ? (($s->{terse} = $v), return $s) : $s->{terse};
495}
496
497sub Freezer {
498 my($s, $v) = @_;
499 defined($v) ? (($s->{freezer} = $v), return $s) : $s->{freezer};
500}
501
502sub Toaster {
503 my($s, $v) = @_;
504 defined($v) ? (($s->{toaster} = $v), return $s) : $s->{toaster};
505}
506
507sub Deepcopy {
508 my($s, $v) = @_;
509 defined($v) ? (($s->{deepcopy} = $v), return $s) : $s->{deepcopy};
510}
511
512sub Quotekeys {
513 my($s, $v) = @_;
514 defined($v) ? (($s->{quotekeys} = $v), return $s) : $s->{quotekeys};
515}
516
517sub Bless {
518 my($s, $v) = @_;
519 defined($v) ? (($s->{'bless'} = $v), return $s) : $s->{'bless'};
520}
521
7820172a
GS
522# used by qquote below
523my %esc = (
524 "\a" => "\\a",
525 "\b" => "\\b",
526 "\t" => "\\t",
527 "\n" => "\\n",
528 "\f" => "\\f",
529 "\r" => "\\r",
530 "\e" => "\\e",
531);
532
823edd99
GS
533# put a string value in double quotes
534sub qquote {
535 local($_) = shift;
7820172a
GS
536 s/([\\\"\@\$])/\\$1/g;
537 return qq("$_") unless /[^\040-\176]/; # fast exit
538
539 my $high = shift || "";
540 s/([\a\b\t\n\f\r\e])/$esc{$1}/g;
541
542 # no need for 3 digits in escape for these
543 s/([\0-\037])(?!\d)/'\\'.sprintf('%o',ord($1))/eg;
544
545 s/([\0-\037\177])/'\\'.sprintf('%03o',ord($1))/eg;
546 if ($high eq "iso8859") {
547 s/([\200-\240])/'\\'.sprintf('%o',ord($1))/eg;
548 } elsif ($high eq "utf8") {
549# use utf8;
550# $str =~ s/([^\040-\176])/sprintf "\\x{%04x}", ord($1)/ge;
551 } elsif ($high eq "8bit") {
552 # leave it as it is
553 } else {
554 s/([\0-\037\177-\377])/'\\'.sprintf('%03o',ord($1))/eg;
555 }
556 return qq("$_");
823edd99
GS
557}
558
5591;
560__END__
561
562=head1 NAME
563
564Data::Dumper - stringified perl data structures, suitable for both printing and C<eval>
565
566
567=head1 SYNOPSIS
568
569 use Data::Dumper;
570
571 # simple procedural interface
572 print Dumper($foo, $bar);
573
574 # extended usage with names
575 print Data::Dumper->Dump([$foo, $bar], [qw(foo *ary)]);
576
577 # configuration variables
578 {
579 local $Data::Dump::Purity = 1;
580 eval Data::Dumper->Dump([$foo, $bar], [qw(foo *ary)]);
581 }
582
583 # OO usage
584 $d = Data::Dumper->new([$foo, $bar], [qw(foo *ary)]);
585 ...
586 print $d->Dump;
587 ...
588 $d->Purity(1)->Terse(1)->Deepcopy(1);
589 eval $d->Dump;
590
591
592=head1 DESCRIPTION
593
594Given a list of scalars or reference variables, writes out their contents in
595perl syntax. The references can also be objects. The contents of each
596variable is output in a single Perl statement. Handles self-referential
597structures correctly.
598
599The return value can be C<eval>ed to get back an identical copy of the
600original reference structure.
601
602Any references that are the same as one of those passed in will be named
603C<$VAR>I<n> (where I<n> is a numeric suffix), and other duplicate references
604to substructures within C<$VAR>I<n> will be appropriately labeled using arrow
605notation. You can specify names for individual values to be dumped if you
606use the C<Dump()> method, or you can change the default C<$VAR> prefix to
607something else. See C<$Data::Dumper::Varname> and C<$Data::Dumper::Terse>
608below.
609
610The default output of self-referential structures can be C<eval>ed, but the
611nested references to C<$VAR>I<n> will be undefined, since a recursive
612structure cannot be constructed using one Perl statement. You should set the
613C<Purity> flag to 1 to get additional statements that will correctly fill in
614these references.
615
616In the extended usage form, the references to be dumped can be given
617user-specified names. If a name begins with a C<*>, the output will
618describe the dereferenced type of the supplied reference for hashes and
619arrays, and coderefs. Output of names will be avoided where possible if
620the C<Terse> flag is set.
621
622In many cases, methods that are used to set the internal state of the
623object will return the object itself, so method calls can be conveniently
624chained together.
625
626Several styles of output are possible, all controlled by setting
627the C<Indent> flag. See L<Configuration Variables or Methods> below
628for details.
629
630
631=head2 Methods
632
633=over 4
634
635=item I<PACKAGE>->new(I<ARRAYREF [>, I<ARRAYREF]>)
636
637Returns a newly created C<Data::Dumper> object. The first argument is an
638anonymous array of values to be dumped. The optional second argument is an
639anonymous array of names for the values. The names need not have a leading
640C<$> sign, and must be comprised of alphanumeric characters. You can begin
641a name with a C<*> to specify that the dereferenced type must be dumped
642instead of the reference itself, for ARRAY and HASH references.
643
644The prefix specified by C<$Data::Dumper::Varname> will be used with a
645numeric suffix if the name for a value is undefined.
646
647Data::Dumper will catalog all references encountered while dumping the
648values. Cross-references (in the form of names of substructures in perl
649syntax) will be inserted at all possible points, preserving any structural
650interdependencies in the original set of values. Structure traversal is
651depth-first, and proceeds in order from the first supplied value to
652the last.
653
654=item I<$OBJ>->Dump I<or> I<PACKAGE>->Dump(I<ARRAYREF [>, I<ARRAYREF]>)
655
656Returns the stringified form of the values stored in the object (preserving
657the order in which they were supplied to C<new>), subject to the
658configuration options below. In an array context, it returns a list
659of strings corresponding to the supplied values.
660
661The second form, for convenience, simply calls the C<new> method on its
662arguments before dumping the object immediately.
663
664=item I<$OBJ>->Dumpxs I<or> I<PACKAGE>->Dumpxs(I<ARRAYREF [>, I<ARRAYREF]>)
665
666This method is available if you were able to compile and install the XSUB
667extension to C<Data::Dumper>. It is exactly identical to the C<Dump> method
668above, only about 4 to 5 times faster, since it is written entirely in C.
669
670=item I<$OBJ>->Seen(I<[HASHREF]>)
671
672Queries or adds to the internal table of already encountered references.
673You must use C<Reset> to explicitly clear the table if needed. Such
674references are not dumped; instead, their names are inserted wherever they
675are encountered subsequently. This is useful especially for properly
676dumping subroutine references.
677
678Expects a anonymous hash of name => value pairs. Same rules apply for names
679as in C<new>. If no argument is supplied, will return the "seen" list of
680name => value pairs, in an array context. Otherwise, returns the object
681itself.
682
683=item I<$OBJ>->Values(I<[ARRAYREF]>)
684
685Queries or replaces the internal array of values that will be dumped.
686When called without arguments, returns the values. Otherwise, returns the
687object itself.
688
689=item I<$OBJ>->Names(I<[ARRAYREF]>)
690
691Queries or replaces the internal array of user supplied names for the values
692that will be dumped. When called without arguments, returns the names.
693Otherwise, returns the object itself.
694
695=item I<$OBJ>->Reset
696
697Clears the internal table of "seen" references and returns the object
698itself.
699
700=back
701
702=head2 Functions
703
704=over 4
705
706=item Dumper(I<LIST>)
707
708Returns the stringified form of the values in the list, subject to the
709configuration options below. The values will be named C<$VAR>I<n> in the
710output, where I<n> is a numeric suffix. Will return a list of strings
711in an array context.
712
713=item DumperX(I<LIST>)
714
715Identical to the C<Dumper()> function above, but this calls the XSUB
716implementation. Only available if you were able to compile and install
717the XSUB extensions in C<Data::Dumper>.
718
719=back
720
721=head2 Configuration Variables or Methods
722
723Several configuration variables can be used to control the kind of output
724generated when using the procedural interface. These variables are usually
725C<local>ized in a block so that other parts of the code are not affected by
726the change.
727
728These variables determine the default state of the object created by calling
729the C<new> method, but cannot be used to alter the state of the object
730thereafter. The equivalent method names should be used instead to query
731or set the internal state of the object.
732
733The method forms return the object itself when called with arguments,
734so that they can be chained together nicely.
735
736=over 4
737
738=item $Data::Dumper::Indent I<or> I<$OBJ>->Indent(I<[NEWVAL]>)
739
740Controls the style of indentation. It can be set to 0, 1, 2 or 3. Style 0
741spews output without any newlines, indentation, or spaces between list
742items. It is the most compact format possible that can still be called
743valid perl. Style 1 outputs a readable form with newlines but no fancy
744indentation (each level in the structure is simply indented by a fixed
745amount of whitespace). Style 2 (the default) outputs a very readable form
746which takes into account the length of hash keys (so the hash value lines
747up). Style 3 is like style 2, but also annotates the elements of arrays
748with their index (but the comment is on its own line, so array output
749consumes twice the number of lines). Style 2 is the default.
750
751=item $Data::Dumper::Purity I<or> I<$OBJ>->Purity(I<[NEWVAL]>)
752
753Controls the degree to which the output can be C<eval>ed to recreate the
754supplied reference structures. Setting it to 1 will output additional perl
755statements that will correctly recreate nested references. The default is
7560.
757
758=item $Data::Dumper::Pad I<or> I<$OBJ>->Pad(I<[NEWVAL]>)
759
760Specifies the string that will be prefixed to every line of the output.
761Empty string by default.
762
763=item $Data::Dumper::Varname I<or> I<$OBJ>->Varname(I<[NEWVAL]>)
764
765Contains the prefix to use for tagging variable names in the output. The
766default is "VAR".
767
768=item $Data::Dumper::Useqq I<or> I<$OBJ>->Useqq(I<[NEWVAL]>)
769
770When set, enables the use of double quotes for representing string values.
771Whitespace other than space will be represented as C<[\n\t\r]>, "unsafe"
772characters will be backslashed, and unprintable characters will be output as
773quoted octal integers. Since setting this variable imposes a performance
774penalty, the default is 0. The C<Dumpxs()> method does not honor this
775flag yet.
776
777=item $Data::Dumper::Terse I<or> I<$OBJ>->Terse(I<[NEWVAL]>)
778
779When set, Data::Dumper will emit single, non-self-referential values as
780atoms/terms rather than statements. This means that the C<$VAR>I<n> names
781will be avoided where possible, but be advised that such output may not
782always be parseable by C<eval>.
783
784=item $Data::Dumper::Freezer I<or> $I<OBJ>->Freezer(I<[NEWVAL]>)
785
786Can be set to a method name, or to an empty string to disable the feature.
787Data::Dumper will invoke that method via the object before attempting to
788stringify it. This method can alter the contents of the object (if, for
789instance, it contains data allocated from C), and even rebless it in a
790different package. The client is responsible for making sure the specified
791method can be called via the object, and that the object ends up containing
792only perl data types after the method has been called. Defaults to an empty
793string.
794
795=item $Data::Dumper::Toaster I<or> $I<OBJ>->Toaster(I<[NEWVAL]>)
796
797Can be set to a method name, or to an empty string to disable the feature.
798Data::Dumper will emit a method call for any objects that are to be dumped
799using the syntax C<bless(DATA, CLASS)->METHOD()>. Note that this means that
800the method specified will have to perform any modifications required on the
801object (like creating new state within it, and/or reblessing it in a
802different package) and then return it. The client is responsible for making
803sure the method can be called via the object, and that it returns a valid
804object. Defaults to an empty string.
805
806=item $Data::Dumper::Deepcopy I<or> $I<OBJ>->Deepcopy(I<[NEWVAL]>)
807
808Can be set to a boolean value to enable deep copies of structures.
809Cross-referencing will then only be done when absolutely essential
810(i.e., to break reference cycles). Default is 0.
811
812=item $Data::Dumper::Quotekeys I<or> $I<OBJ>->Quotekeys(I<[NEWVAL]>)
813
814Can be set to a boolean value to control whether hash keys are quoted.
815A false value will avoid quoting hash keys when it looks like a simple
816string. Default is 1, which will always enclose hash keys in quotes.
817
818=item $Data::Dumper::Bless I<or> $I<OBJ>->Bless(I<[NEWVAL]>)
819
820Can be set to a string that specifies an alternative to the C<bless>
821builtin operator used to create objects. A function with the specified
822name should exist, and should accept the same arguments as the builtin.
823Default is C<bless>.
824
825=back
826
827=head2 Exports
828
829=over 4
830
831=item Dumper
832
833=back
834
835=head1 EXAMPLES
836
837Run these code snippets to get a quick feel for the behavior of this
838module. When you are through with these examples, you may want to
839add or change the various configuration variables described above,
840to see their behavior. (See the testsuite in the Data::Dumper
841distribution for more examples.)
842
843
844 use Data::Dumper;
845
846 package Foo;
847 sub new {bless {'a' => 1, 'b' => sub { return "foo" }}, $_[0]};
848
849 package Fuz; # a weird REF-REF-SCALAR object
850 sub new {bless \($_ = \ 'fu\'z'), $_[0]};
851
852 package main;
853 $foo = Foo->new;
854 $fuz = Fuz->new;
855 $boo = [ 1, [], "abcd", \*foo,
856 {1 => 'a', 023 => 'b', 0x45 => 'c'},
857 \\"p\q\'r", $foo, $fuz];
858
859 ########
860 # simple usage
861 ########
862
863 $bar = eval(Dumper($boo));
864 print($@) if $@;
865 print Dumper($boo), Dumper($bar); # pretty print (no array indices)
866
867 $Data::Dumper::Terse = 1; # don't output names where feasible
868 $Data::Dumper::Indent = 0; # turn off all pretty print
869 print Dumper($boo), "\n";
870
871 $Data::Dumper::Indent = 1; # mild pretty print
872 print Dumper($boo);
873
874 $Data::Dumper::Indent = 3; # pretty print with array indices
875 print Dumper($boo);
876
877 $Data::Dumper::Useqq = 1; # print strings in double quotes
878 print Dumper($boo);
879
880
881 ########
882 # recursive structures
883 ########
884
885 @c = ('c');
886 $c = \@c;
887 $b = {};
888 $a = [1, $b, $c];
889 $b->{a} = $a;
890 $b->{b} = $a->[1];
891 $b->{c} = $a->[2];
892 print Data::Dumper->Dump([$a,$b,$c], [qw(a b c)]);
893
894
895 $Data::Dumper::Purity = 1; # fill in the holes for eval
896 print Data::Dumper->Dump([$a, $b], [qw(*a b)]); # print as @a
897 print Data::Dumper->Dump([$b, $a], [qw(*b a)]); # print as %b
898
899
900 $Data::Dumper::Deepcopy = 1; # avoid cross-refs
901 print Data::Dumper->Dump([$b, $a], [qw(*b a)]);
902
903
904 $Data::Dumper::Purity = 0; # avoid cross-refs
905 print Data::Dumper->Dump([$b, $a], [qw(*b a)]);
906
907
908 ########
909 # object-oriented usage
910 ########
911
912 $d = Data::Dumper->new([$a,$b], [qw(a b)]);
913 $d->Seen({'*c' => $c}); # stash a ref without printing it
914 $d->Indent(3);
915 print $d->Dump;
916 $d->Reset->Purity(0); # empty the seen cache
917 print join "----\n", $d->Dump;
918
919
920 ########
921 # persistence
922 ########
923
924 package Foo;
925 sub new { bless { state => 'awake' }, shift }
926 sub Freeze {
927 my $s = shift;
928 print STDERR "preparing to sleep\n";
929 $s->{state} = 'asleep';
930 return bless $s, 'Foo::ZZZ';
931 }
932
933 package Foo::ZZZ;
934 sub Thaw {
935 my $s = shift;
936 print STDERR "waking up\n";
937 $s->{state} = 'awake';
938 return bless $s, 'Foo';
939 }
940
941 package Foo;
942 use Data::Dumper;
943 $a = Foo->new;
944 $b = Data::Dumper->new([$a], ['c']);
945 $b->Freezer('Freeze');
946 $b->Toaster('Thaw');
947 $c = $b->Dump;
948 print $c;
949 $d = eval $c;
950 print Data::Dumper->Dump([$d], ['d']);
951
952
953 ########
954 # symbol substitution (useful for recreating CODE refs)
955 ########
956
957 sub foo { print "foo speaking\n" }
958 *other = \&foo;
959 $bar = [ \&other ];
960 $d = Data::Dumper->new([\&other,$bar],['*other','bar']);
961 $d->Seen({ '*foo' => \&foo });
962 print $d->Dump;
963
964
965=head1 BUGS
966
967Due to limitations of Perl subroutine call semantics, you cannot pass an
968array or hash. Prepend it with a C<\> to pass its reference instead. This
969will be remedied in time, with the arrival of prototypes in later versions
970of Perl. For now, you need to use the extended usage form, and prepend the
971name with a C<*> to output it as a hash or array.
972
973C<Data::Dumper> cheats with CODE references. If a code reference is
974encountered in the structure being processed, an anonymous subroutine that
975contains the string '"DUMMY"' will be inserted in its place, and a warning
976will be printed if C<Purity> is set. You can C<eval> the result, but bear
977in mind that the anonymous sub that gets created is just a placeholder.
978Someday, perl will have a switch to cache-on-demand the string
979representation of a compiled piece of code, I hope. If you have prior
980knowledge of all the code refs that your data structures are likely
981to have, you can use the C<Seen> method to pre-seed the internal reference
982table and make the dumped output point to them, instead. See L<EXAMPLES>
983above.
984
985The C<Useqq> flag is not honored by C<Dumpxs()> (it always outputs
986strings in single quotes).
987
988SCALAR objects have the weirdest looking C<bless> workaround.
989
990
991=head1 AUTHOR
992
993Gurusamy Sarathy gsar@umich.edu
994
995Copyright (c) 1996-98 Gurusamy Sarathy. All rights reserved.
996This program is free software; you can redistribute it and/or
997modify it under the same terms as Perl itself.
998
999
1000=head1 VERSION
1001
7820172a 1002Version 2.10 (31 Oct 1998)
823edd99
GS
1003
1004=head1 SEE ALSO
1005
1006perl(1)
1007
1008=cut