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