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