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