NAME
Dumper - stringified perl data structures, suitable for both printing and eval
SYNOPSIS
use Data::Dumper;
# simple usage
print Dumper($foo, $bar);
# extended usage with names
print Data::Dumper->Dump([$foo, $bar], [qw(foo *ary)]);
# OO usage
$d = Data::Dumper->new([$foo, $bar], [qw(foo *ary)]);
...
print $d->Dump;
...
$Data::Dump::Purity = 1;
eval $d->Dump;DESCRIPTION
Given a list of scalars or reference variables, writes out their contents in perl syntax. The references can also be objects. The contents of each variable is output in a single Perl statement.
The return value can be evaled to get back the original reference structure. Bear in mind that a reference so created will not preserve pointer equalities with the original reference.
Handles self-referential structures correctly. Any references that are the same as one of those passed in will be marked $VARn, and other duplicate references to substructures within $VARn will be appropriately labeled using arrow notation.
The default output of self-referential structures can be evaled, but the nested references to $VARn will be undefined, since a recursive structure cannot be constructed using one Perl statement. You can set $Data::Dumper::Purity to 1 to get additional statements that will correctly fill in these references.
In the extended usage form, the supplied references can be given user-specified names. If a supplied name begins with a *, the output will describe the dereferenced type of the supplied reference for hashes and arrays.
Several styles of output are possible. Style 0 gives the output without any newlines or indentation. Style 1 outputs a compact form with newlines but no fancy indentation (each level in the structure is simply indented by a fixed amount of whitespace). Style 2 (the default) outputs a very readable form which takes into account the length of hash keys (so the hash values line up). Style 3 is like style 2, but also annotates the elements of arrays with their index (but the comment is on its own line, so array output consumes twice the number of lines).
Exports
Dumper
Configuration
The module variable $Data::Dumper::Indent controls the style of indentation. It can be set to 0, 1, 2 or 3. 2 is the default.
The module variable $Data::Dumper::Purity controls the degree to which the output can be evaled to recreate the supplied reference structures. Setting it to 1 will output additional perl statements that will correctly recreate nested references. The default is 0.
The module variable $Data::Dumper::Pad specifies the string that will be prefixed to every line of the output. Empty string by default.
The module variable $Data::Dumper::Varname controls the prefix to use for tagging variable names in the output. The default is "VAR".
EXAMPLE
use Data::Dumper;
package Foo;
sub new {bless {'a' => 1, 'b' => sub { return "foo" }}, $_[0]};
package Fuz; # a wierd REF-REF-SCALAR object
sub new {bless \($_ = \'fuz'), $_[0]};
package main;
$foo = Foo->new;
$fuz = Fuz->new;
$boo = [ 1, [], "abcd", \*foo,
{1 => 'a', 023 => 'b', 0x45 => 'c'},
\\"pqr", $foo, $fuz];
$bar = eval(Dumper($boo));
print($@) if $@;
print Dumper($boo), Dumper($bar); # pretty print (no array indices)
$Data::Dumper::Indent = 0; # turn off all pretty print
print Dumper($boo), "\n";
$Data::Dumper::Indent = 1; # mild pretty print
print Dumper($boo);
$Data::Dumper::Indent = 3; # pretty print with array indices
print Dumper($boo);
# recursive structure
@c = ('c');
$c = \@c;
$b = {};
$a = [1, $b, $c];
$b->{a} = $a;
$b->{b} = $a->[1];
$b->{c} = $a->[2];
print Data::Dumper->Dump([$a,$b,$c], [qw(a b c)]);
$Data::Dumper::Purity = 1; # fill in the holes for eval
print Data::Dumper->Dump([$a, $b], [qw(*a b)]); # print as @a
print Data::Dumper->Dump([$b, $a], [qw(*b a)]); # print as %b
$d = Data::Dumper->new([$a,$b], [qw(a b)]);
$d->Seen({'*c' => $c}); # stash a ref without printing it
print $d->Dump;
$d->Reset; # empty the seen cache
print $d->Dump;BUGS
Due to limitations of Perl subroutine call semantics, you can't pass an array or hash. Prepend it with a \ to pass its reference instead. This will be remedied in time, with the arrival of prototypes in later versions of Perl. For now, you need to use the extended usage form, and prepend the name with a * to output it as a hash or array.
Dumper cheats with CODE references. If a code reference is encountered in the structure being processed, an anonymous subroutine returning the perl string-interpolated representation of the original CODE reference will be inserted in its place. You can eval the result, but bear in mind that the anonymous sub that gets created is a dummy placeholder. Someday, perl will have a switch to cache-on-demand the string representation of a compiled piece of code, I hope.
SCALAR objects have the wierdest looking bless workaround.
AUTHOR
Gurusamy Sarathy gsar@umich.edu
Copyright (c) 1995 Gurusamy Sarathy. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
VERSION
Version 1.21 20 Nov 1995
SEE ALSO
perl(1)