1TreeDumper(3)         User Contributed Perl Documentation        TreeDumper(3)
2
3
4

NAME

6       Data::TreeDumper - Improved replacement for Data::Dumper. Powerful
7       filtering capability.
8

SYNOPSIS

10         use Data::TreeDumper ;
11
12         my $sub = sub {} ;
13
14         my $s =
15         {
16         A =>
17               {
18               a =>
19                       {
20                       }
21               , bbbbbb => $sub
22               , c123 => $sub
23               , d => \$sub
24               }
25
26         , C =>
27               {
28               b =>
29                       {
30                       a =>
31                               {
32                               a =>
33                                       {
34                                       }
35
36                               , b => sub
37                                       {
38                                       }
39                               , c => 42
40                               }
41
42                       }
43               }
44         , ARRAY => [qw(elment_1 element_2 element_3)]
45         } ;
46
47
48         #-------------------------------------------------------------------
49         # package setup data
50         #-------------------------------------------------------------------
51
52         $Data::TreeDumper::Useascii = 0 ;
53         $Data::TreeDumper::Maxdepth = 2 ;
54
55         print DumpTree($s, 'title') ;
56         print DumpTree($s, 'title', MAX_DEPTH => 1) ;
57         print DumpTrees
58                 (
59                   [$s, "title", MAX_DEPTH => 1]
60                 , [$s2, "other_title", DISPLAY_ADDRESS => 0]
61                 , USE_ASCII => 1
62                 , MAX_DEPTH => 5
63                 ) ;
64

Output

