1Data::Dump::Streamer(3)User Contributed Perl DocumentatioDnata::Dump::Streamer(3)
2
3
4

NAME

6       Data::Dump::Streamer - Accurately serialize a data structure as Perl
7       code.
8

SYNOPSIS

10         use Data::Dump::Streamer;
11         use DDS;                           # optionally installed alias
12
13         Dump($x,$y);                       # Prints to STDOUT
14         Dump($x,$y)->Out();                #   "          "
15
16         my $o=Data::Dump::Streamer->new(); # Returns a new ...
17         my $o=Dump();                      # ... uninitialized object.
18
19         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
24         Dump($x,$y)->To(\*STDERR)->Out();  # Prints to STDERR
25
26         Dump($x,$y)->Names('foo','bar')    # Specify Names
27                    ->Out();
28
29         Dump($x,$y)->Indent(0)->Out();     # No indent
30
31         Dump($x,$y)->To(\*STDERR)          # Output to STDERR
32                    ->Indent(0)             # ... no indent
33                    ->Names('foo','bar')    # ... specify Names
34                    ->Out();                # Print...
35
36         $o->Data($x,$y);                   # OO form of what Dump($x,$y) does.
37         $o->Names('Foo','Names');          #  ...
38         $o->Out();                         #  ...
39

DESCRIPTION

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
47       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
51       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
58       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
63   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
74       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
79       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
87       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
94         my $a = sub { $a++ };
95         Dump( sub { $a->() } );
96
97       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
101       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
106       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

USAGE

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
117          Dump($foo);
118          $as_string= Dump($foo)->Out();
119
120       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
125       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
131       Attributes once set last the lifetime of the object, unless explicitly
132       reset.
133
134   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
141           my ( $proxy, $thaw, $postop )= $callback->($obj);
142           #or                          = $obj->$method();
143
144       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
154       The interface of the Freezer() handler in detail is as follows:
155
156       $obj
157           The object being dumped.
158
159       $proxy
160           This is what will be dumped instead of $obj. It may be one of the
161           following values:
162
163           "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
169           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
175           A Reference
176                   A reference that will be dumped instead of the object.
177
178           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
185       $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
191           FALSE value
192                   Indicates no thaw action is to be included for this object.
193
194           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
201           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
207       $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
212           FALSE value
213                   No postdump action is to occur.
214
215           Code Reference
216                   The code ref will be called after serialization is complete
217                   with the object as the argument.
218
219           Method Name
220                   The method will be called after serialization is complete
221
222       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
227           sub DDS_freeze {
228               my $self=shift;
229               delete $self->{'tie'};
230               return ($self,'->fix_tie','fix_tie');
231           }
232
233           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
243       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
247          $Foo1=bless({ str=>'' },'Foo')->fix_tie();
248
249       Wheras if we omit the "->" then we would get:
250
251           $Foo1=bless({ str=>'' },'Foo');
252           $Foo1->fix_tie();
253
254       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
261       See "Controlling Hash Traversal and Display Order" for a different way
262       to control the representation of hash based objects.
263
264   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
270       You can use the KeyOrder() routine or the SortKeys() routine to specify
271       the sorter to be used.
272
273       The routine will be called in the following way:
274
275          ( $key_array, $thaw ) = $sorter->($hash,($pass=0),$addr,$class);
276          ( $key_array,)        = $sorter->($hash,($pass=1),$addr,$class);
277
278       $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
281       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
288       Note that if a Freezer() method is defined and returns a $thaw then the
289       $thaw returned by the sorter will override it.
290
291   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
298          $ARRAY1 = [ (0) x 4 ];
299
300       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
304       To disable this feature you may set the Rle() property to FALSE, by
305       default it is enabled and set to TRUE.
306
307   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
316         perl Build.Pl DDS [Other Module::Build options]
317
318       Then a normal './Build test, ./Build install' invocation will install
319       DDS.
320
321       Using DDS is identical to Data::Dump::Streamer.
322
323   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
328         use Data::Dumper::Streamer as => 'DDS';
329
330         # or if you prefer
331         use Data::Dumper::Streamer;
332         import Data::Dumper::Streamer as => 'DDS';
333
334       You can use any alias you like, but that doesn't mean you should..
335       Folks doing as => 'DBI' will be mercilessly ridiculed.
336
337   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

