Debian Codegraph @

upstream/debian-unstable/man3/Data::Dumper.3perl

raw
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)