Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Data::Dumper.3pm

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