| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "Data::Dumper 3perl" |
| 58 |
.TH Data::Dumper 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
Data::Dumper \- stringified perl data structures, suitable for both printing and "eval" |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 1 |
| 68 |
\& use Data::Dumper; |
| 69 |
\& |
| 70 |
\& # simple procedural interface |
| 71 |
\& print Dumper($foo, $bar); |
| 72 |
\& |
| 73 |
\& # extended usage with names |
| 74 |
\& print Data::Dumper\->Dump([$foo, $bar], [qw(foo *ary)]); |
| 75 |
\& |
| 76 |
\& # configuration variables |
| 77 |
\& { |
| 78 |
\& local $Data::Dumper::Purity = 1; |
| 79 |
\& eval Data::Dumper\->Dump([$foo, $bar], [qw(foo *ary)]); |
| 80 |
\& } |
| 81 |
\& |
| 82 |
\& # OO usage |
| 83 |
\& my $d = Data::Dumper\->new([$foo, $bar], [qw(foo *ary)]); |
| 84 |
\& ... |
| 85 |
\& print $d\->Dump; |
| 86 |
\& ... |
| 87 |
\& $d\->Purity(1)\->Terse(1)\->Deepcopy(1); |
| 88 |
\& eval $d\->Dump; |
| 89 |
.Ve |
| 90 |
.SH DESCRIPTION |
| 91 |
.IX Header "DESCRIPTION" |
| 92 |
Given a list of scalars or reference variables, writes out their contents in |
| 93 |
perl syntax. The references can also be objects. The content of each |
| 94 |
variable is output in a single Perl statement. Handles self-referential |
| 95 |
structures correctly. |
| 96 |
.PP |
| 97 |
The return value can be \f(CW\*(C`eval\*(C'\fRed to get back an identical copy of the |
| 98 |
original reference structure. (Please do consider the security implications |
| 99 |
of eval'ing code from untrusted sources!) |
| 100 |
.PP |
| 101 |
Any references that are the same as one of those passed in will be named |
| 102 |
\&\f(CW$VAR\fR\fIn\fR (where \fIn\fR is a numeric suffix), and other duplicate references |
| 103 |
to substructures within \f(CW$VAR\fR\fIn\fR will be appropriately labeled using arrow |
| 104 |
notation. You can specify names for individual values to be dumped if you |
| 105 |
use the \f(CWDump()\fR method, or you can change the default \f(CW$VAR\fR prefix to |
| 106 |
something else. See \f(CW$Data::Dumper::Varname\fR and \f(CW$Data::Dumper::Terse\fR |
| 107 |
in "Configuration Variables or Methods" below. |
| 108 |
.PP |
| 109 |
The default output of self-referential structures can be \f(CW\*(C`eval\*(C'\fRed, but the |
| 110 |
nested references to \f(CW$VAR\fR\fIn\fR will be undefined, since a recursive |
| 111 |
structure cannot be constructed using one Perl statement. You should set the |
| 112 |
\&\f(CW\*(C`Purity\*(C'\fR flag to 1 to get additional statements that will correctly fill in |
| 113 |
these references. Moreover, if \f(CW\*(C`eval\*(C'\fRed when strictures are in effect, |
| 114 |
you need to ensure that any variables it accesses are previously declared. |
| 115 |
.PP |
| 116 |
In the extended usage form, the references to be dumped can be given |
| 117 |
user-specified names. If a name begins with a \f(CW\*(C`*\*(C'\fR, the output will |
| 118 |
describe the dereferenced type of the supplied reference for hashes and |
| 119 |
arrays, and coderefs. Output of names will be avoided where possible if |
| 120 |
the \f(CW\*(C`Terse\*(C'\fR flag is set. |
| 121 |
.PP |
| 122 |
In many cases, methods that are used to set the internal state of the |
| 123 |
object will return the object itself, so method calls can be conveniently |
| 124 |
chained together. |
| 125 |
.PP |
| 126 |
Several styles of output are possible, all controlled by setting |
| 127 |
the \f(CW\*(C`Indent\*(C'\fR flag. See "Configuration Variables or Methods" below |
| 128 |
for details. |
| 129 |
.SS Methods |
| 130 |
.IX Subsection "Methods" |
| 131 |
.IP "\fIPACKAGE\fR\->new(\fIARRAYREF [\fR, \fIARRAYREF]\fR)" 4 |
| 132 |
.IX Item "PACKAGE->new(ARRAYREF [, ARRAYREF])" |
| 133 |
Returns a newly created \f(CW\*(C`Data::Dumper\*(C'\fR object. The first argument is an |
| 134 |
anonymous array of values to be dumped. The optional second argument is an |
| 135 |
anonymous array of names for the values. The names need not have a leading |
| 136 |
\&\f(CW\*(C`$\*(C'\fR sign, and must be composed of alphanumeric characters. You can begin |
| 137 |
a name with a \f(CW\*(C`*\*(C'\fR to specify that the dereferenced type must be dumped |
| 138 |
instead of the reference itself, for ARRAY and HASH references. |
| 139 |
.Sp |
| 140 |
The prefix specified by \f(CW$Data::Dumper::Varname\fR will be used with a |
| 141 |
numeric suffix if the name for a value is undefined. |
| 142 |
.Sp |
| 143 |
Data::Dumper will catalog all references encountered while dumping the |
| 144 |
values. Cross-references (in the form of names of substructures in perl |
| 145 |
syntax) will be inserted at all possible points, preserving any structural |
| 146 |
interdependencies in the original set of values. Structure traversal is |
| 147 |
depth-first, and proceeds in order from the first supplied value to |
| 148 |
the last. |
| 149 |
.ie n .IP "\fR\fI$OBJ\fR\fI\fR\->Dump \fIor\fR \fIPACKAGE\fR\->Dump(\fIARRAYREF [\fR, \fIARRAYREF]\fR)" 4 |
| 150 |
.el .IP "\fR\f(CI$OBJ\fR\fI\fR\->Dump \fIor\fR \fIPACKAGE\fR\->Dump(\fIARRAYREF [\fR, \fIARRAYREF]\fR)" 4 |
| 151 |
.IX Item "$OBJ->Dump or PACKAGE->Dump(ARRAYREF [, ARRAYREF])" |
| 152 |
Returns the stringified form of the values stored in the object (preserving |
| 153 |
the order in which they were supplied to \f(CW\*(C`new\*(C'\fR), subject to the |
| 154 |
configuration options below. In a list context, it returns a list |
| 155 |
of strings corresponding to the supplied values. |
| 156 |
.Sp |
| 157 |
The second form, for convenience, simply calls the \f(CW\*(C`new\*(C'\fR method on its |
| 158 |
arguments before dumping the object immediately. |
| 159 |
.ie n .IP \fR\fI$OBJ\fR\fI\fR\->Seen(\fI[HASHREF]\fR) 4 |
| 160 |
.el .IP \fR\f(CI$OBJ\fR\fI\fR\->Seen(\fI[HASHREF]\fR) 4 |
| 161 |
.IX Item "$OBJ->Seen([HASHREF])" |
| 162 |
Queries or adds to the internal table of already encountered references. |
| 163 |
You must use \f(CW\*(C`Reset\*(C'\fR to explicitly clear the table if needed. Such |
| 164 |
references are not dumped; instead, their names are inserted wherever they |
| 165 |
are encountered subsequently. This is useful especially for properly |
| 166 |
dumping subroutine references. |
| 167 |
.Sp |
| 168 |
Expects an anonymous hash of name => value pairs. Same rules apply for names |
| 169 |
as in \f(CW\*(C`new\*(C'\fR. If no argument is supplied, will return the "seen" list of |
| 170 |
name => value pairs, in a list context. Otherwise, returns the object |
| 171 |
itself. |
| 172 |
.ie n .IP \fR\fI$OBJ\fR\fI\fR\->Values(\fI[ARRAYREF]\fR) 4 |
| 173 |
.el .IP \fR\f(CI$OBJ\fR\fI\fR\->Values(\fI[ARRAYREF]\fR) 4 |
| 174 |
.IX Item "$OBJ->Values([ARRAYREF])" |
| 175 |
Queries or replaces the internal array of values that will be dumped. When |
| 176 |
called without arguments, returns the values as a list. When called with a |
| 177 |
reference to an array of replacement values, returns the object itself. When |
| 178 |
called with any other type of argument, dies. |
| 179 |
.ie n .IP \fR\fI$OBJ\fR\fI\fR\->Names(\fI[ARRAYREF]\fR) 4 |
| 180 |
.el .IP \fR\f(CI$OBJ\fR\fI\fR\->Names(\fI[ARRAYREF]\fR) 4 |
| 181 |
.IX Item "$OBJ->Names([ARRAYREF])" |
| 182 |
Queries or replaces the internal array of user supplied names for the values |
| 183 |
that will be dumped. When called without arguments, returns the names. When |
| 184 |
called with an array of replacement names, returns the object itself. If the |
| 185 |
number of replacement names exceeds the number of values to be named, the |
| 186 |
excess names will not be used. If the number of replacement names falls short |
| 187 |
of the number of values to be named, the list of replacement names will be |
| 188 |
exhausted and remaining values will not be renamed. When |
| 189 |
called with any other type of argument, dies. |
| 190 |
.ie n .IP \fR\fI$OBJ\fR\fI\fR\->Reset 4 |
| 191 |
.el .IP \fR\f(CI$OBJ\fR\fI\fR\->Reset 4 |
| 192 |
.IX Item "$OBJ->Reset" |
| 193 |
Clears the internal table of "seen" references and returns the object |
| 194 |
itself. |
| 195 |
.SS Functions |
| 196 |
.IX Subsection "Functions" |
| 197 |
.IP Dumper(\fILIST\fR) 4 |
| 198 |
.IX Item "Dumper(LIST)" |
| 199 |
Returns the stringified form of the values in the list, subject to the |
| 200 |
configuration options below. The values will be named \f(CW$VAR\fR\fIn\fR in the |
| 201 |
output, where \fIn\fR is a numeric suffix. Will return a list of strings |
| 202 |
in a list context. |
| 203 |
.SS "Configuration Variables or Methods" |
| 204 |
.IX Subsection "Configuration Variables or Methods" |
| 205 |
Several configuration variables can be used to control the kind of output |
| 206 |
generated when using the procedural interface. These variables are usually |
| 207 |
\&\f(CW\*(C`local\*(C'\fRized in a block so that other parts of the code are not affected by |
| 208 |
the change. |
| 209 |
.PP |
| 210 |
These variables determine the default state of the object created by calling |
| 211 |
the \f(CW\*(C`new\*(C'\fR method, but cannot be used to alter the state of the object |
| 212 |
thereafter. The equivalent method names should be used instead to query |
| 213 |
or set the internal state of the object. |
| 214 |
.PP |
| 215 |
The method forms return the object itself when called with arguments, |
| 216 |
so that they can be chained together nicely. |
| 217 |
.IP \(bu 4 |
| 218 |
\&\f(CW$Data::Dumper::Indent\fR \fIor\fR \fR\f(CI$OBJ\fR\fI\fR\->Indent(\fI[NEWVAL]\fR) |
| 219 |
.Sp |
| 220 |
Controls the style of indentation. It can be set to 0, 1, 2 or 3. Style 0 |
| 221 |
spews output without any newlines, indentation, or spaces between list items. |
| 222 |
It is the most compact format possible that can still be called valid perl. |
| 223 |
Style 1 outputs a readable form with newlines but no fancy indentation (each |
| 224 |
level in the structure is simply indented by a fixed amount of whitespace). |
| 225 |
Style 2 (the default) outputs a very readable form which lines up the hash |
| 226 |
keys. Style 3 is like style 2, but also annotates the elements of arrays with |
| 227 |
their index (but the comment is on its own line, so array output consumes |
| 228 |
twice the number of lines). Style 2 is the default. |
| 229 |
.IP \(bu 4 |
| 230 |
\&\f(CW$Data::Dumper::Trailingcomma\fR \fIor\fR \fR\f(CI$OBJ\fR\fI\fR\->Trailingcomma(\fI[NEWVAL]\fR) |
| 231 |
.Sp |
| 232 |
Controls whether a comma is added after the last element of an array or |
| 233 |
hash. Even when true, no comma is added between the last element of an array |
| 234 |
or hash and a closing bracket when they appear on the same line. The default |
| 235 |
is false. |
| 236 |
.IP \(bu 4 |
| 237 |
\&\f(CW$Data::Dumper::Purity\fR \fIor\fR \fR\f(CI$OBJ\fR\fI\fR\->Purity(\fI[NEWVAL]\fR) |
| 238 |
.Sp |
| 239 |
Controls the degree to which the output can be \f(CW\*(C`eval\*(C'\fRed to recreate the |
| 240 |
supplied reference structures. Setting it to 1 will output additional perl |
| 241 |
statements that will correctly recreate nested references. The default is |
| 242 |
0. |
| 243 |
.IP \(bu 4 |
| 244 |
\&\f(CW$Data::Dumper::Pad\fR \fIor\fR \fR\f(CI$OBJ\fR\fI\fR\->Pad(\fI[NEWVAL]\fR) |
| 245 |
.Sp |
| 246 |
Specifies the string that will be prefixed to every line of the output. |
| 247 |
Empty string by default. |
| 248 |
.IP \(bu 4 |
| 249 |
\&\f(CW$Data::Dumper::Varname\fR \fIor\fR \fR\f(CI$OBJ\fR\fI\fR\->Varname(\fI[NEWVAL]\fR) |
| 250 |
.Sp |
| 251 |
Contains the prefix to use for tagging variable names in the output. The |
| 252 |
default is "VAR". |
| 253 |
.IP \(bu 4 |
| 254 |
\&\f(CW$Data::Dumper::Useqq\fR \fIor\fR \fR\f(CI$OBJ\fR\fI\fR\->Useqq(\fI[NEWVAL]\fR) |
| 255 |
.Sp |
| 256 |
When set, enables the use of double quotes for representing string values. |
| 257 |
Whitespace other than space will be represented as \f(CW\*(C`[\en\et\er]\*(C'\fR, "unsafe" |
| 258 |
characters will be backslashed, and unprintable characters will be output as |
| 259 |
quoted octal integers. The default is 0. |
| 260 |
.IP \(bu 4 |
| 261 |
\&\f(CW$Data::Dumper::Terse\fR \fIor\fR \fR\f(CI$OBJ\fR\fI\fR\->Terse(\fI[NEWVAL]\fR) |
| 262 |
.Sp |
| 263 |
When set, Data::Dumper will emit single, non-self-referential values as |
| 264 |
atoms/terms rather than statements. This means that the \f(CW$VAR\fR\fIn\fR names |
| 265 |
will be avoided where possible, but be advised that such output may not |
| 266 |
always be parseable by \f(CW\*(C`eval\*(C'\fR. |
| 267 |
.IP \(bu 4 |
| 268 |
\&\f(CW$Data::Dumper::Freezer\fR \fIor\fR $\fIOBJ\fR\->Freezer(\fI[NEWVAL]\fR) |
| 269 |
.Sp |
| 270 |
Can be set to a method name, or to an empty string to disable the feature. |
| 271 |
Data::Dumper will invoke that method via the object before attempting to |
| 272 |
stringify it. This method can alter the contents of the object (if, for |
| 273 |
instance, it contains data allocated from C), and even rebless it in a |
| 274 |
different package. The client is responsible for making sure the specified |
| 275 |
method can be called via the object, and that the object ends up containing |
| 276 |
only perl data types after the method has been called. Defaults to an empty |
| 277 |
string. |
| 278 |
.Sp |
| 279 |
If an object does not support the method specified (determined using |
| 280 |
\&\fBUNIVERSAL::can()\fR) then the call will be skipped. If the method dies a |
| 281 |
warning will be generated. |
| 282 |
.IP \(bu 4 |
| 283 |
\&\f(CW$Data::Dumper::Toaster\fR \fIor\fR $\fIOBJ\fR\->Toaster(\fI[NEWVAL]\fR) |
| 284 |
.Sp |
| 285 |
Can be set to a method name, or to an empty string to disable the feature. |
| 286 |
Data::Dumper will emit a method call for any objects that are to be dumped |
| 287 |
using the syntax \f(CW\*(C`bless(DATA, CLASS)\->METHOD()\*(C'\fR. Note that this means that |
| 288 |
the method specified will have to perform any modifications required on the |
| 289 |
object (like creating new state within it, and/or reblessing it in a |
| 290 |
different package) and then return it. The client is responsible for making |
| 291 |
sure the method can be called via the object, and that it returns a valid |
| 292 |
object. Defaults to an empty string. |
| 293 |
.IP \(bu 4 |
| 294 |
\&\f(CW$Data::Dumper::Deepcopy\fR \fIor\fR $\fIOBJ\fR\->Deepcopy(\fI[NEWVAL]\fR) |
| 295 |
.Sp |
| 296 |
Can be set to a boolean value to enable deep copies of structures. |
| 297 |
Cross-referencing will then only be done when absolutely essential |
| 298 |
(i.e., to break reference cycles). Default is 0. |
| 299 |
.IP \(bu 4 |
| 300 |
\&\f(CW$Data::Dumper::Quotekeys\fR \fIor\fR $\fIOBJ\fR\->Quotekeys(\fI[NEWVAL]\fR) |
| 301 |
.Sp |
| 302 |
Can be set to a boolean value to control whether hash keys are quoted. |
| 303 |
A defined false value will avoid quoting hash keys when it looks like a simple |
| 304 |
string. Default is 1, which will always enclose hash keys in quotes. |
| 305 |
.IP \(bu 4 |
| 306 |
\&\f(CW$Data::Dumper::Bless\fR \fIor\fR $\fIOBJ\fR\->Bless(\fI[NEWVAL]\fR) |
| 307 |
.Sp |
| 308 |
Can be set to a string that specifies an alternative to the \f(CW\*(C`bless\*(C'\fR |
| 309 |
builtin operator used to create objects. A function with the specified |
| 310 |
name should exist, and should accept the same arguments as the builtin. |
| 311 |
Default is \f(CW\*(C`bless\*(C'\fR. |
| 312 |
.IP \(bu 4 |
| 313 |
\&\f(CW$Data::Dumper::Pair\fR \fIor\fR $\fIOBJ\fR\->Pair(\fI[NEWVAL]\fR) |
| 314 |
.Sp |
| 315 |
Can be set to a string that specifies the separator between hash keys |
| 316 |
and values. To dump nested hash, array and scalar values to JavaScript, |
| 317 |
use: \f(CW\*(C`$Data::Dumper::Pair = \*(Aq : \*(Aq;\*(C'\fR. Implementing \f(CW\*(C`bless\*(C'\fR in JavaScript |
| 318 |
is left as an exercise for the reader. |
| 319 |
A function with the specified name exists, and accepts the same arguments |
| 320 |
as the builtin. |
| 321 |
.Sp |
| 322 |
Default is: \f(CW\*(C` => \*(C'\fR. |
| 323 |
.IP \(bu 4 |
| 324 |
\&\f(CW$Data::Dumper::Maxdepth\fR \fIor\fR $\fIOBJ\fR\->Maxdepth(\fI[NEWVAL]\fR) |
| 325 |
.Sp |
| 326 |
Can be set to a positive integer that specifies the depth beyond which |
| 327 |
we don't venture into a structure. Has no effect when |
| 328 |
\&\f(CW\*(C`Data::Dumper::Purity\*(C'\fR is set. (Useful in debugger when we often don't |
| 329 |
want to see more than enough). Default is 0, which means there is |
| 330 |
no maximum depth. |
| 331 |
.IP \(bu 4 |
| 332 |
\&\f(CW$Data::Dumper::Maxrecurse\fR \fIor\fR $\fIOBJ\fR\->Maxrecurse(\fI[NEWVAL]\fR) |
| 333 |
.Sp |
| 334 |
Can be set to a positive integer that specifies the depth beyond which |
| 335 |
recursion into a structure will throw an exception. This is intended |
| 336 |
as a security measure to prevent perl running out of stack space when |
| 337 |
dumping an excessively deep structure. Can be set to 0 to remove the |
| 338 |
limit. Default is 1000. |
| 339 |
.IP \(bu 4 |
| 340 |
\&\f(CW$Data::Dumper::Useperl\fR \fIor\fR $\fIOBJ\fR\->Useperl(\fI[NEWVAL]\fR) |
| 341 |
.Sp |
| 342 |
Can be set to a boolean value which controls whether the pure Perl |
| 343 |
implementation of \f(CW\*(C`Data::Dumper\*(C'\fR is used. The \f(CW\*(C`Data::Dumper\*(C'\fR module is |
| 344 |
a dual implementation, with almost all functionality written in both |
| 345 |
pure Perl and also in XS ('C'). Since the XS version is much faster, it |
| 346 |
will always be used if possible. This option lets you override the |
| 347 |
default behavior, usually for testing purposes only. Default is 0, which |
| 348 |
means the XS implementation will be used if possible. |
| 349 |
.IP \(bu 4 |
| 350 |
\&\f(CW$Data::Dumper::Sortkeys\fR \fIor\fR $\fIOBJ\fR\->Sortkeys(\fI[NEWVAL]\fR) |
| 351 |
.Sp |
| 352 |
Can be set to a boolean value to control whether hash keys are dumped in |
| 353 |
sorted order. A true value will cause the keys of all hashes to be |
| 354 |
dumped in Perl's default sort order. Can also be set to a subroutine |
| 355 |
reference which will be called for each hash that is dumped. In this |
| 356 |
case \f(CW\*(C`Data::Dumper\*(C'\fR will call the subroutine once for each hash, |
| 357 |
passing it the reference of the hash. The purpose of the subroutine is |
| 358 |
to return a reference to an array of the keys that will be dumped, in |
| 359 |
the order that they should be dumped. Using this feature, you can |
| 360 |
control both the order of the keys, and which keys are actually used. In |
| 361 |
other words, this subroutine acts as a filter by which you can exclude |
| 362 |
certain keys from being dumped. Default is 0, which means that hash keys |
| 363 |
are not sorted. |
| 364 |
.IP \(bu 4 |
| 365 |
\&\f(CW$Data::Dumper::Deparse\fR \fIor\fR $\fIOBJ\fR\->Deparse(\fI[NEWVAL]\fR) |
| 366 |
.Sp |
| 367 |
Can be set to a boolean value to control whether code references are |
| 368 |
turned into perl source code. If set to a true value, \f(CW\*(C`B::Deparse\*(C'\fR |
| 369 |
will be used to get the source of the code reference. In older versions, |
| 370 |
using this option imposed a significant performance penalty when dumping |
| 371 |
parts of a data structure other than code references, but that is no |
| 372 |
longer the case. |
| 373 |
.Sp |
| 374 |
Caution : use this option only if you know that your coderefs will be |
| 375 |
properly reconstructed by \f(CW\*(C`B::Deparse\*(C'\fR. |
| 376 |
.IP \(bu 4 |
| 377 |
\&\f(CW$Data::Dumper::Sparseseen\fR \fIor\fR $\fIOBJ\fR\->Sparseseen(\fI[NEWVAL]\fR) |
| 378 |
.Sp |
| 379 |
By default, Data::Dumper builds up the "seen" hash of scalars that |
| 380 |
it has encountered during serialization. This is very expensive. |
| 381 |
This seen hash is necessary to support and even just detect circular |
| 382 |
references. It is exposed to the user via the \f(CWSeen()\fR call both |
| 383 |
for writing and reading. |
| 384 |
.Sp |
| 385 |
If you, as a user, do not need explicit access to the "seen" hash, |
| 386 |
then you can set the \f(CW\*(C`Sparseseen\*(C'\fR option to allow Data::Dumper |
| 387 |
to eschew building the "seen" hash for scalars that are known not |
| 388 |
to possess more than one reference. This speeds up serialization |
| 389 |
considerably if you use the XS implementation. |
| 390 |
.Sp |
| 391 |
Note: If you turn on \f(CW\*(C`Sparseseen\*(C'\fR, then you must not rely on the |
| 392 |
content of the seen hash since its contents will be an |
| 393 |
implementation detail! |
| 394 |
.SS Exports |
| 395 |
.IX Subsection "Exports" |
| 396 |
.IP Dumper 4 |
| 397 |
.IX Item "Dumper" |
| 398 |
.SH EXAMPLES |
| 399 |
.IX Header "EXAMPLES" |
| 400 |
Run these code snippets to get a quick feel for the behavior of this |
| 401 |
module. When you are through with these examples, you may want to |
| 402 |
add or change the various configuration variables described above, |
| 403 |
to see their behavior. (See the testsuite in the Data::Dumper |
| 404 |
distribution for more examples.) |
| 405 |
.PP |
| 406 |
.Vb 1 |
| 407 |
\& use Data::Dumper; |
| 408 |
\& |
| 409 |
\& package Foo; |
| 410 |
\& sub new {bless {\*(Aqa\*(Aq => 1, \*(Aqb\*(Aq => sub { return "foo" }}, $_[0]}; |
| 411 |
\& |
| 412 |
\& package Fuz; # a weird REF\-REF\-SCALAR object |
| 413 |
\& sub new {bless \e($_ = \e \*(Aqfu\e\*(Aqz\*(Aq), $_[0]}; |
| 414 |
\& |
| 415 |
\& package main; |
| 416 |
\& $foo = Foo\->new; |
| 417 |
\& $fuz = Fuz\->new; |
| 418 |
\& $boo = [ 1, [], "abcd", \e*foo, |
| 419 |
\& {1 => \*(Aqa\*(Aq, 023 => \*(Aqb\*(Aq, 0x45 => \*(Aqc\*(Aq}, |
| 420 |
\& \e\e"p\eq\e\*(Aqr", $foo, $fuz]; |
| 421 |
\& |
| 422 |
\& ######## |
| 423 |
\& # simple usage |
| 424 |
\& ######## |
| 425 |
\& |
| 426 |
\& $bar = eval(Dumper($boo)); |
| 427 |
\& print($@) if $@; |
| 428 |
\& print Dumper($boo), Dumper($bar); # pretty print (no array indices) |
| 429 |
\& |
| 430 |
\& $Data::Dumper::Terse = 1; # don\*(Aqt output names where feasible |
| 431 |
\& $Data::Dumper::Indent = 0; # turn off all pretty print |
| 432 |
\& print Dumper($boo), "\en"; |
| 433 |
\& |
| 434 |
\& $Data::Dumper::Indent = 1; # mild pretty print |
| 435 |
\& print Dumper($boo); |
| 436 |
\& |
| 437 |
\& $Data::Dumper::Indent = 3; # pretty print with array indices |
| 438 |
\& print Dumper($boo); |
| 439 |
\& |
| 440 |
\& $Data::Dumper::Useqq = 1; # print strings in double quotes |
| 441 |
\& print Dumper($boo); |
| 442 |
\& |
| 443 |
\& $Data::Dumper::Pair = " : "; # specify hash key/value separator |
| 444 |
\& print Dumper($boo); |
| 445 |
\& |
| 446 |
\& |
| 447 |
\& ######## |
| 448 |
\& # recursive structures |
| 449 |
\& ######## |
| 450 |
\& |
| 451 |
\& @c = (\*(Aqc\*(Aq); |
| 452 |
\& $c = \e@c; |
| 453 |
\& $b = {}; |
| 454 |
\& $a = [1, $b, $c]; |
| 455 |
\& $b\->{a} = $a; |
| 456 |
\& $b\->{b} = $a\->[1]; |
| 457 |
\& $b\->{c} = $a\->[2]; |
| 458 |
\& print Data::Dumper\->Dump([$a,$b,$c], [qw(a b c)]); |
| 459 |
\& |
| 460 |
\& |
| 461 |
\& $Data::Dumper::Purity = 1; # fill in the holes for eval |
| 462 |
\& print Data::Dumper\->Dump([$a, $b], [qw(*a b)]); # print as @a |
| 463 |
\& print Data::Dumper\->Dump([$b, $a], [qw(*b a)]); # print as %b |
| 464 |
\& |
| 465 |
\& |
| 466 |
\& $Data::Dumper::Deepcopy = 1; # avoid cross\-refs |
| 467 |
\& print Data::Dumper\->Dump([$b, $a], [qw(*b a)]); |
| 468 |
\& |
| 469 |
\& |
| 470 |
\& $Data::Dumper::Purity = 0; # avoid cross\-refs |
| 471 |
\& print Data::Dumper\->Dump([$b, $a], [qw(*b a)]); |
| 472 |
\& |
| 473 |
\& ######## |
| 474 |
\& # deep structures |
| 475 |
\& ######## |
| 476 |
\& |
| 477 |
\& $a = "pearl"; |
| 478 |
\& $b = [ $a ]; |
| 479 |
\& $c = { \*(Aqb\*(Aq => $b }; |
| 480 |
\& $d = [ $c ]; |
| 481 |
\& $e = { \*(Aqd\*(Aq => $d }; |
| 482 |
\& $f = { \*(Aqe\*(Aq => $e }; |
| 483 |
\& print Data::Dumper\->Dump([$f], [qw(f)]); |
| 484 |
\& |
| 485 |
\& $Data::Dumper::Maxdepth = 3; # no deeper than 3 refs down |
| 486 |
\& print Data::Dumper\->Dump([$f], [qw(f)]); |
| 487 |
\& |
| 488 |
\& |
| 489 |
\& ######## |
| 490 |
\& # object\-oriented usage |
| 491 |
\& ######## |
| 492 |
\& |
| 493 |
\& $d = Data::Dumper\->new([$a,$b], [qw(a b)]); |
| 494 |
\& $d\->Seen({\*(Aq*c\*(Aq => $c}); # stash a ref without printing it |
| 495 |
\& $d\->Indent(3); |
| 496 |
\& print $d\->Dump; |
| 497 |
\& $d\->Reset\->Purity(0); # empty the seen cache |
| 498 |
\& print join "\-\-\-\-\en", $d\->Dump; |
| 499 |
\& |
| 500 |
\& |
| 501 |
\& ######## |
| 502 |
\& # persistence |
| 503 |
\& ######## |
| 504 |
\& |
| 505 |
\& package Foo; |
| 506 |
\& sub new { bless { state => \*(Aqawake\*(Aq }, shift } |
| 507 |
\& sub Freeze { |
| 508 |
\& my $s = shift; |
| 509 |
\& print STDERR "preparing to sleep\en"; |
| 510 |
\& $s\->{state} = \*(Aqasleep\*(Aq; |
| 511 |
\& return bless $s, \*(AqFoo::ZZZ\*(Aq; |
| 512 |
\& } |
| 513 |
\& |
| 514 |
\& package Foo::ZZZ; |
| 515 |
\& sub Thaw { |
| 516 |
\& my $s = shift; |
| 517 |
\& print STDERR "waking up\en"; |
| 518 |
\& $s\->{state} = \*(Aqawake\*(Aq; |
| 519 |
\& return bless $s, \*(AqFoo\*(Aq; |
| 520 |
\& } |
| 521 |
\& |
| 522 |
\& package main; |
| 523 |
\& use Data::Dumper; |
| 524 |
\& $a = Foo\->new; |
| 525 |
\& $b = Data::Dumper\->new([$a], [\*(Aqc\*(Aq]); |
| 526 |
\& $b\->Freezer(\*(AqFreeze\*(Aq); |
| 527 |
\& $b\->Toaster(\*(AqThaw\*(Aq); |
| 528 |
\& $c = $b\->Dump; |
| 529 |
\& print $c; |
| 530 |
\& $d = eval $c; |
| 531 |
\& print Data::Dumper\->Dump([$d], [\*(Aqd\*(Aq]); |
| 532 |
\& |
| 533 |
\& |
| 534 |
\& ######## |
| 535 |
\& # symbol substitution (useful for recreating CODE refs) |
| 536 |
\& ######## |
| 537 |
\& |
| 538 |
\& sub foo { print "foo speaking\en" } |
| 539 |
\& *other = \e&foo; |
| 540 |
\& $bar = [ \e&other ]; |
| 541 |
\& $d = Data::Dumper\->new([\e&other,$bar],[\*(Aq*other\*(Aq,\*(Aqbar\*(Aq]); |
| 542 |
\& $d\->Seen({ \*(Aq*foo\*(Aq => \e&foo }); |
| 543 |
\& print $d\->Dump; |
| 544 |
\& |
| 545 |
\& |
| 546 |
\& ######## |
| 547 |
\& # sorting and filtering hash keys |
| 548 |
\& ######## |
| 549 |
\& |
| 550 |
\& $Data::Dumper::Sortkeys = \e&my_filter; |
| 551 |
\& my $foo = { map { (ord, "$_$_$_") } \*(AqI\*(Aq..\*(AqQ\*(Aq }; |
| 552 |
\& my $bar = { %$foo }; |
| 553 |
\& my $baz = { reverse %$foo }; |
| 554 |
\& print Dumper [ $foo, $bar, $baz ]; |
| 555 |
\& |
| 556 |
\& sub my_filter { |
| 557 |
\& my ($hash) = @_; |
| 558 |
\& # return an array ref containing the hash keys to dump |
| 559 |
\& # in the order that you want them to be dumped |
| 560 |
\& return [ |
| 561 |
\& # Sort the keys of %$foo in reverse numeric order |
| 562 |
\& $hash eq $foo ? (sort {$b <=> $a} keys %$hash) : |
| 563 |
\& # Only dump the odd number keys of %$bar |
| 564 |
\& $hash eq $bar ? (grep {$_ % 2} keys %$hash) : |
| 565 |
\& # Sort keys in default order for all other hashes |
| 566 |
\& (sort keys %$hash) |
| 567 |
\& ]; |
| 568 |
\& } |
| 569 |
.Ve |
| 570 |
.SH BUGS |
| 571 |
.IX Header "BUGS" |
| 572 |
Due to limitations of Perl subroutine call semantics, you cannot pass an |
| 573 |
array or hash. Prepend it with a \f(CW\*(C`\e\*(C'\fR to pass its reference instead. This |
| 574 |
will be remedied in time, now that Perl has subroutine prototypes. |
| 575 |
For now, you need to use the extended usage form, and prepend the |
| 576 |
name with a \f(CW\*(C`*\*(C'\fR to output it as a hash or array. |
| 577 |
.PP |
| 578 |
\&\f(CW\*(C`Data::Dumper\*(C'\fR cheats with CODE references. If a code reference is |
| 579 |
encountered in the structure being processed (and if you haven't set |
| 580 |
the \f(CW\*(C`Deparse\*(C'\fR flag), an anonymous subroutine that |
| 581 |
contains the string '"DUMMY"' will be inserted in its place, and a warning |
| 582 |
will be printed if \f(CW\*(C`Purity\*(C'\fR is set. You can \f(CW\*(C`eval\*(C'\fR the result, but bear |
| 583 |
in mind that the anonymous sub that gets created is just a placeholder. |
| 584 |
Even using the \f(CW\*(C`Deparse\*(C'\fR flag will in some cases produce results that |
| 585 |
behave differently after being passed to \f(CW\*(C`eval\*(C'\fR; see the documentation |
| 586 |
for B::Deparse. |
| 587 |
.PP |
| 588 |
SCALAR objects have the weirdest looking \f(CW\*(C`bless\*(C'\fR workaround. |
| 589 |
.SS NOTE |
| 590 |
.IX Subsection "NOTE" |
| 591 |
Different runs of Perl will have different |
| 592 |
ordering of hash keys. The change was done for greater security, |
| 593 |
see "Algorithmic Complexity Attacks" in perlsec. This means that |
| 594 |
different runs of Perl will have different Data::Dumper outputs if |
| 595 |
the data contains hashes. If you need to have identical Data::Dumper |
| 596 |
outputs from different runs of Perl, use the environment variable |
| 597 |
PERL_HASH_SEED, see "PERL_HASH_SEED" in perlrun. Using this restores |
| 598 |
the old (platform-specific) ordering: an even prettier solution might |
| 599 |
be to use the \f(CW\*(C`Sortkeys\*(C'\fR filter of Data::Dumper. |
| 600 |
.SH AUTHOR |
| 601 |
.IX Header "AUTHOR" |
| 602 |
Gurusamy Sarathy [email protected] |
| 603 |
.PP |
| 604 |
Copyright (c) 1996\-2019 Gurusamy Sarathy. All rights reserved. |
| 605 |
This program is free software; you can redistribute it and/or |
| 606 |
modify it under the same terms as Perl itself. |
| 607 |
.SH VERSION |
| 608 |
.IX Header "VERSION" |
| 609 |
Version 2.189 |
| 610 |
.SH "SEE ALSO" |
| 611 |
.IX Header "SEE ALSO" |
| 612 |
\&\fBperl\fR\|(1) |