Copyright (C) 2000-2012 |
Manpages Data::DumperSection: Perl Programmers Reference Guide (3perl)Updated: 2001-02-22 Index Return to Main Contents NAMEData::Dumper - stringified perl data structures, suitable for both printing and "eval"SYNOPSISuse Data::Dumper; # simple procedural interface print Dumper($foo, $bar); # extended usage with names print Data::Dumper->Dump([$foo, $bar], [qw(foo *ary)]); # configuration variables { local $Data::Dump::Purity = 1; eval Data::Dumper->Dump([$foo, $bar], [qw(foo *ary)]); } # OO usage $d = Data::Dumper->new([$foo, $bar], [qw(foo *ary)]); ... print $d->Dump; ... $d->Purity(1)->Terse(1)->Deepcopy(1); eval $d->Dump; DESCRIPTIONGiven 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. Handles self-referential structures correctly.The return value can be "eval"ed to get back an identical copy of the original reference structure. Any references that are the same as one of those passed in will be named $VARn (where n is a numeric suffix), and other duplicate references to substructures within $VARn will be appropriately labeled using arrow notation. You can specify names for individual values to be dumped if you use the "Dump()" method, or you can change the default $VAR prefix to something else. See $Data::Dumper::Varname and $Data::Dumper::Terse below. The default output of self-referential structures can be "eval"ed, but the nested references to $VARn will be undefined, since a recursive structure cannot be constructed using one Perl statement. You should set the "Purity" flag to 1 to get additional statements that will correctly fill in these references. In the extended usage form, the references to be dumped can be given user-specified names. If a name begins with a "*", the output will describe the dereferenced type of the supplied reference for hashes and arrays, and coderefs. Output of names will be avoided where possible if the "Terse" flag is set. In many cases, methods that are used to set the internal state of the object will return the object itself, so method calls can be conveniently chained together. Several styles of output are possible, all controlled by setting the "Indent" flag. See ``Configuration Variables or Methods'' below for details. Methods
Functions
Configuration Variables or MethodsSeveral configuration variables can be used to control the kind of output generated when using the procedural interface. These variables are usually "local"ized in a block so that other parts of the code are not affected by the change.These variables determine the default state of the object created by calling the "new" method, but cannot be used to alter the state of the object thereafter. The equivalent method names should be used instead to query or set the internal state of the object. The method forms return the object itself when called with arguments, so that they can be chained together nicely.
ExportsEXAMPLESRun these code snippets to get a quick feel for the behavior of this module. When you are through with these examples, you may want to add or change the various configuration variables described above, to see their behavior. (See the testsuite in the Data::Dumper distribution for more examples.)
use Data::Dumper; package Foo; sub new {bless {'a' => 1, 'b' => sub { return "foo" }}, $_[0]}; package Fuz; # a weird REF-REF-SCALAR object sub new {bless \($_ = \ 'fu\'z'), $_[0]}; package main; $foo = Foo->new; $fuz = Fuz->new; $boo = [ 1, [], "abcd", \*foo, {1 => 'a', 023 => 'b', 0x45 => 'c'}, \\"p\q\'r", $foo, $fuz]; ######## # simple usage ######## $bar = eval(Dumper($boo)); print($@) if $@; print Dumper($boo), Dumper($bar); # pretty print (no array indices) $Data::Dumper::Terse = 1; # don't output names where feasible $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); $Data::Dumper::Useqq = 1; # print strings in double quotes print Dumper($boo); ######## # recursive structures ######## @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 $Data::Dumper::Deepcopy = 1; # avoid cross-refs print Data::Dumper->Dump([$b, $a], [qw(*b a)]); $Data::Dumper::Purity = 0; # avoid cross-refs print Data::Dumper->Dump([$b, $a], [qw(*b a)]); ######## # deep structures ######## $a = "pearl"; $b = [ $a ]; $c = { 'b' => $b }; $d = [ $c ]; $e = { 'd' => $d }; $f = { 'e' => $e }; print Data::Dumper->Dump([$f], [qw(f)]); $Data::Dumper::Maxdepth = 3; # no deeper than 3 refs down print Data::Dumper->Dump([$f], [qw(f)]); ######## # object-oriented usage ######## $d = Data::Dumper->new([$a,$b], [qw(a b)]); $d->Seen({'*c' => $c}); # stash a ref without printing it $d->Indent(3); print $d->Dump; $d->Reset->Purity(0); # empty the seen cache print join "----\n", $d->Dump; ######## # persistence ######## package Foo; sub new { bless { state => 'awake' }, shift } sub Freeze { my $s = shift; print STDERR "preparing to sleep\n"; $s->{state} = 'asleep'; return bless $s, 'Foo::ZZZ'; } package Foo::ZZZ; sub Thaw { my $s = shift; print STDERR "waking up\n"; $s->{state} = 'awake'; return bless $s, 'Foo'; } package Foo; use Data::Dumper; $a = Foo->new; $b = Data::Dumper->new([$a], ['c']); $b->Freezer('Freeze'); $b->Toaster('Thaw'); $c = $b->Dump; print $c; $d = eval $c; print Data::Dumper->Dump([$d], ['d']); ######## # symbol substitution (useful for recreating CODE refs) ######## sub foo { print "foo speaking\n" } *other = \&foo; $bar = [ \&other ]; $d = Data::Dumper->new([\&other,$bar],['*other','bar']); $d->Seen({ '*foo' => \&foo }); print $d->Dump; BUGSDue to limitations of Perl subroutine call semantics, you cannot 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."Data::Dumper" cheats with CODE references. If a code reference is encountered in the structure being processed, an anonymous subroutine that contains the string '``DUMMY''' will be inserted in its place, and a warning will be printed if "Purity" is set. You can "eval" the result, but bear in mind that the anonymous sub that gets created is just a placeholder. Someday, perl will have a switch to cache-on-demand the string representation of a compiled piece of code, I hope. If you have prior knowledge of all the code refs that your data structures are likely to have, you can use the "Seen" method to pre-seed the internal reference table and make the dumped output point to them, instead. See EXAMPLES above. The "Useqq" flag makes Dump() run slower, since the XSUB implementation does not support it. SCALAR objects have the weirdest looking "bless" workaround. AUTHORGurusamy Sarathy gsar@activestate.comCopyright (c) 1996-98 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. VERSIONVersion 2.11 (unreleased)SEE ALSOperl(1)
Index
This document was created by man2html, using the manual pages. Time: 08:55:47 GMT, April 20, 2024 |