diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/Data::Dumper.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/Data::Dumper.3pm | 612 |
1 files changed, 612 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/Data::Dumper.3pm b/upstream/mageia-cauldron/man3pm/Data::Dumper.3pm new file mode 100644 index 00000000..ba3cceec --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/Data::Dumper.3pm @@ -0,0 +1,612 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "Data::Dumper 3pm" +.TH Data::Dumper 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +Data::Dumper \- stringified perl data structures, suitable for both printing and "eval" +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& use 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::Dumper::Purity = 1; +\& eval Data::Dumper\->Dump([$foo, $bar], [qw(foo *ary)]); +\& } +\& +\& # OO usage +\& my $d = Data::Dumper\->new([$foo, $bar], [qw(foo *ary)]); +\& ... +\& print $d\->Dump; +\& ... +\& $d\->Purity(1)\->Terse(1)\->Deepcopy(1); +\& eval $d\->Dump; +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Given a list of scalars or reference variables, writes out their contents in +perl syntax. The references can also be objects. The content of each +variable is output in a single Perl statement. Handles self-referential +structures correctly. +.PP +The return value can be \f(CW\*(C`eval\*(C'\fRed to get back an identical copy of the +original reference structure. (Please do consider the security implications +of eval'ing code from untrusted sources!) +.PP +Any references that are the same as one of those passed in will be named +\&\f(CW$VAR\fR\fIn\fR (where \fIn\fR is a numeric suffix), and other duplicate references +to substructures within \f(CW$VAR\fR\fIn\fR will be appropriately labeled using arrow +notation. You can specify names for individual values to be dumped if you +use the \f(CWDump()\fR method, or you can change the default \f(CW$VAR\fR prefix to +something else. See \f(CW$Data::Dumper::Varname\fR and \f(CW$Data::Dumper::Terse\fR +in "Configuration Variables or Methods" below. +.PP +The default output of self-referential structures can be \f(CW\*(C`eval\*(C'\fRed, but the +nested references to \f(CW$VAR\fR\fIn\fR will be undefined, since a recursive +structure cannot be constructed using one Perl statement. You should set the +\&\f(CW\*(C`Purity\*(C'\fR flag to 1 to get additional statements that will correctly fill in +these references. Moreover, if \f(CW\*(C`eval\*(C'\fRed when strictures are in effect, +you need to ensure that any variables it accesses are previously declared. +.PP +In the extended usage form, the references to be dumped can be given +user-specified names. If a name begins with a \f(CW\*(C`*\*(C'\fR, 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 \f(CW\*(C`Terse\*(C'\fR flag is set. +.PP +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. +.PP +Several styles of output are possible, all controlled by setting +the \f(CW\*(C`Indent\*(C'\fR flag. See "Configuration Variables or Methods" below +for details. +.SS Methods +.IX Subsection "Methods" +.IP "\fIPACKAGE\fR\->new(\fIARRAYREF [\fR, \fIARRAYREF]\fR)" 4 +.IX Item "PACKAGE->new(ARRAYREF [, ARRAYREF])" +Returns a newly created \f(CW\*(C`Data::Dumper\*(C'\fR object. The first argument is an +anonymous array of values to be dumped. The optional second argument is an +anonymous array of names for the values. The names need not have a leading +\&\f(CW\*(C`$\*(C'\fR sign, and must be comprised of alphanumeric characters. You can begin +a name with a \f(CW\*(C`*\*(C'\fR to specify that the dereferenced type must be dumped +instead of the reference itself, for ARRAY and HASH references. +.Sp +The prefix specified by \f(CW$Data::Dumper::Varname\fR will be used with a +numeric suffix if the name for a value is undefined. +.Sp +Data::Dumper will catalog all references encountered while dumping the +values. Cross-references (in the form of names of substructures in perl +syntax) will be inserted at all possible points, preserving any structural +interdependencies in the original set of values. Structure traversal is +depth-first, and proceeds in order from the first supplied value to +the last. +.ie n .IP "\fR\fI$OBJ\fR\fI\fR\->Dump \fIor\fR \fIPACKAGE\fR\->Dump(\fIARRAYREF [\fR, \fIARRAYREF]\fR)" 4 +.el .IP "\fR\f(CI$OBJ\fR\fI\fR\->Dump \fIor\fR \fIPACKAGE\fR\->Dump(\fIARRAYREF [\fR, \fIARRAYREF]\fR)" 4 +.IX Item "$OBJ->Dump or PACKAGE->Dump(ARRAYREF [, ARRAYREF])" +Returns the stringified form of the values stored in the object (preserving +the order in which they were supplied to \f(CW\*(C`new\*(C'\fR), subject to the +configuration options below. In a list context, it returns a list +of strings corresponding to the supplied values. +.Sp +The second form, for convenience, simply calls the \f(CW\*(C`new\*(C'\fR method on its +arguments before dumping the object immediately. +.ie n .IP \fR\fI$OBJ\fR\fI\fR\->Seen(\fI[HASHREF]\fR) 4 +.el .IP \fR\f(CI$OBJ\fR\fI\fR\->Seen(\fI[HASHREF]\fR) 4 +.IX Item "$OBJ->Seen([HASHREF])" +Queries or adds to the internal table of already encountered references. +You must use \f(CW\*(C`Reset\*(C'\fR to explicitly clear the table if needed. Such +references are not dumped; instead, their names are inserted wherever they +are encountered subsequently. This is useful especially for properly +dumping subroutine references. +.Sp +Expects an anonymous hash of name => value pairs. Same rules apply for names +as in \f(CW\*(C`new\*(C'\fR. If no argument is supplied, will return the "seen" list of +name => value pairs, in a list context. Otherwise, returns the object +itself. +.ie n .IP \fR\fI$OBJ\fR\fI\fR\->Values(\fI[ARRAYREF]\fR) 4 +.el .IP \fR\f(CI$OBJ\fR\fI\fR\->Values(\fI[ARRAYREF]\fR) 4 +.IX Item "$OBJ->Values([ARRAYREF])" +Queries or replaces the internal array of values that will be dumped. When +called without arguments, returns the values as a list. When called with a +reference to an array of replacement values, returns the object itself. When +called with any other type of argument, dies. +.ie n .IP \fR\fI$OBJ\fR\fI\fR\->Names(\fI[ARRAYREF]\fR) 4 +.el .IP \fR\f(CI$OBJ\fR\fI\fR\->Names(\fI[ARRAYREF]\fR) 4 +.IX Item "$OBJ->Names([ARRAYREF])" +Queries or replaces the internal array of user supplied names for the values +that will be dumped. When called without arguments, returns the names. When +called with an array of replacement names, returns the object itself. If the +number of replacement names exceeds the number of values to be named, the +excess names will not be used. If the number of replacement names falls short +of the number of values to be named, the list of replacement names will be +exhausted and remaining values will not be renamed. When +called with any other type of argument, dies. +.ie n .IP \fR\fI$OBJ\fR\fI\fR\->Reset 4 +.el .IP \fR\f(CI$OBJ\fR\fI\fR\->Reset 4 +.IX Item "$OBJ->Reset" +Clears the internal table of "seen" references and returns the object +itself. +.SS Functions +.IX Subsection "Functions" +.IP Dumper(\fILIST\fR) 4 +.IX Item "Dumper(LIST)" +Returns the stringified form of the values in the list, subject to the +configuration options below. The values will be named \f(CW$VAR\fR\fIn\fR in the +output, where \fIn\fR is a numeric suffix. Will return a list of strings +in a list context. +.SS "Configuration Variables or Methods" +.IX Subsection "Configuration Variables or Methods" +Several configuration variables can be used to control the kind of output +generated when using the procedural interface. These variables are usually +\&\f(CW\*(C`local\*(C'\fRized in a block so that other parts of the code are not affected by +the change. +.PP +These variables determine the default state of the object created by calling +the \f(CW\*(C`new\*(C'\fR 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. +.PP +The method forms return the object itself when called with arguments, +so that they can be chained together nicely. +.IP \(bu 4 +\&\f(CW$Data::Dumper::Indent\fR \fIor\fR \fR\f(CI$OBJ\fR\fI\fR\->Indent(\fI[NEWVAL]\fR) +.Sp +Controls the style of indentation. It can be set to 0, 1, 2 or 3. Style 0 +spews output without any newlines, indentation, or spaces between list items. +It is the most compact format possible that can still be called valid perl. +Style 1 outputs a readable 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 lines up the hash +keys. 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). Style 2 is the default. +.IP \(bu 4 +\&\f(CW$Data::Dumper::Trailingcomma\fR \fIor\fR \fR\f(CI$OBJ\fR\fI\fR\->Trailingcomma(\fI[NEWVAL]\fR) +.Sp +Controls whether a comma is added after the last element of an array or +hash. Even when true, no comma is added between the last element of an array +or hash and a closing bracket when they appear on the same line. The default +is false. +.IP \(bu 4 +\&\f(CW$Data::Dumper::Purity\fR \fIor\fR \fR\f(CI$OBJ\fR\fI\fR\->Purity(\fI[NEWVAL]\fR) +.Sp +Controls the degree to which the output can be \f(CW\*(C`eval\*(C'\fRed 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. +.IP \(bu 4 +\&\f(CW$Data::Dumper::Pad\fR \fIor\fR \fR\f(CI$OBJ\fR\fI\fR\->Pad(\fI[NEWVAL]\fR) +.Sp +Specifies the string that will be prefixed to every line of the output. +Empty string by default. +.IP \(bu 4 +\&\f(CW$Data::Dumper::Varname\fR \fIor\fR \fR\f(CI$OBJ\fR\fI\fR\->Varname(\fI[NEWVAL]\fR) +.Sp +Contains the prefix to use for tagging variable names in the output. The +default is "VAR". +.IP \(bu 4 +\&\f(CW$Data::Dumper::Useqq\fR \fIor\fR \fR\f(CI$OBJ\fR\fI\fR\->Useqq(\fI[NEWVAL]\fR) +.Sp +When set, enables the use of double quotes for representing string values. +Whitespace other than space will be represented as \f(CW\*(C`[\en\et\er]\*(C'\fR, "unsafe" +characters will be backslashed, and unprintable characters will be output as +quoted octal integers. The default is 0. +.IP \(bu 4 +\&\f(CW$Data::Dumper::Terse\fR \fIor\fR \fR\f(CI$OBJ\fR\fI\fR\->Terse(\fI[NEWVAL]\fR) +.Sp +When set, Data::Dumper will emit single, non-self-referential values as +atoms/terms rather than statements. This means that the \f(CW$VAR\fR\fIn\fR names +will be avoided where possible, but be advised that such output may not +always be parseable by \f(CW\*(C`eval\*(C'\fR. +.IP \(bu 4 +\&\f(CW$Data::Dumper::Freezer\fR \fIor\fR $\fIOBJ\fR\->Freezer(\fI[NEWVAL]\fR) +.Sp +Can be set to a method name, or to an empty string to disable the feature. +Data::Dumper will invoke that method via the object before attempting to +stringify it. This method can alter the contents of the object (if, for +instance, it contains data allocated from C), and even rebless it in a +different package. The client is responsible for making sure the specified +method can be called via the object, and that the object ends up containing +only perl data types after the method has been called. Defaults to an empty +string. +.Sp +If an object does not support the method specified (determined using +\&\fBUNIVERSAL::can()\fR) then the call will be skipped. If the method dies a +warning will be generated. +.IP \(bu 4 +\&\f(CW$Data::Dumper::Toaster\fR \fIor\fR $\fIOBJ\fR\->Toaster(\fI[NEWVAL]\fR) +.Sp +Can be set to a method name, or to an empty string to disable the feature. +Data::Dumper will emit a method call for any objects that are to be dumped +using the syntax \f(CW\*(C`bless(DATA, CLASS)\->METHOD()\*(C'\fR. Note that this means that +the method specified will have to perform any modifications required on the +object (like creating new state within it, and/or reblessing it in a +different package) and then return it. The client is responsible for making +sure the method can be called via the object, and that it returns a valid +object. Defaults to an empty string. +.IP \(bu 4 +\&\f(CW$Data::Dumper::Deepcopy\fR \fIor\fR $\fIOBJ\fR\->Deepcopy(\fI[NEWVAL]\fR) +.Sp +Can be set to a boolean value to enable deep copies of structures. +Cross-referencing will then only be done when absolutely essential +(i.e., to break reference cycles). Default is 0. +.IP \(bu 4 +\&\f(CW$Data::Dumper::Quotekeys\fR \fIor\fR $\fIOBJ\fR\->Quotekeys(\fI[NEWVAL]\fR) +.Sp +Can be set to a boolean value to control whether hash keys are quoted. +A defined false value will avoid quoting hash keys when it looks like a simple +string. Default is 1, which will always enclose hash keys in quotes. +.IP \(bu 4 +\&\f(CW$Data::Dumper::Bless\fR \fIor\fR $\fIOBJ\fR\->Bless(\fI[NEWVAL]\fR) +.Sp +Can be set to a string that specifies an alternative to the \f(CW\*(C`bless\*(C'\fR +builtin operator used to create objects. A function with the specified +name should exist, and should accept the same arguments as the builtin. +Default is \f(CW\*(C`bless\*(C'\fR. +.IP \(bu 4 +\&\f(CW$Data::Dumper::Pair\fR \fIor\fR $\fIOBJ\fR\->Pair(\fI[NEWVAL]\fR) +.Sp +Can be set to a string that specifies the separator between hash keys +and values. To dump nested hash, array and scalar values to JavaScript, +use: \f(CW\*(C`$Data::Dumper::Pair = \*(Aq : \*(Aq;\*(C'\fR. Implementing \f(CW\*(C`bless\*(C'\fR in JavaScript +is left as an exercise for the reader. +A function with the specified name exists, and accepts the same arguments +as the builtin. +.Sp +Default is: \f(CW\*(C` => \*(C'\fR. +.IP \(bu 4 +\&\f(CW$Data::Dumper::Maxdepth\fR \fIor\fR $\fIOBJ\fR\->Maxdepth(\fI[NEWVAL]\fR) +.Sp +Can be set to a positive integer that specifies the depth beyond which +we don't venture into a structure. Has no effect when +\&\f(CW\*(C`Data::Dumper::Purity\*(C'\fR is set. (Useful in debugger when we often don't +want to see more than enough). Default is 0, which means there is +no maximum depth. +.IP \(bu 4 +\&\f(CW$Data::Dumper::Maxrecurse\fR \fIor\fR $\fIOBJ\fR\->Maxrecurse(\fI[NEWVAL]\fR) +.Sp +Can be set to a positive integer that specifies the depth beyond which +recursion into a structure will throw an exception. This is intended +as a security measure to prevent perl running out of stack space when +dumping an excessively deep structure. Can be set to 0 to remove the +limit. Default is 1000. +.IP \(bu 4 +\&\f(CW$Data::Dumper::Useperl\fR \fIor\fR $\fIOBJ\fR\->Useperl(\fI[NEWVAL]\fR) +.Sp +Can be set to a boolean value which controls whether the pure Perl +implementation of \f(CW\*(C`Data::Dumper\*(C'\fR is used. The \f(CW\*(C`Data::Dumper\*(C'\fR module is +a dual implementation, with almost all functionality written in both +pure Perl and also in XS ('C'). Since the XS version is much faster, it +will always be used if possible. This option lets you override the +default behavior, usually for testing purposes only. Default is 0, which +means the XS implementation will be used if possible. +.IP \(bu 4 +\&\f(CW$Data::Dumper::Sortkeys\fR \fIor\fR $\fIOBJ\fR\->Sortkeys(\fI[NEWVAL]\fR) +.Sp +Can be set to a boolean value to control whether hash keys are dumped in +sorted order. A true value will cause the keys of all hashes to be +dumped in Perl's default sort order. Can also be set to a subroutine +reference which will be called for each hash that is dumped. In this +case \f(CW\*(C`Data::Dumper\*(C'\fR will call the subroutine once for each hash, +passing it the reference of the hash. The purpose of the subroutine is +to return a reference to an array of the keys that will be dumped, in +the order that they should be dumped. Using this feature, you can +control both the order of the keys, and which keys are actually used. In +other words, this subroutine acts as a filter by which you can exclude +certain keys from being dumped. Default is 0, which means that hash keys +are not sorted. +.IP \(bu 4 +\&\f(CW$Data::Dumper::Deparse\fR \fIor\fR $\fIOBJ\fR\->Deparse(\fI[NEWVAL]\fR) +.Sp +Can be set to a boolean value to control whether code references are +turned into perl source code. If set to a true value, \f(CW\*(C`B::Deparse\*(C'\fR +will be used to get the source of the code reference. In older versions, +using this option imposed a significant performance penalty when dumping +parts of a data structure other than code references, but that is no +longer the case. +.Sp +Caution : use this option only if you know that your coderefs will be +properly reconstructed by \f(CW\*(C`B::Deparse\*(C'\fR. +.IP \(bu 4 +\&\f(CW$Data::Dumper::Sparseseen\fR \fIor\fR $\fIOBJ\fR\->Sparseseen(\fI[NEWVAL]\fR) +.Sp +By default, Data::Dumper builds up the "seen" hash of scalars that +it has encountered during serialization. This is very expensive. +This seen hash is necessary to support and even just detect circular +references. It is exposed to the user via the \f(CWSeen()\fR call both +for writing and reading. +.Sp +If you, as a user, do not need explicit access to the "seen" hash, +then you can set the \f(CW\*(C`Sparseseen\*(C'\fR option to allow Data::Dumper +to eschew building the "seen" hash for scalars that are known not +to possess more than one reference. This speeds up serialization +considerably if you use the XS implementation. +.Sp +Note: If you turn on \f(CW\*(C`Sparseseen\*(C'\fR, then you must not rely on the +content of the seen hash since its contents will be an +implementation detail! +.SS Exports +.IX Subsection "Exports" +.IP Dumper 4 +.IX Item "Dumper" +.SH EXAMPLES +.IX Header "EXAMPLES" +Run 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.) +.PP +.Vb 1 +\& use Data::Dumper; +\& +\& package Foo; +\& sub new {bless {\*(Aqa\*(Aq => 1, \*(Aqb\*(Aq => sub { return "foo" }}, $_[0]}; +\& +\& package Fuz; # a weird REF\-REF\-SCALAR object +\& sub new {bless \e($_ = \e \*(Aqfu\e\*(Aqz\*(Aq), $_[0]}; +\& +\& package main; +\& $foo = Foo\->new; +\& $fuz = Fuz\->new; +\& $boo = [ 1, [], "abcd", \e*foo, +\& {1 => \*(Aqa\*(Aq, 023 => \*(Aqb\*(Aq, 0x45 => \*(Aqc\*(Aq}, +\& \e\e"p\eq\e\*(Aqr", $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\*(Aqt output names where feasible +\& $Data::Dumper::Indent = 0; # turn off all pretty print +\& print Dumper($boo), "\en"; +\& +\& $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); +\& +\& $Data::Dumper::Pair = " : "; # specify hash key/value separator +\& print Dumper($boo); +\& +\& +\& ######## +\& # recursive structures +\& ######## +\& +\& @c = (\*(Aqc\*(Aq); +\& $c = \e@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 = { \*(Aqb\*(Aq => $b }; +\& $d = [ $c ]; +\& $e = { \*(Aqd\*(Aq => $d }; +\& $f = { \*(Aqe\*(Aq => $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({\*(Aq*c\*(Aq => $c}); # stash a ref without printing it +\& $d\->Indent(3); +\& print $d\->Dump; +\& $d\->Reset\->Purity(0); # empty the seen cache +\& print join "\-\-\-\-\en", $d\->Dump; +\& +\& +\& ######## +\& # persistence +\& ######## +\& +\& package Foo; +\& sub new { bless { state => \*(Aqawake\*(Aq }, shift } +\& sub Freeze { +\& my $s = shift; +\& print STDERR "preparing to sleep\en"; +\& $s\->{state} = \*(Aqasleep\*(Aq; +\& return bless $s, \*(AqFoo::ZZZ\*(Aq; +\& } +\& +\& package Foo::ZZZ; +\& sub Thaw { +\& my $s = shift; +\& print STDERR "waking up\en"; +\& $s\->{state} = \*(Aqawake\*(Aq; +\& return bless $s, \*(AqFoo\*(Aq; +\& } +\& +\& package main; +\& use Data::Dumper; +\& $a = Foo\->new; +\& $b = Data::Dumper\->new([$a], [\*(Aqc\*(Aq]); +\& $b\->Freezer(\*(AqFreeze\*(Aq); +\& $b\->Toaster(\*(AqThaw\*(Aq); +\& $c = $b\->Dump; +\& print $c; +\& $d = eval $c; +\& print Data::Dumper\->Dump([$d], [\*(Aqd\*(Aq]); +\& +\& +\& ######## +\& # symbol substitution (useful for recreating CODE refs) +\& ######## +\& +\& sub foo { print "foo speaking\en" } +\& *other = \e&foo; +\& $bar = [ \e&other ]; +\& $d = Data::Dumper\->new([\e&other,$bar],[\*(Aq*other\*(Aq,\*(Aqbar\*(Aq]); +\& $d\->Seen({ \*(Aq*foo\*(Aq => \e&foo }); +\& print $d\->Dump; +\& +\& +\& ######## +\& # sorting and filtering hash keys +\& ######## +\& +\& $Data::Dumper::Sortkeys = \e&my_filter; +\& my $foo = { map { (ord, "$_$_$_") } \*(AqI\*(Aq..\*(AqQ\*(Aq }; +\& my $bar = { %$foo }; +\& my $baz = { reverse %$foo }; +\& print Dumper [ $foo, $bar, $baz ]; +\& +\& sub my_filter { +\& my ($hash) = @_; +\& # return an array ref containing the hash keys to dump +\& # in the order that you want them to be dumped +\& return [ +\& # Sort the keys of %$foo in reverse numeric order +\& $hash eq $foo ? (sort {$b <=> $a} keys %$hash) : +\& # Only dump the odd number keys of %$bar +\& $hash eq $bar ? (grep {$_ % 2} keys %$hash) : +\& # Sort keys in default order for all other hashes +\& (sort keys %$hash) +\& ]; +\& } +.Ve +.SH BUGS +.IX Header "BUGS" +Due to limitations of Perl subroutine call semantics, you cannot pass an +array or hash. Prepend it with a \f(CW\*(C`\e\*(C'\fR to pass its reference instead. This +will be remedied in time, now that Perl has subroutine prototypes. +For now, you need to use the extended usage form, and prepend the +name with a \f(CW\*(C`*\*(C'\fR to output it as a hash or array. +.PP +\&\f(CW\*(C`Data::Dumper\*(C'\fR cheats with CODE references. If a code reference is +encountered in the structure being processed (and if you haven't set +the \f(CW\*(C`Deparse\*(C'\fR flag), an anonymous subroutine that +contains the string '"DUMMY"' will be inserted in its place, and a warning +will be printed if \f(CW\*(C`Purity\*(C'\fR is set. You can \f(CW\*(C`eval\*(C'\fR the result, but bear +in mind that the anonymous sub that gets created is just a placeholder. +Even using the \f(CW\*(C`Deparse\*(C'\fR flag will in some cases produce results that +behave differently after being passed to \f(CW\*(C`eval\*(C'\fR; see the documentation +for B::Deparse. +.PP +SCALAR objects have the weirdest looking \f(CW\*(C`bless\*(C'\fR workaround. +.SS NOTE +.IX Subsection "NOTE" +Different runs of Perl will have different +ordering of hash keys. The change was done for greater security, +see "Algorithmic Complexity Attacks" in perlsec. This means that +different runs of Perl will have different Data::Dumper outputs if +the data contains hashes. If you need to have identical Data::Dumper +outputs from different runs of Perl, use the environment variable +PERL_HASH_SEED, see "PERL_HASH_SEED" in perlrun. Using this restores +the old (platform-specific) ordering: an even prettier solution might +be to use the \f(CW\*(C`Sortkeys\*(C'\fR filter of Data::Dumper. +.SH AUTHOR +.IX Header "AUTHOR" +Gurusamy Sarathy gsar@activestate.com +.PP +Copyright (c) 1996\-2019 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. +.SH VERSION +.IX Header "VERSION" +Version 2.188 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBperl\fR\|(1) |