1TreeDumper(3) User Contributed Perl Documentation TreeDumper(3)
2
6 Data::TreeDumper - Improved replacement for Data::Dumper. Powerful
7 filtering capability.
8
10 use Data::TreeDumper ;
11 my $sub = sub {} ;
13 my $s =
15 {
16 A =>
17 {
18 a =>
19 {
20 }
21 , bbbbbb => $sub
22 , c123 => $sub
23 , d => \$sub
24 }
25 , C =>
27 {
28 b =>
29 {
30 a =>
31 {
32 a =>
33 {
34 }
35 , b => sub
37 {
38 }
39 , c => 42
40 }
41 }
43 }
44 , ARRAY => [qw(elment_1 element_2 element_3)]
45 } ;
46 #-------------------------------------------------------------------
49 # package setup data
50 #-------------------------------------------------------------------
51 $Data::TreeDumper::Useascii = 0 ;
53 $Data::TreeDumper::Maxdepth = 2 ;
54 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
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
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 Data::TreeDumper also dumps data in a tree-like fashion but hopefully
92 in a format more easily understood.
93 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 | |- bbbbbb = CODE(0x8139fa0) [C3]
100 | |- c123 [C4 -> C3]
101 | `- d [R5]
102 | `- REF(0x8139fb8) [R5 -> C3]
103 Address
105 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 ex: c123 [C4 -> C3]
112 ^ ^
113 | | address of the data refered to
114 |
115 | current element address
116 Types
118 S: Scalar, H: Hash, A: Array, C: Code,
120 R: Reference, RS: Scalar reference. Ox: Object, where x is the object
122 undelying type
123 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 |- A [S10] = string
129 |- EMPTY_ARRAY (no elements) [A11]
130 |- B [S12] = 123
131
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 ex:
139 $Data::TreeDumper::Maxdepth = 2 ;
140 # 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 # maximum depth is 2
146 print DumpTree($s, 'title') ;
147 $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 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 print Data::TreeDumper::DumpTree($s, "Using package data") ;
161 print Data::TreeDumper::DumpTree($s, "Not Using package data", NO_PACKAGE_SETUP => 1) ;
162 DISPLAY_ROOT_ADDRESS
164 By default, Data::TreeDumper doesn't display the address of the root.
165 DISPLAY_ROOT_ADDRESS => 1 # show the root address
167 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 DISPLAY_ADDRESS => 0
174 DISPLAY_PATH
176 Add the path of the element to the its address.
177 DISPLAY_PATH => 1
179 ex: '- CopyOfARRAY [A39 -> A18 /{'ARRAY'}]
181 DISPLAY_OBJECT_TYPE
183 Data::TreeDumper displays the package in which an object is blessed.
184 You can suppress this display by using:
185 DISPLAY_OBJECT_TYPE => 0
187 DISPLAY_INHERITANCE
189 Data::TreeDumper will display the inheritance hierarchy for the object:
190 |- object = blessed in 'SuperObject' <- Potatoe [OH55]
192 | `- Data = 0 [S56]
193 DISPLAY_AUTOLOAD
195 if set, Data::TreeDumper will tag the object type with '[A]' if the
196 package has an AUTOLOAD function.
197 |- object_with_autoload = blessed in '[A]SuperObjectWithAutoload' <- Potatoe <- [A] Vegetable [O58]
199 | `- Data = 0 [S56]
200 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 |- tied_hash (tied to 'TiedHash') [H57]
207 | `- x = 1 [S58]
208 |- tied_hash_object = (tied to 'TiedHash') blessed in 'SuperObject' <- [A]Potatoe <- Vegetable [O59]
210 | |- m1 = 1 [S60]
211 | `- m2 = 2 [S61]
212 PERL DATA
214 Setting one of the options below will show internal perl data:
215 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 DISPLAY_PERL_SIZE
225 Setting this option will show the size of the memory allocated for each
227 element in the tree within angle brackets.
228 DISPLAY_PERL_SIZE => 1
230 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 DISPLAY_PERL_ADDRESS
236 Setting this option will show the perl-address of the dumped data.
238 DISPLAY_PERL_ADDRESS => 1
240 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 # 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 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 DumpTree(\$s, 'some data:', QUOTE_HASH_KEYS => 1) ;
259 # output
261 some data:
262 `- REF(0x813da3c) [H1]
263 |- 'A' [H2]
264 | |- 'a' [H3]
265 | |- 'b' [H4]
266 | | |- 'a' = 0 [S5]
267 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 DumpTree(\$s, 'Cells:', QUOTE_VALUES=> 1) ;
273 NO_NO_ELEMENTS
275 If this option is set, Data::TreeDumper will not add 'no elements' to
276 empty hashes and arrays
277 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 Filters
285 Data::TreeDumper can sort the tree nodes with a user defined
286 subroutine. By default, hash keys are sorted.
287 FILTER => \&ReverseSort
289 FILTER_ARGUMENT => ['your', 'arguments']
290 The filter routine is passed these arguments:
292 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 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 In Perl:
307 ($tree_type, $replacement_tree, @nodes_to_display) = $your_filter->($tree, $level, $path, $nodes_to_display, $setup) ;
309 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 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 FILTER_ARGUMENT
319 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 sub SomeSub
325 {
326 my $counter = 0 ;
327 my $data_structure = {.....} ;
328 DumpTree($data_structure, 'title', FILTER => \&CountNodes, FILTER_ARGUMENT => \$counter) ;
330 print "\$counter = $counter\n" ;
332 }
333 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 return(DefaultNodesToDisplay($structure)) ;
340 }
341 Key removal
343 Entries can be removed from the display by not returning their keys.
345 my $s = {visible => '', also_visible => '', not_visible => ''} ;
347 my $OnlyVisible = sub
348 {
349 my $s = shift ;
350 if('HASH' eq ref $s)
352 {
353 return('HASH', undef, grep {! /^not_visible/} keys %$s) ;
354 }
355 return(Data::TreeDumper::DefaultNodesToDisplay($s)) ;
357 }
358 DumpTree($s, 'title', FILTER => $OnlyVisible) ;
360 Label changing
362 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 sub StarOnA
371 {
372 # hash entries matching /^a/i have '*' prepended
373 my $tree = shift ;
375 if('HASH' eq ref $tree)
377 {
378 my @keys_to_dump ;
379 for my $key_name (keys %$tree)
381 {
382 if($key_name =~ /^a/i)
383 {
384 $key_name = [$key_name, "* $key_name"] ;
385 }
386 push @keys_to_dump, $key_name ;
388 }
389 return ('HASH', undef, @keys_to_dump) ;
391 }
392 return (Data::TreeDumper::DefaultNodesToDisplay($tree)) ;
394 }
395 print DumpTree($s, "Entries matching /^a/i have '*' prepended", FILTER => \&StarOnA) ;
397 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 Structure replacement
403 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 sub ReplaceArray
410 {
411 # replace arrays with hashes!!!
412 my $tree = shift ;
414 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 return (Data::TreeDumper::DefaultNodesToDisplay($tree)) ;
423 }
424 print DumpTree($s, 'replace arrays with hashes!', FILTER => \&ReplaceArray) ;
426 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 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 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 FILTER => sub
477 {
478 my $s = shift ;
479 if('Tree::Simple' eq ref $s)
481 {
482 my $counter = 0 ;
483 return
485 (
486 'ARRAY'
487 , $s->{_children}
488 , map{[$counter++, $_->{_node}]} @{$s->{_children}} # index generation
489 ) ;
490 }
491 return(Data::TreeDumper::DefaultNodesToDisplay($s)) ;
493 }
494 Which would give this much more readable output:
496 Tree::Simple through Data::TreeDumper2
498 |- 1
499 | `- 1.1
500 |- 2
501 | |- 2.1
502 | |- 2.1a
503 | `- 2.2
504 `- 3
505 What about counting the children nodes? The index generating code
507 becomes:
508 map{[$counter++, "$_->{_node} [" . @{$_->{_children}} . "]"]} @{$s->{_children}}
510 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 Filter chaining
521 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 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 sub AddStar
531 {
532 my $s = shift ;
533 my $level = shift ;
534 my $path = shift ;
535 my $keys = shift ;
536 if('HASH' eq ref $s)
538 {
539 $keys = [keys %$s] unless defined $keys ;
540 my @new_keys ;
542 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 return('HASH', undef, @new_keys) ;
557 }
558 return(Data::TreeDumper::DefaultNodesToDisplay($s)) ;
560 } ;
561 sub RemoveA
563 {
564 my $s = shift ;
565 my $level = shift ;
566 my $path = shift ;
567 my $keys = shift ;
568 if('HASH' eq ref $s)
570 {
571 $keys = [keys %$s] unless defined $keys ;
572 my @new_keys ;
573 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 return('HASH', undef, @new_keys) ;
588 }
589 return(Data::TreeDumper::DefaultNodesToDisplay($s)) ;
591 } ;
592 DumpTree($s, 'Chained filters', FILTER => CreateChainingFilter(\&AddStar, \&RemoveA)) ;
594 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 LEVEL_FILTERS => {1 => \&FilterForLevelOne, 5 => \&FilterForLevelFive
600 ... } ;
601 Type Filters
603 You can define filters for specific types of references. This filter
604 type has the highest priority.
605 here's a very simple filter that will display the specified keys for
607 the types
608 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 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 # 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 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 return('HASH', $tree, grep {! /^__/} keys %$tree) ; # prune to run faster
641 }
642 else
643 {
644 return('SCALAR', 1) ; # prune
645 }
646 } ;
647 DumpTree($dependency_tree, '', NO_OUTPUT => 1, FILTER => $node_counter) ;
649 See the example under FILTER which passes arguments through
651 Data::TreeDumper instead for using a closure as above
652 Start level
654 This configuration option controls whether the tree trunk is displayed
655 or not.
656 START_LEVEL => 1:
658 $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 START_LEVEL => 0:
671 $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 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 USE_ASCII => 0 # will use ANSI codes instead
689 Display number of elements
691 DISPLAY_NUMBER_OF_ELEMENTS => 1
692 When set, the number of elements of every array and hash is displayed
694 (not for objects based on hashes and arrays).
695 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 MAX_DEPTH => 1
702 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 DISPLAY_NUMBER_OF_ELEMENTS_OVER_MAX_DEPTH => 1
708 Indentation
710 Every line of the tree dump will be appended with the value of
711 INDENTATION.
712 INDENTATION => ' ' ;
714
716 You can change the glyphs used by Data::TreeDumper.
717 DumpTree(\$s, 's', , GLYPHS => ['. ', '. ', '. ', '. ']) ;
719 # 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 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
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 NUMBER_LEVELS => 2
742 NUMBER_LEVELS => \&NumberingSub
743 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 print DumpTree($s, "Level numbering", NUMBER_LEVELS => 2) ;
752 sub GetLevelTagger
754 {
755 my $level_to_tag = shift ;
756 sub
758 {
759 my ($element, $level, $setup) = @_ ;
760 my $tag = "Level $level_to_tag => ";
762 if($level == 0)
764 {
765 return($tag) ;
766 }
767 else
768 {
769 return(' ' x length($tag)) ;
770 }
771 } ;
772 }
773 print DumpTree($s, "Level tagging", NUMBER_LEVELS => GetLevelTagger(0)) ;
775
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 COLOR_LEVELS => [\@color_codes, $reset_code]
784 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 COLOR_LEVELS => \&LevelColoringSub
792 If COLOR_LEVEL is assigned a sub, the sub is called for each glyph
794 element. It is passed the following elements:
795 1 - the nodes depth (this allows you to selectively display elements at
797 a certain depth)
798 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 If level numbering is on, it is also colorized.
804
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 | | |- 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 You can direct DTD to not wrap your text by setting NO_WRAP = 1>.
820 WRAP_WIDTH
822 if this option is set, Data::TreeDumper will use it instead for the
823 console width.
824
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 DumpTree
833 (
834 $s
835 , 'Tree'
836 , RENDERER =>
837 {
838 BEGIN => \&RenderDhtmlBegin
839 , NODE => \&RenderDhtmlNode
840 , END => \&RenderDhtmlEnd
841 # data needed by the renderer
843 , PREVIOUS_LEVEL => -1
844 , PREVIOUS_ADDRESS => 'ROOT'
845 }
846 ) ;
847 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 my ($title, $type_address, $element, $size, $perl_address,
854 $setup) = @_ ;
855 1 $title
857 2 $type_address
859 3 $element
861 4 $perl_size
863 5 $perl_address
865 6 $setup
867 · {RENDERER}{NODE} is called for each node in the data structure. The
869 following arguments are passed to the callback
870 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 · {RENDERER}{ ... }Arguments to the renderer can be stores within the
889 {RENDERER} hash.
890 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 print DumpTree($s, 'Tree', Data::TreeDumper::Renderer::DHTML::GetRenderer()) ;
898 or
899 print DumpTree($s, 'Tree', GetDhtmlRenderer()) ;
900 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 print DumpTree($s, 'Tree', RENDERER => 'DHTML') ;
906 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 print DumpTree($s, 'Tree', RENDERER => {NAME => 'DHTML', STYLE => \$style) ;
913
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 VIRTUAL_WIDTH => 120 ;
920
922 · COLOR_LEVELS
923 · DISPLAY_ADDRESS
925 · DISPLAY_PATH
927 · DISPLAY_PERL_SIZE
929 · DISPLAY_ROOT_ADDRESS
931 · DISPLAY_PERL_ADDRESS
933 · FILTER
935 · GLYPHS
937 · INDENTATION
939 · LEVEL_FILTERS
941 · MAX_DEPTH
943 · DISPLAY_NUMBER_OF_ELEMENTS_OVER_MAX_DEPTH
945 · NUMBER_LEVELS
947 · QUOTE_HASH_KEYS
949 · QUOTE_VALUES
951 · REPLACEMENT_LIST
953 · START_LEVEL
955 · USE_ASCII
957 · WRAP_WIDTH
959 · VIRTUAL_WIDTH
961 · NO_OUTPUT
963 · DISPLAY_OBJECT_TYPE
965 · DISPLAY_INHERITANCE
967 · DISPLAY_TIE
969 · DISPLAY_AUTOLOAD
971
973 Package Data (à la Data::Dumper (as is the silly naming scheme))
974 Configuration Variables
975 $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 API
1000 PrintTreeprints on STDOUT the output of DumpTree.
1002 DumpTree uses the configuration variables defined above. It takes the
1004 following arguments:
1005 [1] structure_to_dump
1007 [2] title, a string to prepended to the tree (optional)
1008 [3] overrides (optional)
1009 print DumpTree($s, "title", MAX_DEPTH => 1) ;
1011 DumpTrees uses the configuration variables defined above. It takes the
1013 following arguments
1014 [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 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
1030 None that I know of in this release but plenty, lurking in the dark
1031 corners, waiting to be found.
1032
1034 Four examples files are included in the distribution.
1035 usage.pl shows you how you can use Data::TreeDumper.
1037 filters.pl shows you how you how to do advance filtering.
1039 colors.pl shows you how you how to colorize a dump.
1041 try_it.pl is meant as a scratch pad for you to try Data::TreeDumper.
1043
1045 Text::Wrap.
1046 Term::Size or Win32::Console.
1048 Optional Devel::Size if you want Data::TreeDumper to show perl sizes
1050 for the tree elements.
1051
1053 DumpTree, DumpTrees and CreateChainingFilter.
1054
1056 Khemir Nadim ibn Hamouda. <nadim@khemir.net>
1057 Thanks to Ed Avis for showing interest and pushing me to re-write the
1059 documentation.
1060 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 If you find any value in this module, mail me! All hints, tips, flames
1067 and wishes are welcome at <nadim@khemir.net>.
1068
1070 Data::TreeDumper::00. Data::Dumper.
1071 Data::TreeDumper::Renderer::DHTML.
1073 Devel::Size::Report.Devel::Size.
1075 PBS: the Perl Build System from which Data::TreeDumper was extracted.
1077
1079 Hey! The above document had some coding errors, which are explained
1080 below:
1081 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 Around line 2612:
1087 Non-ASCII character seen before =encoding in '(à'. Assuming CP1252
1088perl v5.30.0 2019-07-26 TreeDumper(3)