INTERFACE

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
352       Dumper
353       Dumper LIST
354           A synonym for scalar Dump(LIST)->Out for usage compatibility with
355           Data::Dumper
356
357       DDumper
358       DDumper LIST
359           A secondary export of the actual Data::Dumper::Dumper subroutine.
360
361   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
366           See Dump() for a better way to do things.
367
368       Dump
369       Dump VALUES
370           Smart non method based constructor.
371
372           This routine behaves very differently depending on the context it
373           is called in and whether arguments are provided.
374
375           If called with no arguments it is exactly equivalent to calling
376
377             Data::Dump::Streamer->new()
378
379           which means it returns an object reference.
380
381           If called with arguments and in scalar context it is equivalent to
382           calling
383
384             Data::Dump::Streamer->new()->Data(@vals)
385
386           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
391           If called with arguments and in void or list context it is
392           equivelent to calling
393
394             Data::Dump::Streamer->new()->Data(@vals)->Out()
395
396           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
401           So to put it short:
402
403             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
407             Dump($x,$y);                 # prints the dump.
408             print Dump($x,$y);           # prints the dump.
409
410           It should be noted that the setting of "$\" will affect the
411           behaviour of both of
412
413             Dump($x,$y);
414             print Dump($x,$y);
415
416           but it will not affect the behaviour of
417
418             print scalar Dump($x,$y);
419
420           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
424             $obj->Dump($foo)->Names('foo')->Out();
425
426           will work fine, as will the odd looking:
427
428             $obj->Dump($foo)->Names('foo')->Dump();
429
430           which are both the same as
431
432             $obj->Names('foo')->Data($foo)->Out();
433
434           Hopefully this should make method use more or less DWIM.
435
436       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
444           Thanks to Ovid for the idea of this. See Data::Dumper::Simple for a
445           similar wrapper around Data::Dumper.
446
447       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
453   Methods
454       Data
455       Data LIST
456           Analyzes a list of variables in breadth first order.
457
458           If called with arguments then the internal object state is reset
459           before scanning the list of arguments provided.
460
461           If called with no arguments then whatever arguments were provided
462           to Dump() will be scanned.
463
464           Returns $self.
465
466       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
473           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
477           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
481           This routine is virtually always called without arguments as the
482           last method in the method chain.
483
484            Dump->Arguments(1)->Out(@vars);
485            $obj->Data(@vars)->Out();
486            Dump(@vars)->Out;
487            Data::Dump::Streamer->Out(@vars);
488
489           All should DWIM.
490
491       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
501           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
505           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
510           NOTE: Must be called before Data() is called.
511
512           If you wish to have no names, use Terse.
513
514       Terse
515       Terse BOOL
516           When true, no variable names will be created.  Data will be dumped
517           as anonymous references or values.
518
519               Dump([])->Out;              # $ARRAY1 = []
520               Dump([])->Terse(1)->Out;    # []
521
522       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
536           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
542       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
549           If a filehandle is specified then it is used until it is explicitly
550           changed, or the object is destroyed.
551
552       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
560           Defaults to False.
561
562       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
571           Default is Indent(2)
572
573           If indent is False then no indentation is done, and all optional
574           whitespace.  is omitted. See <OptSpace()|/OptSpace> for more
575           details.
576
577           Defaults to True.
578
579           Newlines are appended to each statement regardless of this value.
580
581       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
589           Defaults to True.
590
591           NOTE: Must be set before Data() is called.
592
593       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
599           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
604       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
609           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
612           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
616           The built in sort mechanisms are 'aphabetical'/'lexical',
617           'numeric', 'smart'/'intelligent' and 'each'.
618
619           If VALUE is omitted returns the current value for the given type.
620
621           If TYPE_OR_OBJ is omitted or FALSE it defaults to "" which
622           represents unblessed hashes.
623
624           See "Controlling Hash Traversal and Display Order" for more
625           details.
626
627       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
633             $self->KeyOrder( "", @_ );
634
635       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
647           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
652           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
657           Defaults to True.
658
659           NOTE: Must be set before Data() is called.
660
661       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
667           Defaults to True
668
669           NOTE: Must be set before Data() is called.
670
671       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
677           Caveat Emptor, dumping subroutine references is hardly a secure
678           act, and it is provided here only for convenience.
679
680           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
684       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
693             "%s_eclipse_%d"
694
695           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
698       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
709           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
713       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
719           Defaults to 'sub { Carp::confess "Dumped code stub!" }'
720
721       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
727           Defaults to 'do{ local *F; eval "format F =\nFormat Stub\n.\n";
728           *F{FORMAT} }'
729
730       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
736           Defaults to True.
737
738       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
747       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
757       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
764           If ACTION is false it indicates that the given CLASS should not
765           have any serilization hooks called.
766
767           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
771           If ACTION is a code ref it is executed with the object as the
772           argument.
773
774           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
779           If the action executes a sub or method it is expected to return a
780           list of three values:
781
782              ( $proxy, $thaw, $postdump )=$obj->DDS_Freeze();
783
784           See "Controlling Object Representation" for more details.
785
786           NOTE: Must be set before Data() is called.
787
788       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
794           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
799           Returns $self when setting.
800
801           NOTE: Must be set before Data() is called.
802
803       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
811       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
817             my $prelude_code=$compressor->(); # no arguments.
818             my $code=$compressor->('string'); # string argument
819
820           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
826           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
830           The abbreviated name was chosen as when using the default
831           compressor every string will be represented by a string like
832
833              usqz('....')
834
835           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
840   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
845           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
852       Which prints (without the comments of course):
853
854           $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
866       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
882       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
886       In a later version I'll try to expand this section with more examples.
887
888   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

EXPORT

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
899       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
906       The following XS subs (and tagnames for various groupings) are
907       exportable on request.
908
909         :Dumper
910               Dumper
911               DDumper
912
913         :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
928         :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
934         :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
946            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
962       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

BUGS

969       Code with this many debug statements is certain to have errors. :-)
970
971       Please report them with as much of the error output as possible.
972
973       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
981       Copyright (C) 2003-2005 Yves Orton
982
983       This library is free software; you can redistribute it and/or modify it
984       under the same terms as Perl itself.
985
986       Contains code derived from works by Gisle Aas, Graham Barr, Jeff
987       Pinyan, Richard Clamp, and Gurusamy Sarathy.
988
989       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

SEE ALSO (its a crowded space, isn't it!)

994       Data::Dumper - the mother of them all
995
996       Data::Dumper::Simple - Auto named vars with source filter interface.
997
998       Data::Dumper::Names - Auto named vars without source filtering.
999
1000       Data::Dumper::EasyOO - easy to use wrapper for DD
1001
1002       Data::Dump - Has cool feature to squeeze data
1003
1004       Data::Dump::Streamer - The best perl dumper. But I would say that. :-)
1005
1006       Data::TreeDumper - Non perl output, lots of rendering options
1007
1008       And of course www.perlmonks.org and perl itself.
1009
1010
1011
1012perl v5.36.0                      2023-02-21           Data::Dump::Streamer(3)
Impressum