66         title:
67         |- A [H1]
68         |  |- a [H2]
69         |  |- bbbbbb = CODE(0x8139fa0) [C3]
70         |  |- c123 [C4 -> C3]
71         |  `- d [R5]
72         |     `- REF(0x8139fb8) [R5 -> C3]
73         |- ARRAY [A6]
74         |  |- 0 [S7] = elment_1
75         |  |- 1 [S8] = element_2
76         |  `- 2 [S9] = element_3
77         `- C [H10]
78            `- b [H11]
79               `- a [H12]
80                  |- a [H13]
81                  |- b = CODE(0x81ab130) [C14]
82                  `- c [S15] = 42
83

DESCRIPTION

85       Data::Dumper and other modules do a great job of dumping data
86       structures.  Their output, however, often takes more brain power to
87       understand than the data itself.  When dumping large amounts of data,
88       the output can be overwhelming and it can be difficult to see the
89       relationship between each piece of the dumped data.
90
91       Data::TreeDumper also dumps data in a tree-like fashion but hopefully
92       in a format more easily understood.
93
94   Label
95       Each node in the tree has a label. The label contains a type and an
96       address. The label is displayed to the right of the entry name within
97       square brackets.
98
99         |  |- bbbbbb = CODE(0x8139fa0) [C3]
100         |  |- c123 [C4 -> C3]
101         |  `- d [R5]
102         |     `- REF(0x8139fb8) [R5 -> C3]
103
104       Address
105
106       The addresses are linearly incremented which should make it easier to
107       locate data.  If the entry is a reference to data already displayed, a
108       -> followed with the address of the already displayed data is appended
109       within the label.
110
111         ex: c123 [C4 -> C3]
112                    ^     ^
113                    |     | address of the data refered to
114                    |
115                    | current element address
116
117       Types
118
119       S: Scalar, H: Hash, A: Array, C: Code,
120
121       R: Reference, RS: Scalar reference.  Ox: Object, where x is the object
122       undelying type
123
124   Empty Hash or Array
125       No structure is displayed for empty hashes or arrays, the string "no
126       elements" is added to the display.
127
128         |- A [S10] = string
129         |- EMPTY_ARRAY (no elements) [A11]
130         |- B [S12] = 123
131

Configuration and Overrides

133       Data::TreeDumper has configuration options you can set to modify the
134       output it generates. DumpTree and PrintTree take overrides as trailing
135       arguments. Those overrides are active within the current dump call
136       only.
137
138         ex:
139         $Data::TreeDumper::Maxdepth = 2 ;
140
141         # maximum depth set to 1 for the duration of the call only
142         print DumpTree($s, 'title', MAX_DEPTH => 1) ;
143         PrintTree($s, 'title', MAX_DEPTH => 1) ; # shortcut for the above call
144
145         # maximum depth is 2
146         print DumpTree($s, 'title') ;
147
148   $Data::TreeDumper::Displaycallerlocation
149       This package variable is very usefull when you use Data::TreeDumper and
150       don't know where you called PrintTree or DumpTree, ie when debugging.
151       It displays the filename and line of call on STDOUT.  It can't also be
152       set as an override,  DISPLAY_CALLER_LOCATION => 1.
153
154   NO_PACKAGE_SETUP
155       Sometimes, the package setup you have is not what you want to use.
156       resetting the variable, making a call and setting the variables back is
157       borring. You can set NO_PACKAGE_SETUP to 1 and DumpTree will ignore the
158       package setup for the call.
159
160         print Data::TreeDumper::DumpTree($s, "Using package data") ;
161         print Data::TreeDumper::DumpTree($s, "Not Using package data", NO_PACKAGE_SETUP => 1) ;
162
163   DISPLAY_ROOT_ADDRESS
164       By default, Data::TreeDumper doesn't display the address of the root.
165
166         DISPLAY_ROOT_ADDRESS => 1 # show the root address
167
168   DISPLAY_ADDRESS
169       When the dumped data is not self-referential, displaying the address of
170       each node clutters the display. You can direct Data::TreeDumper to not
171       display the node address by using:
172
173         DISPLAY_ADDRESS => 0
174
175   DISPLAY_PATH
176       Add the path of the element to the its address.
177
178         DISPLAY_PATH => 1
179
180         ex: '- CopyOfARRAY  [A39 -> A18 /{'ARRAY'}]
181
182   DISPLAY_OBJECT_TYPE
183       Data::TreeDumper displays the package in which an object is blessed.
184       You can suppress this display by using:
185
186         DISPLAY_OBJECT_TYPE => 0
187
188   DISPLAY_INHERITANCE
189       Data::TreeDumper will display the inheritance hierarchy for the object:
190
191         |- object =  blessed in 'SuperObject' <- Potatoe [OH55]
192         |  `- Data = 0  [S56]
193
194   DISPLAY_AUTOLOAD
195       if set, Data::TreeDumper will tag the object type with '[A]' if the
196       package has an AUTOLOAD function.
197
198         |- object_with_autoload = blessed in '[A]SuperObjectWithAutoload' <- Potatoe <- [A] Vegetable   [O58]
199         |  `- Data = 0  [S56]
200
201   DISPLAY_TIE
202       if DISPLAY_TIE is set, Data::TreeDumper will display which packae the
203       variable is tied to. This works for hashes and arrays as well as for
204       object which are based on hashes and arrays.
205
206         |- tied_hash (tied to 'TiedHash')  [H57]
207         |  `- x = 1  [S58]
208
209         |- tied_hash_object = (tied to 'TiedHash') blessed in 'SuperObject' <- [A]Potatoe <- Vegetable   [O59]
210         |  |- m1 = 1  [S60]
211         |  `- m2 = 2  [S61]
212
213   PERL DATA
214       Setting one of the options below will show internal perl data:
215
216         Cells: <2234> HASH(0x814F20c)
217         |- A1 [H1] <204> HASH(0x824620c)
218         |  `- VALUE [S2] = datadatadatadatadatadatadatadatadatadata <85>
219         |- A8 [H11] <165> HASH(0x8243d68)
220         |  `- VALUE [S12] = C <46>
221         `- C2 [H19] <165> HASH(0x8243dc0)
222            `- VALUE [S20] = B <46>
223
224       DISPLAY_PERL_SIZE
225
226       Setting this option will show the size of the memory allocated for each
227       element in the tree within angle brackets.
228
229         DISPLAY_PERL_SIZE => 1
230
231       The excellent Devel::Size is used to compute the size of the perl data.
232       If you have deep circular data structures, expect the dump time to be
233       slower, 50 times slower or more.
234
235       DISPLAY_PERL_ADDRESS
236
237       Setting this option will show the perl-address of the dumped data.
238
239         DISPLAY_PERL_ADDRESS => 1
240
241   REPLACEMENT_LIST
242       Scalars may contain non printable characters that you rather not see in
243       a dump. One of the most common is "\r" embedded in text string from dos
244       files. Data::TreeDumper, by default, replaces "\n" by '[\n]' and "\r"
245       by '[\r]'. You can set REPLACEMENT_LIST to an array ref containing
246       elements which are themselves array references. The first element is
247       the character(s) to match and the second is the replacement.
248
249         # a fancy and stricter replacement for \n and \r
250         my $replacement = [ ["\n" => '[**Fancy \n replacement**]'], ["\r" => '\r'] ] ;
251         print DumpTree($smed->{TEXT}, 'Text:', REPLACEMENT_LIST => $replacement) ;
252
253   QUOTE_HASH_KEYS
254       QUOTE_HASH_KEYS and its package variable
255       $Data::TreeDumper::Quotehashkeys can be set if you wish to single quote
256       the hash keys. Hash keys are not quoted by default.
257
258         DumpTree(\$s, 'some data:', QUOTE_HASH_KEYS => 1) ;
259
260         # output
261         some data:
262         `- REF(0x813da3c) [H1]
263            |- 'A' [H2]
264            |  |- 'a' [H3]
265            |  |- 'b' [H4]
266            |  |  |- 'a' = 0 [S5]
267
268   QUOTE_VALUES
269       QUOTE_VALUES and its package variable $Data::TreeDumper::Quotevalues
270       can be set if you wish to single quote the scalar values.
271
272         DumpTree(\$s, 'Cells:', QUOTE_VALUES=> 1) ;
273
274   NO_NO_ELEMENTS
275       If this option is set, Data::TreeDumper will not add 'no elements' to
276       empty hashes and arrays
277
278   NO_OUTPUT
279       This option suppresses all output generated by Data::TreeDumper.  This
280       is useful when you want to iterate through your data structures and
281       display the data yourself, manipulate the data structure, or do a
282       search (see "using filter as iterators" below)
283
284   Filters
285       Data::TreeDumper can sort the tree nodes with a user defined
286       subroutine. By default, hash keys are sorted.
287
288         FILTER => \&ReverseSort
289         FILTER_ARGUMENT => ['your', 'arguments']
290
291       The filter routine is passed these arguments:
292
293       1 - a reference to the node which is going to be displayed
294       2 - the nodes depth (this allows you to selectively display elements at
295       a certain depth)
296       3 - the path to the reference from the start of the dump.
297       4 - an array reference containing the keys to be displayed (see "Filter
298       chaining")
299       5 - the dumpers setup
300       5 - the filter arguments (see below)
301
302       The filter returns the node's type, an eventual new structure (see
303       below) and a list of 'keys' to display. The keys are hash keys or array
304       indexes.
305
306       In Perl:
307
308         ($tree_type, $replacement_tree, @nodes_to_display) = $your_filter->($tree, $level, $path, $nodes_to_display, $setup) ;
309
310       Filter are not as complicated as they sound and they are very
311       powerfull, especially when using the path argument.  The path idea was
312       given to me by another module writer but I forgot whom. If this writer
313       will contact me, I will give him the proper credit.
314
315       Lots of examples can be found in filters.pl and I'll be glad to help if
316       you want to develop a specific filter.
317
318       FILTER_ARGUMENT
319
320       it is possible to pass arguments to your filter, passing a reference
321       allows you to modify the arguments when the filter is run (that
322       happends for each node).
323
324        sub SomeSub
325        {
326        my $counter = 0 ;
327        my $data_structure = {.....} ;
328
329        DumpTree($data_structure, 'title', FILTER => \&CountNodes, FILTER_ARGUMENT => \$counter) ;
330
331        print "\$counter = $counter\n" ;
332        }
333
334        sub CountNodes
335        {
336        my ($structure, $level, $path, $nodes_to_display, $setup, $counter) = @_ ;
337        $$counter++ ; # remember to pass references if you want them to be changed by the filter
338
339        return(DefaultNodesToDisplay($structure)) ;
340        }
341
342       Key removal
343
344       Entries can be removed from the display by not returning their keys.
345
346         my $s = {visible => '', also_visible => '', not_visible => ''} ;
347         my $OnlyVisible = sub
348               {
349               my $s = shift ;
350
351               if('HASH' eq ref $s)
352                       {
353                       return('HASH', undef, grep {! /^not_visible/} keys %$s) ;
354                       }
355
356               return(Data::TreeDumper::DefaultNodesToDisplay($s)) ;
357               }
358
359         DumpTree($s, 'title', FILTER => $OnlyVisible) ;
360
361       Label changing
362
363       The label for a hash keys or an array index can be altered. This can be
364       used to add visual information to the tree dump. Instead of returning
365       the key name, return an array reference containing the key name and the
366       label you want to display.  You only need to return such a reference
367       for the entries you want to change, thus a mix of scalars and array ref
368       is acceptable.
369
370         sub StarOnA
371         {
372         # hash entries matching /^a/i have '*' prepended
373
374         my $tree = shift ;
375
376         if('HASH' eq ref $tree)
377               {
378               my @keys_to_dump ;
379
380               for my $key_name (keys %$tree)
381                       {
382                       if($key_name =~ /^a/i)
383                               {
384                               $key_name = [$key_name, "* $key_name"] ;
385                               }
386
387                       push @keys_to_dump, $key_name ;
388                       }
389
390               return ('HASH', undef, @keys_to_dump) ;
391               }
392
393         return (Data::TreeDumper::DefaultNodesToDisplay($tree)) ;
394         }
395
396         print DumpTree($s, "Entries matching /^a/i have '*' prepended", FILTER => \&StarOnA) ;
397
398       If you use an ANSI terminal, you can also change the color of the
399       label.  This can greatly improve visual search time.  See the label
400       coloring example in colors.pl.
401
402       Structure replacement
403
404       It is possible to replace the whole data structure in a filter. This
405       comes handy when you want to display a "worked" version of the
406       structure. You can even change the type of the data structure, for
407       example changing an array to a hash.
408
409         sub ReplaceArray
410         {
411         # replace arrays with hashes!!!
412
413         my $tree = shift ;
414
415         if('ARRAY' eq ref $tree)
416               {
417               my $multiplication = $tree->[0] * $tree->[1] ;
418               my $replacement = {MULTIPLICATION => $multiplication} ;
419               return('HASH', $replacement, keys %$replacement) ;
420               }
421
422         return (Data::TreeDumper::DefaultNodesToDisplay($tree)) ;
423         }
424
425         print DumpTree($s, 'replace arrays with hashes!', FILTER => \&ReplaceArray) ;
426
427       Here is a real life example. Tree::Simple
428       (<http://search.cpan.org/dist/Tree-Simple/>) allows one to build tree
429       structures. The child nodes are not directly in the parent object
430       (hash). Here is an unfiltered dump of a tree with seven nodes:
431
432         Tree::Simple through Data::TreeDumper
433         |- _children
434         |  |- 0
435         |  |  |- _children
436         |  |  |  `- 0
437         |  |  |     |- _children
438         |  |  |     |- _depth = 1
439         |  |  |     |- _node = 1.1
440         |  |  |     `- _parent
441         |  |  |- _depth = 0
442         |  |  |- _node = 1
443         |  |  `- _parent
444         |  |- 1
445         |  |  |- _children
446         |  |  |  |- 0
447         |  |  |  |  |- _children
448         |  |  |  |  |- _depth = 1
449         |  |  |  |  |- _node = 2.1
450         |  |  |  |  `- _parent
451         |  |  |  |- 1
452         |  |  |  |  |- _children
453         |  |  |  |  |- _depth = 1
454         |  |  |  |  |- _node = 2.1a
455         |  |  |  |  `- _parent
456         |  |  |  `- 2
457         |  |  |     |- _children
458         |  |  |     |- _depth = 1
459         |  |  |     |- _node = 2.2
460         |  |  |     `- _parent
461         |  |  |- _depth = 0
462         |  |  |- _node = 2
463         |  |  `- _parent
464         |  `- 2
465         |     |- _children
466         |     |- _depth = 0
467         |     |- _node = 3
468         |     `- _parent
469         |- _depth = -1
470         |- _node = 0
471         `- _parent = root
472
473       This is nice for the developer but not for a user wanting to oversee
474       the node hierarchy. One of the possible filters would be:
475
476         FILTER => sub
477                       {
478                       my $s = shift ;
479
480                       if('Tree::Simple' eq ref $s)
481                               {
482                               my $counter = 0 ;
483
484                               return
485                                       (
486                                       'ARRAY'
487                                       , $s->{_children}
488                                       , map{[$counter++, $_->{_node}]} @{$s->{_children}} # index generation
489                                       ) ;
490                               }
491
492                       return(Data::TreeDumper::DefaultNodesToDisplay($s)) ;
493                       }
494
495       Which would give this much more readable output:
496
497         Tree::Simple through Data::TreeDumper2
498         |- 1
499         |  `- 1.1
500         |- 2
501         |  |- 2.1
502         |  |- 2.1a
503         |  `- 2.2
504         `- 3
505
506       What about counting the children nodes? The index generating code
507       becomes:
508
509         map{[$counter++, "$_->{_node} [" . @{$_->{_children}} . "]"]} @{$s->{_children}}
510
511         Tree::Simple through Data::TreeDumper4
512         |- 1 [1]
513         |  `- 1.1 [0]
514         |- 2 [3]
515         |  |- 2.1 [0]
516         |  |- 2.1a [0]
517         |  `- 2.2 [0]
518         `- 3 [0]
519
520       Filter chaining
521
522       It is possible to chain filters. CreateChainingFilter takes a list of
523       filtering sub references.  The filters must properly handle the third
524       parameter passed to them.
525
526       Suppose you want to chain a filter that adds a star before each hash
527       key label, with a filter that removes all (original) keys that match
528       /^a/i.
529
530         sub AddStar
531               {
532               my $s = shift ;
533               my $level = shift ;
534               my $path = shift ;
535               my $keys = shift ;
536
537               if('HASH' eq ref $s)
538                       {
539                       $keys = [keys %$s] unless defined $keys ;
540
541                       my @new_keys ;
542
543                       for (@$keys)
544                               {
545                               if('' eq ref $_)
546                                       {
547                                       push @new_keys, [$_, "* $_"] ;
548                                       }
549                               else
550                                       {
551                                       # another filter has changed the label
552                                       push @new_keys, [$_->[0], "* $_->[1]"] ;
553                                       }
554                               }
555
556                       return('HASH', undef, @new_keys) ;
557                       }
558
559               return(Data::TreeDumper::DefaultNodesToDisplay($s)) ;
560               } ;
561
562         sub RemoveA
563               {
564               my $s = shift ;
565               my $level = shift ;
566               my $path = shift ;
567               my $keys = shift ;
568
569               if('HASH' eq ref $s)
570                       {
571                       $keys = [keys %$s] unless defined $keys ;
572                       my @new_keys ;
573
574                       for (@$keys)
575                               {
576                               if('' eq ref $_)
577                                       {
578                                       push @new_keys, $_ unless /^a/i ;
579                                       }
580                               else
581                                       {
582                                       # another filter has changed the label
583                                       push @new_keys, $_ unless $_->[0] =~ /^a/i ;
584                                       }
585                               }
586
587                       return('HASH', undef, @new_keys) ;
588                       }
589
590               return(Data::TreeDumper::DefaultNodesToDisplay($s)) ;
591               } ;
592
593         DumpTree($s, 'Chained filters', FILTER => CreateChainingFilter(\&AddStar, \&RemoveA)) ;
594
595   level Filters
596       It is possible to define one filter for a specific level. If a filter
597       for a specific level exists it is used instead of the global filter.
598
599       LEVEL_FILTERS => {1 => \&FilterForLevelOne, 5 => \&FilterForLevelFive
600       ... } ;
601
602   Type Filters
603       You can define filters for specific types of references. This filter
604       type has the highest priority.
605
606       here's a very simple filter that will display the specified keys for
607       the types
608
609               print DumpTree
610                       (
611                       $data,
612                       'title',
613                       TYPE_FILTERS =>
614                               {
615                               'Config::Hierarchical' => sub {'HASH', undef, qw(CATEGORIES) },
616                               'PBS2::Node' => sub {'HASH', undef, qw(CONFIG DEPENDENCIES MATCH) },,
617                               }
618                       ) ;
619
620   Using filters as iterators
621       You can iterate through your data structures and display data yourself,
622       manipulate the data structure, or do a search. While iterating through
623       the data structure, you can prune arbitrary branches to speedup
624       processing.
625
626         # this example counts the nodes in a tree (hash based)
627         # a node is counted if it has a '__NAME' key
628         # any field that starts with '__' is considered rivate and we prune so we don't recurse in it
629         # anything that is not a hash (the part of the tree that interests us in this case) is pruned
630
631         my $number_of_nodes_in_the_dependency_tree = 0 ;
632         my $node_counter =
633               sub
634               {
635               my $tree = shift ;
636               if('HASH' eq ref $tree && exists $tree->{__NAME})
637                       {
638                       $number_of_nodes_in_the_dependency_tree++ if($tree->{__NAME} !~ /^__/) ;
639
640                       return('HASH', $tree, grep {! /^__/} keys %$tree) ; # prune to run faster
641                       }
642               else
643                       {
644                       return('SCALAR', 1) ; # prune
645                       }
646               } ;
647
648         DumpTree($dependency_tree, '', NO_OUTPUT => 1, FILTER => $node_counter) ;
649
650       See the example under FILTER which passes arguments through
651       Data::TreeDumper instead for using a closure as above
652
653   Start level
654       This configuration option controls whether the tree trunk is displayed
655       or not.
656
657       START_LEVEL => 1:
658
659         $tree:
660         |- A [H1]
661         |  |- a [H2]
662         |  |- bbbbbb = CODE(0x8139fa0) [C3]
663         |  |- c123 [C4 -> C3]
664         |  `- d [R5]
665         |     `- REF(0x8139fb8) [R5 -> C3]
666         |- ARRAY [A6]
667         |  |- 0 [S7] = element_1
668         |  |- 1 [S8] = element_2
669
670       START_LEVEL => 0:
671
672         $tree:
673         A [H1]
674         |- a [H2]
675         |- bbbbbb = CODE(0x8139fa0) [C3]
676         |- c123 [C4 -> C3]
677         `- d [R5]
678            `- REF(0x8139fb8) [R5 -> C3]
679         ARRAY [A6]
680         |- 0 [S7] = element_1
681         |- 1 [S8] = element_2
682
683   ASCII vs ANSI
684       You can direct Data:TreeDumper to output ANSI codes instead of ASCII
685       characters. The display will be much nicer but takes slightly longer
686       (not significant for small data structures).
687
688         USE_ASCII => 0 # will use ANSI codes instead
689
690   Display number of elements
691         DISPLAY_NUMBER_OF_ELEMENTS => 1
692
693       When set, the number of elements of every array and hash is displayed
694       (not for objects based on hashes and arrays).
695
696   Maximum depth of the dump
697       Controls the depth beyond which which we don't recurse into a
698       structure. Default is -1, which means there is no maximum depth. This
699       is useful to limit the amount of data displayed.
700
701         MAX_DEPTH => 1
702
703   Number of elements not displayed because of maximum depth limit
704       Data::TreDumper will display the number of elements a hash or array has
705       but that can not be displayed because of the maximum depth setting.
706
707         DISPLAY_NUMBER_OF_ELEMENTS_OVER_MAX_DEPTH => 1
708
709   Indentation
710       Every line of the tree dump will be appended with the value of
711       INDENTATION.
712
713         INDENTATION => '   ' ;
714

Custom glyphs

716       You can  change the glyphs used by Data::TreeDumper.
717
718         DumpTree(\$s, 's', , GLYPHS => ['.  ', '.  ', '.  ', '.  ']) ;
719
720         # output
721         s
722         .  REF(0x813da3c) [H1]
723         .  .  A [H2]
724         .  .  .  a [H3]
725         .  .  .  b [H4]
726         .  .  .  .  a = 0 [S5]
727         .  .  .  .  b = 1 [S6]
728         .  .  .  .  c [H7]
729         .  .  .  .  .  a = 1 [S8]
730
731       Four glyphs must be given. They replace the standard glyphs ['|  ', '|-
732       ', '`- ', '   ']. It is also possible to set the package variable
733       $Data::TreeDumper::Glyphs. USE_ASCII should be set, which it is by
734       default.
735

Level numbering and tagging

737       Data:TreeDumper can prepend the level of the current line to the tree
738       glyphs. This can be very useful when searching in tree dump either
739       visually or with a pager.
740
741         NUMBER_LEVELS => 2
742         NUMBER_LEVELS => \&NumberingSub
743
744       NUMBER_LEVELS can be assigned a number or a sub reference. When
745       assigned a number, Data::TreeDumper will use that value to define the
746       width of the field where the level is displayed. For more control, you
747       can define a sub that returns a string to be displayed on the left side
748       of the tree glyphs. The example below tags all the nodes whose level is
749       zero.
750
751         print DumpTree($s, "Level numbering", NUMBER_LEVELS => 2) ;
752
753         sub GetLevelTagger
754         {
755         my $level_to_tag = shift ;
756
757         sub
758               {
759               my ($element, $level, $setup) = @_ ;
760
761               my $tag = "Level $level_to_tag => ";
762
763               if($level == 0)
764                       {
765                       return($tag) ;
766                       }
767               else
768                       {
769                       return(' ' x length($tag)) ;
770                       }
771               } ;
772         }
773
774         print DumpTree($s, "Level tagging", NUMBER_LEVELS => GetLevelTagger(0)) ;
775

Level coloring

777       Another way to enhance the output for easier searching is to colorize
778       it. Data::TreeDumper can colorize the glyph elements or whole levels.
779       If your terminal supports ANSI codes, using Term::ANSIColors and
780       Data::TreeDumper together can greatly ease the reading of large dumps.
781       See the examples in 'color.pl'.
782
783         COLOR_LEVELS => [\@color_codes, $reset_code]
784
785       When passed an array reference, the first element is an array
786       containing coloring codes. The codes are indexed with the node level
787       modulo the size of the array. The second element is used to reset the
788       color after the glyph is displayed. If the second element is an empty
789       string, the glyph and the rest of the level is colorized.
790
791         COLOR_LEVELS => \&LevelColoringSub
792
793       If COLOR_LEVEL is assigned a sub, the sub is called for each glyph
794       element. It is passed the following elements:
795
796       1 - the nodes depth (this allows you to selectively display elements at
797       a certain depth)
798
799       It should return a coloring code and a reset code. If you return an
800       empty string for the reset code, the whole node is displayed using the
801       last glyph element color.
802
803       If level numbering is on, it is also colorized.
804

Wrapping

806       Data::TreeDumper uses the Text::Wrap module to wrap your data to fit
807       your display. Entries can be wrapped multiple times so they snuggly fit
808       your screen.
809
810         |  |        |- 1 [S21] = 1
811         |  |        `- 2 [S22] = 2
812         |  `- 3 [OH23 -> R17]
813         |- ARRAY_ZERO [A24]
814         |- B [S25] = scalar
815         |- Long_name Long_name Long_name Long_name Long_name Long_name
816         |    Long_name Long_name Long_name Long_name Long_name Long_name
817         |    Long_name Long_name Long_name Long_name Long_name [S26] = 0
818
819       You can direct DTD to not wrap your text by setting NO_WRAP = 1>.
820
821   WRAP_WIDTH
822       if this option is set, Data::TreeDumper will use it instead for the
823       console width.
824

Custom Rendering

826       Data::TreeDumper has a plug-in interface for other rendering formats.
827       The renderer callbacks are set by overriding the native renderer.
828       Thanks to Stevan Little author of Tree::Simple::View for getting
829       Data::TreeDumper on this track. Check
830       Data::TreeDumper::Renderer::DHTML.
831
832        DumpTree
833               (
834                 $s
835               , 'Tree'
836               , RENDERER =>
837                       {
838                         BEGIN => \&RenderDhtmlBegin
839                       , NODE  => \&RenderDhtmlNode
840                       , END   => \&RenderDhtmlEnd
841
842                       # data needed by the renderer
843                       , PREVIOUS_LEVEL => -1
844                       , PREVIOUS_ADDRESS => 'ROOT'
845                       }
846               ) ;
847
848   Callbacks
849       · {RENDERER}{BEGIN} is called before the traversal of the data
850         structure starts. This allows you to setup the document (ex:: html
851         header).
852
853             my ($title, $type_address, $element, $size, $perl_address,
854             $setup) = @_ ;
855
856             1 $title
857
858             2 $type_address
859
860             3 $element
861
862             4 $perl_size
863
864             5 $perl_address
865
866             6 $setup
867
868       · {RENDERER}{NODE} is called for each node in the data structure. The
869         following arguments are passed to the callback
870
871         1 $element
872         2 $level
873         3 $is_terminal (whether a deeper structure will follow or not)
874         4 $previous_level_separator (ASCII separators before this node)
875         5 $separator (ASCII separator for this element)
876         6 $element_name
877         7 $element_value
878         8 $td_address (address of the element, Ex: C12 or H34. Unique for
879         each element)
880         9 $link_address (link to another element, may be undef)
881         10 $perl_size (size of the lement in bytes, see option
882         DISPLAY_PERL_SIZE)
883         11 $perl_address (adress (physical) of the element, see option
884         DISPLAY_PERL_ADDRESS)
885         12 $setup (the dumper's settings)
886       · {RENDERER}{END} is called after the last node has been processed.
887
888       · {RENDERER}{ ... }Arguments to the renderer can be stores within the
889         {RENDERER} hash.
890
891   Renderer modules
892       Renderers should be defined in modules under Data::TreeDumper::Renderer
893       and should define a function called GetRenderer. GetRenderer can be
894       passed whatever arguments the developer whishes. It is acceptable for
895       the modules to also export a specifc sub.
896
897         print DumpTree($s, 'Tree', Data::TreeDumper::Renderer::DHTML::GetRenderer()) ;
898         or
899         print DumpTree($s, 'Tree', GetDhtmlRenderer()) ;
900
901       If {RENDERER} is set to a scalar, Data::TreeDumper will load the
902       specified module if it exists. GetRenderer will be called without
903       arguments.
904
905         print DumpTree($s, 'Tree', RENDERER => 'DHTML') ;
906
907       If {RENDERER}{NAME} is set to a scalar, Data::TreeDumper will load the
908       specified module if it exists. GetRenderer will be called without
909       arguments. Arguments to the renderer can aither be passed to the
910       GetRenderer sub or as elements in the {RENDERER} hash.
911
912         print DumpTree($s, 'Tree', RENDERER => {NAME => 'DHTML', STYLE => \$style) ;
913

Zero width console

915       When no console exists, while redirecting to a file for example,
916       Data::TreeDumper uses the variable VIRTUAL_WIDTH instead. Default is
917       120.
918
919               VIRTUAL_WIDTH => 120 ;
920

OVERRIDE list

922       · COLOR_LEVELS
923
924       · DISPLAY_ADDRESS
925
926       · DISPLAY_PATH
927
928       · DISPLAY_PERL_SIZE
929
930       · DISPLAY_ROOT_ADDRESS
931
932       · DISPLAY_PERL_ADDRESS
933
934       · FILTER
935
936       · GLYPHS
937
938       · INDENTATION
939
940       · LEVEL_FILTERS
941
942       · MAX_DEPTH
943
944       · DISPLAY_NUMBER_OF_ELEMENTS_OVER_MAX_DEPTH
945
946       · NUMBER_LEVELS
947
948       · QUOTE_HASH_KEYS
949
950       · QUOTE_VALUES
951
952       · REPLACEMENT_LIST
953
954       · START_LEVEL
955
956       · USE_ASCII
957
958       · WRAP_WIDTH
959
960       · VIRTUAL_WIDTH
961
962       · NO_OUTPUT
963
964       · DISPLAY_OBJECT_TYPE
965
966       · DISPLAY_INHERITANCE
967
968       · DISPLAY_TIE
969
970       · DISPLAY_AUTOLOAD
971

Interface

973   Package Data (à la Data::Dumper (as is the silly naming scheme))
974       Configuration Variables
975
976         $Data::TreeDumper::Startlevel            = 1 ;
977         $Data::TreeDumper::Useascii              = 1 ;
978         $Data::TreeDumper::Maxdepth              = -1 ;
979         $Data::TreeDumper::Indentation           = '' ;
980         $Data::TreeDumper::Virtualwidth          = 120 ;
981         $Data::TreeDumper::Displayrootaddress    = 0 ;
982         $Data::TreeDumper::Displayaddress        = 1 ;
983         $Data::TreeDumper::Displaypath           = 0 ;
984         $Data::TreeDumper::Displayobjecttype     = 1 ;
985         $Data::TreeDumper::Displayinheritance    = 0 ;
986         $Data::TreeDumper::Displaytie            = 0 ;
987         $Data::TreeDumper::Displayautoload       = 0 ;
988         $Data::TreeDumper::Displayperlsize       = 0 ;
989         $Data::TreeDumper::Displayperladdress    = 0 ;
990         $Data::TreeDumper::Filter                = \&FlipEverySecondOne ;
991         $Data::TreeDumper::Levelfilters          = {1 => \&Filter_1, 5 => \&Filter_5} ;
992         $Data::TreeDumper::Numberlevels          = 0 ;
993         $Data::TreeDumper::Glyphs                = ['|  ', '|- ', '`- ', '   '] ;
994         $Data::TreeDumper::Colorlevels           = undef ;
995         $Data::TreeDumper::Nooutput              = 0 ; # generate an output
996         $Data::TreeDumper::Quotehashkeys         = 0 ;
997         $Data::TreeDumper::Displaycallerlocation = 0 ;
998
999       API
1000
1001       PrintTreeprints on STDOUT the output of DumpTree.
1002
1003       DumpTree uses the configuration variables defined above. It takes the
1004       following arguments:
1005
1006       [1] structure_to_dump
1007       [2] title, a string to prepended to the tree (optional)
1008       [3] overrides (optional)
1009
1010         print DumpTree($s, "title", MAX_DEPTH => 1) ;
1011
1012       DumpTrees uses the configuration variables defined above. It takes the
1013       following arguments
1014
1015       [1] One or more array references containing
1016         [a] structure_to_dump
1017         [b] title, a string to prepended to the tree (optional)
1018         [c] overrides (optional)
1019       [2] overrides (optional)
1020
1021         print DumpTrees
1022                 (
1023                   [$s, "title", MAX_DEPTH => 1]
1024                 , [$s2, "other_title", DISPLAY_ADDRESS => 0]
1025                 , USE_ASCII => 1
1026                 , MAX_DEPTH => 5
1027                 ) ;
1028

Bugs

1030       None that I know of in this release but plenty, lurking in the dark
1031       corners, waiting to be found.
1032

Examples

1034       Four examples files are included in the distribution.
1035
1036       usage.pl shows you how you can use Data::TreeDumper.
1037
1038       filters.pl shows you how you how to do advance filtering.
1039
1040       colors.pl shows you how you how to colorize a dump.
1041
1042       try_it.pl is meant as a scratch pad for you to try Data::TreeDumper.
1043

DEPENDENCY

1045       Text::Wrap.
1046
1047       Term::Size or Win32::Console.
1048
1049       Optional Devel::Size if you want Data::TreeDumper to show perl sizes
1050       for the tree elements.
1051

EXPORT

1053       DumpTree, DumpTrees and  CreateChainingFilter.
1054

AUTHOR

1056       Khemir Nadim ibn Hamouda. <nadim@khemir.net>
1057
1058       Thanks to Ed Avis for showing interest and pushing me to re-write the
1059       documentation.
1060
1061         Copyright (c) 2003-2010 Nadim Ibn Hamouda el Khemir. All rights
1062         reserved.  This program is free software; you can redis-
1063         tribute it and/or modify it under the same terms as Perl
1064         itself.
1065
1066       If you find any value in this module, mail me!  All hints, tips, flames
1067       and wishes are welcome at <nadim@khemir.net>.
1068

SEE ALSO

1070       Data::TreeDumper::00. Data::Dumper.
1071
1072       Data::TreeDumper::Renderer::DHTML.
1073
1074       Devel::Size::Report.Devel::Size.
1075
1076       PBS: the Perl Build System from which Data::TreeDumper was extracted.
1077

POD ERRORS

1079       Hey! The above document had some coding errors, which are explained
1080       below:
1081
1082       Around line 2454:
1083           You can't have =items (as at line 2458) unless the first thing
1084           after the =over is an =item
1085
1086       Around line 2612:
1087           Non-ASCII character seen before =encoding in '(à'. Assuming CP1252
1088
1089
1090
1091perl v5.30.0                      2019-07-26                     TreeDumper(3)
Impressum