1Data::Dump::Streamer(3pUms)er Contributed Perl DocumentatDiaotna::Dump::Streamer(3pm)
2
6 Data::Dump::Streamer - Accurately serialize a data structure as Perl
7 code.
8
10 use Data::Dump::Streamer;
11 use DDS; # optionally installed alias
12 Dump($x,$y); # Prints to STDOUT
14 Dump($x,$y)->Out(); # " "
15 my $o=Data::Dump::Streamer->new(); # Returns a new ...
17 my $o=Dump(); # ... uninitialized object.
18 my $o=Dump($x,$y); # Returns an initialized object
20 my $s=Dump($x,$y)->Out(); # " a string of the dumped obj
21 my @l=Dump($x,$y); # " a list of code fragments
22 my @l=Dump($x,$y)->Out(); # " a list of code fragments
23 Dump($x,$y)->To(\*STDERR)->Out(); # Prints to STDERR
25 Dump($x,$y)->Names('foo','bar') # Specify Names
27 ->Out();
28 Dump($x,$y)->Indent(0)->Out(); # No indent
30 Dump($x,$y)->To(\*STDERR) # Output to STDERR
32 ->Indent(0) # ... no indent
33 ->Names('foo','bar') # ... specify Names
34 ->Out(); # Print...
35 $o->Data($x,$y); # OO form of what Dump($x,$y) does.
37 $o->Names('Foo','Names'); # ...
38 $o->Out(); # ...
39
41 Given a list of scalars or reference variables, writes out their
42 contents in perl syntax. The references can also be objects. The
43 contents of each variable is output using the least number of Perl
44 statements as convenient, usually only one. Self-referential
45 structures, closures, and objects are output correctly.
46 The return value can be evaled to get back an identical copy of the
48 original reference structure. In some cases this may require the use of
49 utility subs that Data::Dump::Streamer will optionally export.
50 This module is very similar in concept to the core module Data::Dumper,
52 with the major differences being that this module is designed to output
53 to a stream instead of constructing its output in memory (trading speed
54 for memory), and that the traversal over the data structure is
55 effectively breadth first versus the depth first traversal done by the
56 others.
57 In fact the data structure is scanned twice, first in breadth first
59 mode to perform structural analysis, and then in depth first mode to
60 actually produce the output, but obeying the depth relationships of the
61 first pass.
62 Caveats Dumping Closures (CODE Refs)
64 As of version 1.11 DDS has had the ability to dump closures properly.
65 This means that the lexicals that are bound to the closure are dumped
66 along with the subroutine that uses them. This makes it much easier to
67 debug code that uses closures and to a certain extent provides a
68 persistency framework for closure based code. The way this works is
69 that DDS figures out what all the lexicals are that are bound to CODE
70 refs it is dumping and then pretends that it had originally been called
71 with all of them as its arguments, (along with the original arguments
72 as well of course.)
73 One consequence of the way the dumping process works is that all of the
75 recreated subroutines will be in the same scope. This of course can
76 lead to collisions as two subroutines can easily be bound to different
77 variables that have the same name.
78 The way that DDS resolves these collisions is that it renames one of
80 the variables with a special name so that presumably there are no
81 collisions. However this process is very simplistic with no checks to
82 prevent collisions with other lexicals or other globals that may be
83 used by other dumped code. In some situations it may be necessary to
84 change the default value of the rename template which may be done by
85 using the "EclipseName" method.
86 Similarly to the problem of colliding lexicals is the problem of
88 colliding lexicals and globals. DDS pays no attention to globals when
89 dumping closures which can potentially result in lexicals being
90 declared that will eclipse their global namesake. There is currently no
91 way around this other than to avoid accessing a global and a lexical
92 with the same name from the subs being dumped. An example is
93 my $a = sub { $a++ };
95 Dump( sub { $a->() } );
96 which will not be dumped correctly. Generally speaking this kind of
98 thing is bad practice anyway, so this should probably be viewed as a
99 "feature". :-)
100 Generally if the closures being dumped avoid accessing lexicals and
102 globals with the same name from out of scope and that all of the CODE
103 being dumped avoids vars with the "EclipseName" in their names the
104 dumps should be valid and should eval back into existence properly.
105 Note that the behaviour of dumping closures is subject to change in
107 future versions as its possible that I will put some additional effort
108 into more sophisticated ways of avoiding name collisions in the dump.
109
111 While Data::Dump::Streamer is at heart an object oriented module, it is
112 expected (based on experience with using Data::Dumper) that the common
113 case will not exploit these features. Nevertheless the method based
114 approach is convenient and accordingly a compromise hybrid approach has
115 been provided via the Dump() subroutine. Such as
116 Dump($foo);
118 $as_string= Dump($foo)->Out();
119 All attribute methods are designed to be chained together. This means
121 that when used as set attribute (called with arguments) they return the
122 object they were called against. When used as get attributes (called
123 without arguments) they return the value of the attribute.
124 From an OO point of view the key methods are the Data() and Out()
126 methods. These correspond to the breadth first and depth first
127 traversal, and need to be called in this order. Some attributes must be
128 set prior to the Data() phase and some need only be set before the
129 Out() phase.
130 Attributes once set last the lifetime of the object, unless explicitly
132 reset.
133 Controlling Object Representation
135 This module provides hooks to allow objects to override how they are
136 represented. The basic idea is that a subroutine (or method) is
137 provided which is responsible for the override. The return of the
138 method governs how the object will be represented when dumped, and how
139 it will be restored. The basic calling convention is
140 my ( $proxy, $thaw, $postop )= $callback->($obj);
142 #or = $obj->$method();
143 The Freezer() method controls what methods to use as a default method
145 and also allows per class overrides. When dumping an object of a given
146 class the first time it tries to execute the class specific handler if
147 it is specified, then the user specific generic handler if its been
148 specified and then "DDS_freeze". This means that class authors can
149 implement a DDS_freeze() method and their objects will automatically be
150 serialized as necessary. Note that if either the class specific or
151 generic handler is defined but false DDS_freeze() will not be used even
152 if it is present.
153 The interface of the Freezer() handler in detail is as follows:
155 $obj
157 The object being dumped.
158 $proxy
160 This is what will be dumped instead of $obj. It may be one of the
161 following values:
162 "undef" (first time only)
164 On the first time a serialization hook is called in a dump
165 it may return undef or the empty list to indicate that it
166 shouldn't be used again for this class during this pass.
167 Any other time undef is treated the same as false.
168 FALSE value
170 A false value for $proxy is taken to mean that it should be
171 ignored. Its like saying IgnoreClass(ref($obj)); Note that
172 undef has a special meaning when the callback is called the
173 first time.
174 A Reference
176 A reference that will be dumped instead of the object.
177 Perl Code
179 A string that is to be treated as code and inserted
180 directly into the dump stream as a proxy for the original.
181 Note that the code must be able to execute inline or in
182 other words must evaluate to a perl EXPR. Use "do{}" to
183 wrap multistatement code.
184 $thaw
186 This values is used to allow extra control over how the object will
187 be recreated when dumped. It is used for converting the $proxy
188 representation into the real thing. It is only relevant when $proxy
189 is a reference.
190 FALSE value
192 Indicates no thaw action is to be included for this object.
193 Sub or Method Name
195 A string matching "/^(->)?((?:\w*::)\w+)(\(\))?$/" in which
196 case it is taken as a sub name when the string ends in ()
197 and a method name when the string doesn't. If the "->" is
198 present then the sub or method is called inline. If it is
199 not then the sub or method is called after the main dump.
200 Perl Code
202 Any other string, in which case the result will be taken as
203 code which will be emitted after the main dump. It will be
204 wrapped in a for loop that aliases $_ to the variable in
205 question.
206 $postdump
208 This is the similar to $thaw but is called in process instead of
209 being emitted as part of the dump. Any return is ignored. It is
210 only relevant when $proxy is a reference.
211 FALSE value
213 No postdump action is to occur.
214 Code Reference
216 The code ref will be called after serialization is complete
217 with the object as the argument.
218 Method Name
220 The method will be called after serialization is complete
221 An example DDS_freeze method is one I had to put together for an object
223 which contained a key whose value was a ref to an array tied to the
224 value of another key. Dumping this got crazy, so I wanted to suppress
225 dumping the tied array. I did it this way:
226 sub DDS_freeze {
228 my $self=shift;
229 delete $self->{'tie'};
230 return ($self,'->fix_tie','fix_tie');
231 }
232 sub fix_tie {
234 my $self=shift;
235 if ( ! $self->{'tie'} ) {
236 $self->{str}="" unless defined $self->{str};
237 tie my @a, 'Tie::Array::PackedC', $self->{str};
238 $self->{'tie'} = \@a;
239 }
240 return $self;
241 }
242 The $postop means the object is relatively unaffected after the dump,
244 the $thaw says that we should also include the method inline as we
245 dump. An example dump of an object like this might be
246 $Foo1=bless({ str=>'' },'Foo')->fix_tie();
248 Wheras if we omit the "->" then we would get:
250 $Foo1=bless({ str=>'' },'Foo');
252 $Foo1->fix_tie();
253 In our example it wouldn't actually make a difference, but the former
255 style can be nicer to read if the object is embedded in another.
256 However the non arrow notation is slightly more dangerous, in that its
257 possible that the internals of the object will not be fully linked when
258 the method is evaluated. The second form guarantees that the object
259 will be fully linked when the method is evaluated.
260 See "Controlling Hash Traversal and Display Order" for a different way
262 to control the representation of hash based objects.
263 Controlling Hash Traversal and Display Order
265 When dumping a hash you may control the order the keys will be output
266 and which keys will be included. The basic idea is to specify a
267 subroutine which takes a hash as an argument and returns a reference to
268 an array containing the keys to be dumped.
269 You can use the KeyOrder() routine or the SortKeys() routine to specify
271 the sorter to be used.
272 The routine will be called in the following way:
274 ( $key_array, $thaw ) = $sorter->($hash,($pass=0),$addr,$class);
276 ( $key_array,) = $sorter->($hash,($pass=1),$addr,$class);
277 $hash is the hash to be dumped, $addr is the refaddr() of the $hash,
279 and $class will be set if the hash has been blessed.
280 When $pass is 0 the $thaw variable may be supplied as well as the
282 keyorder. If it is defined then it specifies what thaw action to
283 perform after dumping the hash. See $thaw in "Controlling Object
284 Representation" for details as to how it works. This allows an object
285 to define those keys needed to recreate itself properly, and a followup
286 hook to recreate the rest.
287 Note that if a Freezer() method is defined and returns a $thaw then the
289 $thaw returned by the sorter will override it.
290 Controlling Array Presentation and Run Length Encoding
292 By default Data::Dump::Streamer will "run length encode" array values.
293 This means that when an array value is simple (ie, its not referenced
294 and does contain a reference) and is repeated multiple times the output
295 will be single a list multiplier statement, and not each item output
296 separately. Thus: "Dump([0,0,0,0])" will be output something like
297 $ARRAY1 = [ (0) x 4 ];
299 This is particularly useful when dealing with large arrays that are
301 only partly filled, and when accidentally the array has been made very
302 large, such as with the improper use of pseudo-hash notation.
303 To disable this feature you may set the Rle() property to FALSE, by
305 default it is enabled and set to TRUE.
306 Installing DDS as a package alias
308 Its possible to have an alias to Data::Dump::Streamer created and
309 installed for easier usage in one liners and short scripts.
310 Data::Dump::Streamer is a bit long to type sometimes. However because
311 this technically means polluting the root level namespace, and having
312 it listed on CPAN, I have elected to have the installer not install it
313 by default. If you wish it to be installed you must explicitly state
314 so when Build.Pl is run:
315 perl Build.Pl DDS [Other Module::Build options]
317 Then a normal './Build test, ./Build install' invocation will install
319 DDS.
320 Using DDS is identical to Data::Dump::Streamer.
322 use-time package aliasing
324 You can also specify an alias at use-time, then use that alias in the
325 rest of your program, thus avoiding the permanent (but modest)
326 namespace pollution of the previous method.
327 use Data::Dumper::Streamer as => 'DDS';
329 # or if you prefer
331 use Data::Dumper::Streamer;
332 import Data::Dumper::Streamer as => 'DDS';
333 You can use any alias you like, but that doesn't mean you should..
335 Folks doing as => 'DBI' will be mercilessly ridiculed.
336 PadWalker support
338 If PadWalker 1.0 is installed you can use DumpLex() to try to
339 automatically determine the names of the vars being dumped. As long as
340 the vars being dumped have my or our declarations in scope the vars
341 will be correctly named. Padwalker will also be used instead of the B::
342 modules when dumping closures when it is available.
343
345 Data::Dumper Compatibility
346 For drop in compatibility with the Dumper() usage of Data::Dumper, you
347 may request that the Dumper() method is exported. It will not be
348 exported by default. In addition the standard Data::Dumper::Dumper()
349 may be exported on request as "DDumper". If you provide the tag
350 ":Dumper" then both will be exported.
351 Dumper
353 Dumper LIST
354 A synonym for scalar Dump(LIST)->Out for usage compatibility with
355 Data::Dumper
356 DDumper
358 DDumper LIST
359 A secondary export of the actual Data::Dumper::Dumper subroutine.
360 Constructors
362 new Creates a new Data::Dump::Streamer object. Currently takes no
363 arguments and simply returns the new object with a default style
364 configuration.
365 See Dump() for a better way to do things.
367 Dump
369 Dump VALUES
370 Smart non method based constructor.
371 This routine behaves very differently depending on the context it
373 is called in and whether arguments are provided.
374 If called with no arguments it is exactly equivalent to calling
376 Data::Dump::Streamer->new()
378 which means it returns an object reference.
380 If called with arguments and in scalar context it is equivalent to
382 calling
383 Data::Dump::Streamer->new()->Data(@vals)
385 except that the actual depth first traversal is delayed until Out()
387 is called. This means that options that must be provided before
388 the Data() phase can be provided after the call to Dump(). Again,
389 it returns a object reference.
390 If called with arguments and in void or list context it is
392 equivelent to calling
393 Data::Dump::Streamer->new()->Data(@vals)->Out()
395 The reason this is true in list context is to make "print
397 Dump(...),"\n";" do the right thing. And also that combined with
398 method chaining options can be added or removed as required quite
399 easily and naturally.
400 So to put it short:
402 my $obj=Dump($x,$y); # Returns an object
404 my $str=Dump($x,$y)->Out(); # Returns a string of the dump.
405 my @code=Dump($x,$y); # Returns a list of the dump.
406 Dump($x,$y); # prints the dump.
408 print Dump($x,$y); # prints the dump.
409 It should be noted that the setting of "$\" will affect the
411 behaviour of both of
412 Dump($x,$y);
414 print Dump($x,$y);
415 but it will not affect the behaviour of
417 print scalar Dump($x,$y);
419 Note As of 1.11 Dump also works as a method, with identical
421 properties as when called as a subroutine, with the exception that
422 when called with no arguments it is a synonym for Out(). Thus
423 $obj->Dump($foo)->Names('foo')->Out();
425 will work fine, as will the odd looking:
427 $obj->Dump($foo)->Names('foo')->Dump();
429 which are both the same as
431 $obj->Names('foo')->Data($foo)->Out();
433 Hopefully this should make method use more or less DWIM.
435 DumpLex VALUES
437 DumpLex is similar to Dump except it will try to automatically
438 determine the names to use for the variables being dumped by using
439 PadWalker to have a poke around the calling lexical scope to see
440 what is declared. If a name for a var can't be found then it will
441 be named according to the normal scheme. When PadWalker isn't
442 installed this is just a wrapper for Dump().
443 Thanks to Ovid for the idea of this. See Data::Dumper::Simple for a
445 similar wrapper around Data::Dumper.
446 DumpVars PAIRS
448 This is wrapper around Dump() which expect to receive a list of
449 name=>value pairs instead of a list of values. Otherwise behaves
450 like Dump(). Note that names starting with a '-' are treated the
451 same as those starting with '*' when passed to Names().
452 Methods
454 Data
455 Data LIST
456 Analyzes a list of variables in breadth first order.
457 If called with arguments then the internal object state is reset
459 before scanning the list of arguments provided.
460 If called with no arguments then whatever arguments were provided
462 to Dump() will be scanned.
463 Returns $self.
465 Out
467 Out VALUES
468 Prints out a set of values to the appropriate location. If provided
469 a list of values then the values are first scanned with Data() and
470 then printed, if called with no values then whatever was scanned
471 last with Data() or Dump() is printed.
472 If the To() attribute was provided then will dump to whatever
474 object was specified there (any object, including filehandles that
475 accept the print() method), and will always return $self.
476 If the To() attribute was not provided then will use an internal
478 printing object, returning either a list or scalar or printing to
479 STDOUT in void context.
480 This routine is virtually always called without arguments as the
482 last method in the method chain.
483 Dump->Arguments(1)->Out(@vars);
485 $obj->Data(@vars)->Out();
486 Dump(@vars)->Out;
487 Data::Dump::Streamer->Out(@vars);
488 All should DWIM.
490 Names
492 Names LIST
493 Names ARRAYREF
494 Takes a list of strings or a reference to an array of strings to
495 use for var names for the objects dumped. The names may be prefixed
496 by a * indicating the variable is to be dumped as its dereferenced
497 type if it is an array, hash or code ref. Otherwise the star is
498 ignored. Other sigils may be prefixed but they will be silently
499 converted to *'s.
500 If no names are provided then names are generated automatically
502 based on the type of object being dumped, with abbreviations
503 applied to compound class names.
504 If called with arguments then returns the object itself, otherwise
506 in list context returns the list of names in use, or in scalar
507 context a reference or undef. In void context with no arguments the
508 names are cleared.
509 NOTE: Must be called before Data() is called.
511 If you wish to have no names, use Terse.
513 Terse
515 Terse BOOL
516 When true, no variable names will be created. Data will be dumped
517 as anonymous references or values.
518 Dump([])->Out; # $ARRAY1 = []
520 Dump([])->Terse(1)->Out; # []
521 Purity
523 Purity BOOL
524 This option can be used to set the level of purity in the output.
525 It defaults to TRUE, which results in the module doing its best to
526 ensure that the resulting dump when eval()ed is precisely the same
527 as the input. However, at times such as debugging this can be
528 tedious, resulting in extremely long dumps with many "fix"
529 statements involved. By setting Purity to FALSE the resulting
530 output won't necessarily be legal Perl, but it will be more
531 legible. In this mode the output is broadly similar to that of the
532 default setting of Data::Dumper (Purity(0)). When set to TRUE the
533 behaviour is likewise similar to Data::Dumper in Purity(1) but more
534 accurate.
535 When Purity() is set to FALSE aliases will be output with a
537 function call wrapper of 'alias_to' whose argument will be the
538 value the item is an alias to. This wrapper does nothing, and is
539 only there as a visual cue. Likewise, 'make_ro' will be output
540 when the value was readonly, and again the effect is cosmetic only.
541 To
543 To STREAMER
544 Specifies the object to print to. Data::Dump::Streamer can stream
545 its output to any object supporting the print method. This is
546 primarily meant for streaming to a filehandle, however any object
547 that supports the method will do.
548 If a filehandle is specified then it is used until it is explicitly
550 changed, or the object is destroyed.
551 Declare
553 Declare BOOL
554 If Declare is True then each object is dumped with 'my'
555 declarations included, and all rules that follow are obeyed. (Ie,
556 not referencing an undeclared variable). If Declare is False then
557 all objects are expected to be previously defined and references to
558 top level objects can be made at any time.
559 Defaults to False.
561 Indent
563 Indent INT
564 If Indent is True then data is output in an indented and fairly
565 neat fashion. If the value is 2 then hash key/value pairs and array
566 values each on their own line. If the value is 1 then a "smart"
567 indenting mode is activated where multiple key/value or values may
568 be printed to the same line. The heuristics for this mode are still
569 experimental so it may occasional not indent very nicely.
570 Default is Indent(2)
572 If indent is False then no indentation is done, and all optional
574 whitespace. is omitted. See <OptSpace()|/OptSpace> for more
575 details.
576 Defaults to True.
578 Newlines are appended to each statement regardless of this value.
580 Indentkeys
582 Indentkeys BOOL
583 If Indent() and Indentkeys are True then hashes with more than one
584 key value pair are dumped such that the keys and values line up.
585 Note however this means each key has to be quoted twice. Not
586 advised for very large data structures. Additional logic may
587 enhance this feature soon.
588 Defaults to True.
590 NOTE: Must be set before Data() is called.
592 OptSpace
594 OptSpace STR
595 Normally DDS emits a lot of whitespace in between tokens that it
596 emits. Using this method you can control how much whitespace it
597 will emit, or even if some other string should be used.
598 If Indent is set to 0 then this value is automatically set to the
600 empty string. When Indent is set back to a non zero value the old
601 value will be restored if it has not been changed from the empty
602 string in the intervening time.
603 KeyOrder TYPE_OR_OBJ
605 KeyOrder TYPE_OR_OBJ, VALUE
606 Sets or returns the key order to for use for a given type or
607 object.
608 TYPE_OR_OBJ may be a string representing a class, or "" for
610 representing unblessed objects, or it maybe a reference to a hash.
611 VALUE may be a string representing one of built in sort mechanisms,
613 or it may be a reference to a subroutine, or a method name if
614 TYPE_OR_OBJ is not an object.
615 The built in sort mechanisms are 'aphabetical'/'lexical',
617 'numeric', 'smart'/'intelligent' and 'each'.
618 If VALUE is omitted returns the current value for the given type.
620 If TYPE_OR_OBJ is omitted or FALSE it defaults to "" which
622 represents unblessed hashes.
623 See "Controlling Hash Traversal and Display Order" for more
625 details.
626 SortKeys
628 SortKeys VALUE
629 This is a wrapper for KeyOrder. It allows only the generic hash
630 sort order to be specified a little more elegantly than via
631 KeyOrder(). It is syntactically equivalent to
632 $self->KeyOrder( "", @_ );
634 Verbose
636 Verbose BOOL
637 If Verbose is True then when references that cannot be resolved in
638 a single statement are encountered the reference is substituted for
639 a descriptive tag saying what type of forward reference it is, and
640 to what is being referenced. The type is provided through a prefix,
641 "R:" for reference, and "A:" for alias, "V:" for a value and then
642 the name of the var in a string. Automatically generated var names
643 are also reduced to the shortest possible unique abbreviation, with
644 some tricks thrown in for Long::Class::Names::Like::This (which
645 would abbreviate most likely to LCNLT1)
646 If Verbose if False then a simple placeholder saying 'A' or 'R' is
648 provided. (In most situations perl requires a placeholder, and as
649 such one is always provided, even if technically it could be
650 omitted.)
651 This setting does not change the followup statements that fix up
653 the structure, and does not result in a loss of accuracy, it just
654 makes it a little harder to read. OTOH, it means dumps can be quite
655 a bit smaller and less noisy.
656 Defaults to True.
658 NOTE: Must be set before Data() is called.
660 DumpGlob
662 DumpGlob BOOL
663 If True then globs will be followed and fully defined, otherwise
664 the globs will still be referenced but their current value will not
665 be set.
666 Defaults to True
668 NOTE: Must be set before Data() is called.
670 Deparse
672 Deparse BOOL
673 If True then CODE refs will be deparsed use B::Deparse and included
674 in the dump. If it is False the a stub subroutine reference will be
675 output as per the setting of CodeStub().
676 Caveat Emptor, dumping subroutine references is hardly a secure
678 act, and it is provided here only for convenience.
679 Note using this routine is at your own risk as of DDS 1.11, how it
681 interacts with the newer advanced closure dumping process is
682 undefined.
683 EclipseName
685 EclipseName SPRINTF_FORMAT
686 When necessary DDS will rename vars output during deparsing with
687 this value. It is a sprintf format string that should contain only
688 and both of the "%s" and a "%d" formats in any order along with
689 whatever other literal text you want in the name. No checks are
690 performed on the validity of this value so be careful. It defaults
691 to
692 "%s_eclipse_%d"
694 where the "%s" represents the name of the var being eclipsed, and
696 the "%d" a counter to ensure all such mappings are unique.
697 DeparseOpts
699 DeparseOpts LIST
700 DeparseOpts ARRAY
701 If Deparse is True then these options will be passed to
702 B::Deparse->new() when dumping a CODE ref. If passed a list of
703 scalars the list is used as the arguments. If passed an array
704 reference then this array is assumed to contain a list of
705 arguments. If no arguments are provided returns a an array ref of
706 arguments in scalar context, and a list of arguments in list
707 context.
708 Note using this routine is at your own risk as of DDS 1.11, how it
710 interacts with the newer advanced closure dumping process is
711 undefined.
712 CodeStub
714 CodeStub STRING
715 If Deparse is False then this string will be used in place of CODE
716 references. Its the users responsibility to make sure its
717 compilable and blessable.
718 Defaults to 'sub { Carp::confess "Dumped code stub!" }'
720 FormatStub
722 FormatStub STRING
723 If Deparse is False then this string will be used in place of
724 FORMAT references. Its the users responsibility to make sure its
725 compilable and blessable.
726 Defaults to 'do{ local *F; eval "format F =\nFormat Stub\n.\n";
728 *F{FORMAT} }'
729 DeparseGlob
731 DeparseGlob BOOL
732 If Deparse is TRUE then this style attribute will determine if
733 subroutines and FORMAT's contained in globs that are dumped will be
734 deparsed or not.
735 Defaults to True.
737 Dualvars
739 Dualvars BOOL
740 Dualvars
741 Dualvars BOOL
742 If TRUE then dualvar checking will occur and the required
743 statements emitted to recreate dualvars when they are encountered,
744 otherwise items will be dumped in their stringified form always. It
745 defaults to TRUE.
746 Rle
748 Rle BOOL
749 RLE
750 RLE BOOL
751 If True then arrays will be run length encoded using the "x"
752 operator. What this means is that if an array contains repeated
753 elements then instead of outputting each and every one a list
754 multiplier will be output. This means that considerably less space
755 is taken to dump redundant data.
756 Freezer
758 Freezer ACTION
759 Freezer CLASS, ACTION
760 This method can be used to override the DDS_freeze hook for a
761 specific class. If CLASS is omitted then the ACTION applies to all
762 blessed object.
763 If ACTION is false it indicates that the given CLASS should not
765 have any serilization hooks called.
766 If ACTION is a string then it is taken to be the method name that
768 will be executed to freeze the object. CLASS->can(METHOD) must
769 return true or the setting will be ignored.
770 If ACTION is a code ref it is executed with the object as the
772 argument.
773 When called with no arguments returns in scalar context the generic
775 serialization method (defaults to 'DDS_freeze'), in list context
776 returns the generic serialization method followed by a list of
777 pairs of Classname=>ACTION.
778 If the action executes a sub or method it is expected to return a
780 list of three values:
781 ( $proxy, $thaw, $postdump )=$obj->DDS_Freeze();
783 See "Controlling Object Representation" for more details.
785 NOTE: Must be set before Data() is called.
787 Ignore
789 Ignore OBJ_OR_CLASS
790 Ignore OBJ_OR_CLASS, BOOL
791 Allows a given object or class to be ignored, and replaced with a
792 string containing the name of the item ignored.
793 If called with no args returns a list of items ignored (using the
795 refaddr to represent objects). If called with a single argument
796 returns whether that argument is ignored. If called with more than
797 one arguments then expects a list of pairs of object => is_ignored.
798 Returns $self when setting.
800 NOTE: Must be set before Data() is called.
802 Compress
804 Compress SIZE
805 Controls compression of string values (not keys). If this value is
806 nonzero and a string to be dumped is longer than its value then the
807 Compressor() if defined is used to compress the string. Setting
808 size to -1 will cause all strings to be processed, setting size to
809 0 will cause no strings to be processed.
810 Compressor
812 Compressor CODE
813 This attribute is used to control the compression of strings. It
814 is expected to be a reference to a subroutine with the following
815 interface:
816 my $prelude_code=$compressor->(); # no arguments.
818 my $code=$compressor->('string'); # string argument
819 The sub will be called with no arguments at the beginning of the
821 dump to allow any require statements or similar to be added. During
822 the dump the sub will be called with a single argument when
823 compression is required. The code returned in this case is expected
824 to be an EXPR that will evaluate back to the original string.
825 By default DDS will use Compress::Zlib in conjunction with
827 MIME::Base64 to do compression and encoding, and exposes the 'usqz'
828 subroutine for handling the decoding and decompression.
829 The abbreviated name was chosen as when using the default
831 compressor every string will be represented by a string like
832 usqz('....')
834 Meaning that eight characters are required without considering the
836 data itself. Likewise Base64 was chosen because it is a
837 representation that is high-bit safe, compact and easy to quote.
838 Escaped strings are much less efficient for storing binary data.
839 Reading the Output
841 As mentioned in Verbose there is a notation used to make understanding
842 the output easier. However at first glance it can probably be a bit
843 confusing. Take the following example:
844 my $x=1;
846 my $y=[];
847 my $array=sub{\@_ }->( $x,$x,$y );
848 push @$array,$y,1;
849 unshift @$array,\$array->[-1];
850 Dump($array);
851 Which prints (without the comments of course):
853 $ARRAY1 = [
855 'R: $ARRAY1->[5]', # resolved by fix 1
856 1,
857 'A: $ARRAY1->[1]', # resolved by fix 2
858 [],
859 'V: $ARRAY1->[3]', # resolved by fix 3
860 1
861 ];
862 $ARRAY1->[0] = \$ARRAY1->[5]; # fix 1
863 alias_av(@$ARRAY1, 2, $ARRAY1->[1]); # fix 2
864 $ARRAY1->[4] = $ARRAY1->[3]; # fix 3
865 The first entry, 'R: $ARRAY1->[5]' indicates that this slot in the
867 array holds a reference to the currently undefined "$ARRAY1->[5]", and
868 as such the value will have to be provided later in what the author
869 calls 'fix' statements. The third entry 'A: $ARRAY1->[1]' indicates
870 that is element of the array is in fact the exact same scalar as exists
871 in "$ARRAY1->[1]", or is in other words, an alias to that variable.
872 Again, this cannot be expressed in a single statement and so generates
873 another, different, fix statement. The fifth entry 'V: $ARRAY1->[3]'
874 indicates that this slots holds a value (actually a reference value)
875 that is identical to one elsewhere, but is currently undefined. In
876 this case it is because the value it needs is the reference returned by
877 the anonymous array constructor in the fourth element ("$ARRAY1->[3]").
878 Again this results in yet another different fix statement. If
879 Verbose() is off then only a 'R' 'A' or 'V' tag is emitted as a marker
880 of some form is necessary.
881 All of this specialized behaviour can be bypassed by setting Purity()
883 to FALSE, in which case the output will look very similar to what
884 Data::Dumper outputs in low Purity setting.
885 In a later version I'll try to expand this section with more examples.
887 A Note About Speed
889 Data::Dumper is much faster than this module for many things. However
890 IMO it is less readable, and definitely less accurate. YMMV.
891
893 By default exports the Dump() command. Or may export on request the
894 same command as Stream(). A Data::Dumper::Dumper compatibility routine
895 is provided via requesting Dumper and access to the real
896 Data::Dumper::Dumper routine is provided via DDumper. The later two are
897 exported together with the :Dumper tag.
898 Additionally there are a set of internally used routines that are
900 exposed. These are mostly direct copies of routines from
901 Array::RefElem, Lexical::Alias and Scalar::Util, however some where
902 marked have had their semantics slightly changed, returning defined but
903 false instead of undef for negative checks, or throwing errors on
904 failure.
905 The following XS subs (and tagnames for various groupings) are
907 exportable on request.
908 :Dumper
910 Dumper
911 DDumper
912 :undump # Collection of routines needed to undump something
914 alias_av # aliases a given array value to a scalar
915 alias_hv # aliases a given hashes value to a scalar
916 alias_ref # aliases a scalar to another scalar
917 make_ro # makes a scalar read only
918 lock_keys # pass through to Hash::Util::lock_keys
919 lock_keys_plus # like lock_keys, but adds keys to those present
920 lock_ref_keys # like lock_keys but operates on a hashref
921 lock_ref_keys_plus # like lock_keys_plus but operates on a hashref
922 dualvar # make a variable with different string/numeric
923 # representation
924 alias_to # pretend to return an alias, used in low
925 # purity mode to indicate a value is actually
926 # an alias to something else.
927 :alias # all croak on failure
929 alias_av(@Array,$index,$var);
930 alias_hv(%hash,$key,$var);
931 alias_ref(\$var1,\$var2);
932 push_alias(@array,$var);
933 :util
935 blessed($var) #undef or a class name.
936 isweak($var) #returns true if $var contains a weakref
937 reftype($var) #the underlying type or false but defined.
938 refaddr($var) #a references address
939 refcount($var) #the number of times a reference is referenced
940 sv_refcount($var) #the number of times a scalar is referenced.
941 weak_refcount($var) #the number of weakrefs to an object.
942 #sv_refcount($var)-weak_refcount($var) is the true
943 #SvREFCOUNT() of the var.
944 looks_like_number($var) #if perl will think this is a number.
945 regex($var) # In list context returns the pattern and the modifiers,
947 # in scalar context returns the pattern in (?msix:) form.
948 # If not a regex returns false.
949 readonly($var) # returns whether the $var is readonly
950 weaken($var) # cause the reference contained in var to become weak.
951 make_ro($var) # causes $var to become readonly, returns the value of $var.
952 reftype_or_glob # returns the reftype of a reference, or if its not
953 # a reference but a glob then the globs name
954 refaddr_or_glob # similar to reftype_or_glob but returns an address
955 # in the case of a reference.
956 globname # returns an evalable string to represent a glob, or
957 # the empty string if not a glob.
958 :all # (Dump() and Stream() and Dumper() and DDumper()
959 # and all of the XS)
960 :bin # (not Dump() but all of the rest of the XS)
961 By default exports only Dump(), DumpLex() and DumpVars(). Tags are
963 provided for exporting 'all' subroutines, as well as 'bin' (not
964 Dump()), 'util' (only introspection utilities) and 'alias' for the
965 aliasing utilities. If you need to ensure that you can eval the results
966 (undump) then use the 'undump' tag.
967
969 Code with this many debug statements is certain to have errors. :-)
970 Please report them with as much of the error output as possible.
972 Be aware that to a certain extent this module is subject to whimsies of
974 your local perl. The same code may not produce the same dump on two
975 different installs and versions. Luckily these don't seem to pop up
976 often.
977
979 Yves Orton, yves at cpan org.
980 Copyright (C) 2003-2005 Yves Orton
982 This library is free software; you can redistribute it and/or modify it
984 under the same terms as Perl itself.
985 Contains code derived from works by Gisle Aas, Graham Barr, Jeff
987 Pinyan, Richard Clamp, and Gurusamy Sarathy.
988 Thanks to Dan Brook, Yitzchak Scott-Thoennes, eric256, Joshua ben Jore,
990 Jim Cromie, Curtis "Ovid" Poe, Lars Dɪᴇᴄᴋᴏᴡ, and anybody that I've
991 forgotten for patches, feedback and ideas.
992
994 Data::Dumper - the mother of them all
995 Data::Dumper::Simple - Auto named vars with source filter interface.
997 Data::Dumper::Names - Auto named vars without source filtering.
999 Data::Dumper::EasyOO - easy to use wrapper for DD
1001 Data::Dump - Has cool feature to squeeze data
1003 Data::Dump::Streamer - The best perl dumper. But I would say that. :-)
1005 Data::TreeDumper - Non perl output, lots of rendering options
1007 And of course www.perlmonks.org and perl itself.
1009perl v5.38.0 2023-07-20 Data::Dump::Streamer(3pm)