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 => \&Data::TreeDumper::HashKeysSorter
290 FILTER_ARGUMENT => ['your', 'arguments']
291 The filter routine is passed these arguments:
293 1 - a reference to the node which is going to be displayed
295 2 - the nodes depth (this allows you to selectively display elements at
296 a certain depth)
297 3 - the path to the reference from the start of the dump.
298 4 - an array reference containing the keys to be displayed (see filter
299 chaining below) last argument can be undefined and can then be safely
300 ignored.
301 5 - the dumpers setup
302 5 - the filter arguments (see below)
303 The filter returns the node's type, an eventual new structure (see
305 below) and a list of 'keys' to display. The keys are hash keys or array
306 indexes.
307 In Perl:
309 ($tree_type, $replacement_tree, @nodes_to_display) = $your_filter->($tree, $level, $path, $nodes_to_display, $setup) ;
311 Filter are not as complicated as they sound and they are very
313 powerfull, especially when using the path argument. The path idea was
314 given to me by another module writer but I forgot whom. If this writer
315 will contact me, I will give him the proper credit.
316 Lots of examples can be found in filters.pl and I'll be glad to help if
318 you want to develop a specific filter.
319 FILTER_ARGUMENT
321 it is possible to pass arguments to your filter, passing a reference
323 allows you to modify the arguments when the filter is run (that
324 happends for each node).
325 sub SomeSub
327 {
328 my $counter = 0 ;
329 my $data_structure = {.....} ;
330 DumpTree($data_structure, 'title', FILTER => \&CountNodes, FILTER_ARGUMENT => \$counter) ;
332 print "\$counter = $counter\n" ;
334 }
335 sub CountNodes
337 {
338 my ($structure, $level, $path, $nodes_to_display, $setup, $counter) = @_ ;
339 $$counter++ ; # remember to pass references if you want them to be changed by the filter
340 return(DefaultNodesToDisplay($structure)) ;
342 }
343 Key removal
345 Entries can be removed from the display by not returning their keys.
347 my $s = {visible => '', also_visible => '', not_visible => ''} ;
349 my $OnlyVisible = sub
350 {
351 my $s = shift ;
352 if('HASH' eq ref $s)
354 {
355 return('HASH', undef, grep {! /^not_visible/} keys %$s) ;
356 }
357 return(Data::TreeDumper::DefaultNodesToDisplay($s)) ;
359 }
360 DumpTree($s, 'title', FILTER => $OnlyVisible) ;
362 Label changing
364 The label for a hash keys or an array index can be altered. This can be
366 used to add visual information to the tree dump. Instead of returning
367 the key name, return an array reference containing the key name and the
368 label you want to display. You only need to return such a reference
369 for the entries you want to change, thus a mix of scalars and array ref
370 is acceptable.
371 sub StarOnA
373 {
374 # hash entries matching /^a/i have '*' prepended
375 my $tree = shift ;
377 if('HASH' eq ref $tree)
379 {
380 my @keys_to_dump ;
381 for my $key_name (keys %$tree)
383 {
384 if($key_name =~ /^a/i)
385 {
386 $key_name = [$key_name, "* $key_name"] ;
387 }
388 push @keys_to_dump, $key_name ;
390 }
391 return ('HASH', undef, @keys_to_dump) ;
393 }
394 return (Data::TreeDumper::DefaultNodesToDisplay($tree)) ;
396 }
397 print DumpTree($s, "Entries matching /^a/i have '*' prepended", FILTER => \&StarOnA) ;
399 If you use an ANSI terminal, you can also change the color of the
401 label. This can greatly improve visual search time. See the label
402 coloring example in colors.pl.
403 Structure replacement
405 It is possible to replace the whole data structure in a filter. This
407 comes handy when you want to display a "worked" version of the
408 structure. You can even change the type of the data structure, for
409 example changing an array to a hash.
410 sub ReplaceArray
412 {
413 # replace arrays with hashes!!!
414 my $tree = shift ;
416 if('ARRAY' eq ref $tree)
418 {
419 my $multiplication = $tree->[0] * $tree->[1] ;
420 my $replacement = {MULTIPLICATION => $multiplication} ;
421 return('HASH', $replacement, keys %$replacement) ;
422 }
423 return (Data::TreeDumper::DefaultNodesToDisplay($tree)) ;
425 }
426 print DumpTree($s, 'replace arrays with hashes!', FILTER => \&ReplaceArray) ;
428 Here is a real life example. Tree::Simple
430 (http://search.cpan.org/dist/Tree-Simple/
431 <http://search.cpan.org/dist/Tree-Simple/>) allows one to build tree
432 structures. The child nodes are not directly in the parent object
433 (hash). Here is an unfiltered dump of a tree with seven nodes:
434 Tree::Simple through Data::TreeDumper
436 |- _children
437 | |- 0
438 | | |- _children
439 | | | `- 0
440 | | | |- _children
441 | | | |- _depth = 1
442 | | | |- _node = 1.1
443 | | | `- _parent
444 | | |- _depth = 0
445 | | |- _node = 1
446 | | `- _parent
447 | |- 1
448 | | |- _children
449 | | | |- 0
450 | | | | |- _children
451 | | | | |- _depth = 1
452 | | | | |- _node = 2.1
453 | | | | `- _parent
454 | | | |- 1
455 | | | | |- _children
456 | | | | |- _depth = 1
457 | | | | |- _node = 2.1a
458 | | | | `- _parent
459 | | | `- 2
460 | | | |- _children
461 | | | |- _depth = 1
462 | | | |- _node = 2.2
463 | | | `- _parent
464 | | |- _depth = 0
465 | | |- _node = 2
466 | | `- _parent
467 | `- 2
468 | |- _children
469 | |- _depth = 0
470 | |- _node = 3
471 | `- _parent
472 |- _depth = -1
473 |- _node = 0
474 `- _parent = root
475 This is nice for the developer but not for a user wanting to oversee
477 the node hierarchy. One of the possible filters would be:
478 FILTER => sub
480 {
481 my $s = shift ;
482 if('Tree::Simple' eq ref $s)
484 {
485 my $counter = 0 ;
486 return
488 (
489 'ARRAY'
490 , $s->{_children}
491 , map{[$counter++, $_->{_node}]} @{$s->{_children}} # index generation
492 ) ;
493 }
494 return(Data::TreeDumper::DefaultNodesToDisplay($s)) ;
496 }
497 Which would give this much more readable output:
499 Tree::Simple through Data::TreeDumper2
501 |- 1
502 | `- 1.1
503 |- 2
504 | |- 2.1
505 | |- 2.1a
506 | `- 2.2
507 `- 3
508 What about counting the children nodes? The index generating code
510 becomes:
511 map{[$counter++, "$_->{_node} [" . @{$_->{_children}} . "]"]} @{$s->{_children}}
513 Tree::Simple through Data::TreeDumper4
515 |- 1 [1]
516 | `- 1.1 [0]
517 |- 2 [3]
518 | |- 2.1 [0]
519 | |- 2.1a [0]
520 | `- 2.2 [0]
521 `- 3 [0]
522 Filter chaining
524 It is possible to chain filters. CreateChainingFilter takes a list of
526 filtering sub references. The filters must properly handle the third
527 parameter passed to them.
528 Suppose you want to chain a filter that adds a star before each hash
530 key label, with a filter that removes all (original) keys that match
531 /^a/i.
532 sub AddStar
534 {
535 my $s = shift ;
536 my $level = shift ;
537 my $path = shift ;
538 my $keys = shift ;
539 if('HASH' eq ref $s)
541 {
542 $keys = [keys %$s] unless defined $keys ;
543 my @new_keys ;
545 for (@$keys)
547 {
548 if('' eq ref $_)
549 {
550 push @new_keys, [$_, "* $_"] ;
551 }
552 else
553 {
554 # another filter has changed the label
555 push @new_keys, [$_->[0], "* $_->[1]"] ;
556 }
557 }
558 return('HASH', undef, @new_keys) ;
560 }
561 return(Data::TreeDumper::DefaultNodesToDisplay($s)) ;
563 } ;
564 sub RemoveA
566 {
567 my $s = shift ;
568 my $level = shift ;
569 my $path = shift ;
570 my $keys = shift ;
571 if('HASH' eq ref $s)
573 {
574 $keys = [keys %$s] unless defined $keys ;
575 my @new_keys ;
576 for (@$keys)
578 {
579 if('' eq ref $_)
580 {
581 push @new_keys, $_ unless /^a/i ;
582 }
583 else
584 {
585 # another filter has changed the label
586 push @new_keys, $_ unless $_->[0] =~ /^a/i ;
587 }
588 }
589 return('HASH', undef, @new_keys) ;
591 }
592 return(Data::TreeDumper::DefaultNodesToDisplay($s)) ;
594 } ;
595 DumpTree($s, 'Chained filters', FILTER => CreateChainingFilter(\&AddStar, \&RemoveA)) ;
597 level Filters
599 It is possible to define one filter for a specific level. If a filter
600 for a specific level exists it is used instead of the global filter.
601 LEVEL_FILTERS => {1 => \&FilterForLevelOne, 5 => \&FilterForLevelFive
603 ... } ;
604 Type Filters
606 You can define filters for specific types of references. This filter
607 type has the highest priority.
608 here's a very simple filter that will display the specified keys for
610 the types
611 print DumpTree
613 (
614 $data,
615 'title',
616 TYPE_FILTERS =>
617 {
618 'Config::Hierarchical' => sub {'HASH', undef, qw(CATEGORIES) },
619 'PBS2::Node' => sub {'HASH', undef, qw(CONFIG DEPENDENCIES MATCH) },,
620 }
621 ) ;
622 Using filters as iterators
624 You can iterate through your data structures and display data yourself,
625 manipulate the data structure, or do a search. While iterating through
626 the data structure, you can prune arbitrary branches to speedup
627 processing.
628 # this example counts the nodes in a tree (hash based)
630 # a node is counted if it has a '__NAME' key
631 # any field that starts with '__' is considered rivate and we prune so we don't recurse in it
632 # anything that is not a hash (the part of the tree that interests us in this case) is pruned
633 my $number_of_nodes_in_the_dependency_tree = 0 ;
635 my $node_counter =
636 sub
637 {
638 my $tree = shift ;
639 if('HASH' eq ref $tree && exists $tree->{__NAME})
640 {
641 $number_of_nodes_in_the_dependency_tree++ if($tree->{__NAME} !~ /^__/) ;
642 return('HASH', $tree, grep {! /^__/} keys %$tree) ; # prune to run faster
644 }
645 else
646 {
647 return('SCALAR', 1) ; # prune
648 }
649 } ;
650 DumpTree($dependency_tree, '', NO_OUTPUT => 1, FILTER => $node_counter) ;
652 See the example under FILTER which passes arguments through
654 Data::TreeDumper instead for using a closure as above
655 Start level
657 This configuration option controls whether the tree trunk is displayed
658 or not.
659 START_LEVEL => 1:
661 $tree:
663 |- A [H1]
664 | |- a [H2]
665 | |- bbbbbb = CODE(0x8139fa0) [C3]
666 | |- c123 [C4 -> C3]
667 | `- d [R5]
668 | `- REF(0x8139fb8) [R5 -> C3]
669 |- ARRAY [A6]
670 | |- 0 [S7] = element_1
671 | |- 1 [S8] = element_2
672 START_LEVEL => 0:
674 $tree:
676 A [H1]
677 |- a [H2]
678 |- bbbbbb = CODE(0x8139fa0) [C3]
679 |- c123 [C4 -> C3]
680 `- d [R5]
681 `- REF(0x8139fb8) [R5 -> C3]
682 ARRAY [A6]
683 |- 0 [S7] = element_1
684 |- 1 [S8] = element_2
685 ASCII vs ANSI
687 You can direct Data:TreeDumper to output ANSI codes instead of ASCII
688 characters. The display will be much nicer but takes slightly longer
689 (not significant for small data structures).
690 USE_ASCII => 0 # will use ANSI codes instead
692 Display number of elements
694 DISPLAY_NUMBER_OF_ELEMENTS => 1
695 When set, the number of elements of every array and hash is displayed
697 (not for objects based on hashes and arrays).
698 Maximum depth of the dump
700 Controls the depth beyond which which we don't recurse into a
701 structure. Default is -1, which means there is no maximum depth. This
702 is useful to limit the amount of data displayed.
703 MAX_DEPTH => 1
705 Number of elements not displayed because of maximum depth limit
707 Data::TreDumper will display the number of elements a hash or array has
708 but that can not be displayed because of the maximum depth setting.
709 DISPLAY_NUMBER_OF_ELEMENTS_OVER_MAX_DEPTH => 1
711 Indentation
713 Every line of the tree dump will be appended with the value of
714 INDENTATION.
715 INDENTATION => ' ' ;
717
719 You can change the glyphs used by Data::TreeDumper.
720 DumpTree(\$s, 's', , GLYPHS => ['. ', '. ', '. ', '. ']) ;
722 # output
724 s
725 . REF(0x813da3c) [H1]
726 . . A [H2]
727 . . . a [H3]
728 . . . b [H4]
729 . . . . a = 0 [S5]
730 . . . . b = 1 [S6]
731 . . . . c [H7]
732 . . . . . a = 1 [S8]
733 Four glyphs must be given. They replace the standard glyphs ['| ', '|-
735 ', '`- ', ' ']. It is also possible to set the package variable
736 $Data::TreeDumper::Glyphs. USE_ASCII should be set, which it is by
737 default.
738
740 Data:TreeDumper can prepend the level of the current line to the tree
741 glyphs. This can be very useful when searching in tree dump either
742 visually or with a pager.
743 NUMBER_LEVELS => 2
745 NUMBER_LEVELS => \&NumberingSub
746 NUMBER_LEVELS can be assigned a number or a sub reference. When
748 assigned a number, Data::TreeDumper will use that value to define the
749 width of the field where the level is displayed. For more control, you
750 can define a sub that returns a string to be displayed on the left side
751 of the tree glyphs. The example below tags all the nodes whose level is
752 zero.
753 print DumpTree($s, "Level numbering", NUMBER_LEVELS => 2) ;
755 sub GetLevelTagger
757 {
758 my $level_to_tag = shift ;
759 sub
761 {
762 my ($element, $level, $setup) = @_ ;
763 my $tag = "Level $level_to_tag => ";
765 if($level == 0)
767 {
768 return($tag) ;
769 }
770 else
771 {
772 return(' ' x length($tag)) ;
773 }
774 } ;
775 }
776 print DumpTree($s, "Level tagging", NUMBER_LEVELS => GetLevelTagger(0)) ;
778
780 Another way to enhance the output for easier searching is to colorize
781 it. Data::TreeDumper can colorize the glyph elements or whole levels.
782 If your terminal supports ANSI codes, using Term::ANSIColors and
783 Data::TreeDumper together can greatly ease the reading of large dumps.
784 See the examples in 'color.pl'.
785 COLOR_LEVELS => [\@color_codes, $reset_code]
787 When passed an array reference, the first element is an array
789 containing coloring codes. The codes are indexed with the node level
790 modulo the size of the array. The second element is used to reset the
791 color after the glyph is displayed. If the second element is an empty
792 string, the glyph and the rest of the level is colorized.
793 COLOR_LEVELS => \&LevelColoringSub
795 If COLOR_LEVEL is assigned a sub, the sub is called for each glyph
797 element. It is passed the following elements:
798 1 - the nodes depth (this allows you to selectively display elements at
800 a certain depth)
801 It should return a coloring code and a reset code. If you return an
803 empty string for the reset code, the whole node is displayed using the
804 last glyph element color.
805 If level numbering is on, it is also colorized.
807
809 Data::TreeDumper uses the Text::Wrap module to wrap your data to fit
810 your display. Entries can be wrapped multiple times so they snuggly fit
811 your screen.
812 | | |- 1 [S21] = 1
814 | | `- 2 [S22] = 2
815 | `- 3 [OH23 -> R17]
816 |- ARRAY_ZERO [A24]
817 |- B [S25] = scalar
818 |- Long_name Long_name Long_name Long_name Long_name Long_name
819 | Long_name Long_name Long_name Long_name Long_name Long_name
820 | Long_name Long_name Long_name Long_name Long_name [S26] = 0
821 You can direct DTD to not wrap your text by setting NO_WRAP = 1>.
823 WRAP_WIDTH
825 if this option is set, Data::TreeDumper will use it instead for the
826 console width.
827
829 Data::TreeDumper has a plug-in interface for other rendering formats.
830 The renderer callbacks are set by overriding the native renderer.
831 Thanks to Stevan Little author of Tree::Simple::View for getting
832 Data::TreeDumper on this track. Check
833 Data::TreeDumper::Renderer::DHTML.
834 DumpTree
836 (
837 $s
838 , 'Tree'
839 , RENDERER =>
840 {
841 BEGIN => \&RenderDhtmlBegin
842 , NODE => \&RenderDhtmlNode
843 , END => \&RenderDhtmlEnd
844 # data needed by the renderer
846 , PREVIOUS_LEVEL => -1
847 , PREVIOUS_ADDRESS => 'ROOT'
848 }
849 ) ;
850 Callbacks
852 · {RENDERER}{BEGIN} is called before the traversal of the data
853 structure starts. This allows you to setup the document (ex:: html
854 header).
855 1 $title
857 2 $type_address
858 3 $element
859 4 $perl_size
860 5 $perl_address
861 6 $setup
862 · {RENDERER}{NODE} is called for each node in the data structure. The
863 following arguments are passed to the callback
864 1 $element
866 2 $level
867 3 $is_terminal (whether a deeper structure will follow or not)
868 4 $previous_level_separator (ASCII separators before this node)
869 5 $separator (ASCII separator for this element)
870 6 $element_name
871 7 $element_value
872 8 $td_address (address of the element, Ex: C12 or H34. Unique for
873 each element)
874 9 $link_address (link to another element, may be undef)
875 10 $perl_size (size of the lement in bytes, see option
876 DISPLAY_PERL_SIZE)
877 11 $perl_address (adress (physical) of the element, see option
878 DISPLAY_PERL_ADDRESS)
879 12 $setup (the dumper's settings)
880 · {RENDERER}{END} is called after the last node has been processed.
881 · {RENDERER}{ ... }Arguments to the renderer can be stores within the
883 {RENDERER} hash.
884 Renderer modules
886 Renderers should be defined in modules under Data::TreeDumper::Renderer
887 and should define a function called GetRenderer. GetRenderer can be
888 passed whatever arguments the developer whishes. It is acceptable for
889 the modules to also export a specifc sub.
890 print DumpTree($s, 'Tree', Data::TreeDumper::Renderer::DHTML::GetRenderer()) ;
892 or
893 print DumpTree($s, 'Tree', GetDhtmlRenderer()) ;
894 If {RENDERER} is set to a scalar, Data::TreeDumper will load the
896 specified module if it exists. GetRenderer will be called without
897 arguments.
898 print DumpTree($s, 'Tree', RENDERER => 'DHTML') ;
900 If {RENDERER}{NAME} is set to a scalar, Data::TreeDumper will load the
902 specified module if it exists. GetRenderer will be called without
903 arguments. Arguments to the renderer can aither be passed to the
904 GetRenderer sub or as elements in the {RENDERER} hash.
905 print DumpTree($s, 'Tree', RENDERER => {NAME => 'DHTML', STYLE => \$style) ;
907
909 When no console exists, while redirecting to a file for example,
910 Data::TreeDumper uses the variable VIRTUAL_WIDTH instead. Default is
911 120.
912 VIRTUAL_WIDTH => 120 ;
914
916 · COLOR_LEVELS
917 · DISPLAY_ADDRESS
919 · DISPLAY_PATH
921 · DISPLAY_PERL_SIZE
923 · DISPLAY_ROOT_ADDRESS
925 · DISPLAY_PERL_ADDRESS
927 · FILTER
929 · GLYPHS
931 · INDENTATION
933 · LEVEL_FILTERS
935 · MAX_DEPTH
937 · DISPLAY_NUMBER_OF_ELEMENTS_OVER_MAX_DEPTH
939 · NUMBER_LEVELS
941 · QUOTE_HASH_KEYS
943 · QUOTE_VALUES
945 · REPLACEMENT_LIST
947 · START_LEVEL
949 · USE_ASCII
951 · WRAP_WIDTH
953 · VIRTUAL_WIDTH
955 · NO_OUTPUT
957 · DISPLAY_OBJECT_TYPE
959 · DISPLAY_INHERITANCE
961 · DISPLAY_TIE
963 · DISPLAY_AUTOLOAD
965
967 Package Data (a la Data::Dumper (as is the silly naming scheme))
968 Configuration Variables
969 $Data::TreeDumper::Startlevel = 1 ;
971 $Data::TreeDumper::Useascii = 1 ;
972 $Data::TreeDumper::Maxdepth = -1 ;
973 $Data::TreeDumper::Indentation = '' ;
974 $Data::TreeDumper::Virtualwidth = 120 ;
975 $Data::TreeDumper::Displayrootaddress = 0 ;
976 $Data::TreeDumper::Displayaddress = 1 ;
977 $Data::TreeDumper::Displaypath = 0 ;
978 $Data::TreeDumper::Displayobjecttype = 1 ;
979 $Data::TreeDumper::Displayinheritance = 0 ;
980 $Data::TreeDumper::Displaytie = 0 ;
981 $Data::TreeDumper::Displayautoload = 0 ;
982 $Data::TreeDumper::Displayperlsize = 0 ;
983 $Data::TreeDumper::Displayperladdress = 0 ;
984 $Data::TreeDumper::Filter = \&FlipEverySecondOne ;
985 $Data::TreeDumper::Levelfilters = {1 => \&Filter_1, 5 => \&Filter_5} ;
986 $Data::TreeDumper::Numberlevels = 0 ;
987 $Data::TreeDumper::Glyphs = ['| ', '|- ', '`- ', ' '] ;
988 $Data::TreeDumper::Colorlevels = undef ;
989 $Data::TreeDumper::Nooutput = 0 ; # generate an output
990 $Data::TreeDumper::Quotehashkeys = 0 ;
991 $Data::TreeDumper::Displaycallerlocation = 0 ;
992 API
994 PrintTreeprints on STDOUT the output of DumpTree.
996 DumpTree uses the configuration variables defined above. It takes the
998 following arguments:
999 [1] structure_to_dump
1001 [2] title, a string to prepended to the tree (optional)
1002 [3] overrides (optional)
1003 print DumpTree($s, "title", MAX_DEPTH => 1) ;
1005 DumpTrees uses the configuration variables defined above. It takes the
1007 following arguments
1008 [1] One or more array references containing
1010 [a] structure_to_dump
1011 [b] title, a string to prepended to the tree (optional)
1012 [c] overrides (optional)
1013 [2] overrides (optional)
1014 print DumpTrees
1016 (
1017 [$s, "title", MAX_DEPTH => 1]
1018 , [$s2, "other_title", DISPLAY_ADDRESS => 0]
1019 , USE_ASCII => 1
1020 , MAX_DEPTH => 5
1021 ) ;
1022
1024 None that I know of in this release but plenty, lurking in the dark
1025 corners, waiting to be found.
1026
1028 Four examples files are included in the distribution.
1029 usage.pl shows you how you can use Data::TreeDumper.
1031 filters.pl shows you how you how to do advance filtering.
1033 colors.pl shows you how you how to colorize a dump.
1035 try_it.pl is meant as a scratch pad for you to try Data::TreeDumper.
1037
1039 Text::Wrap.
1040 Term::Size or Win32::Console.
1042 Optional Devel::Size if you want Data::TreeDumper to show perl sizes
1044 for the tree elements.
1045
1047 DumpTree, DumpTrees and CreateChainingFilter.
1048
1050 Khemir Nadim ibn Hamouda. <nadim@khemir.net>
1051 Thanks to Ed Avis for showing interest and pushing me to re-write the
1053 documentation.
1054 Copyright (c) 2003-2006 Nadim Ibn Hamouda el Khemir. All rights
1056 reserved. This program is free software; you can redis-
1057 tribute it and/or modify it under the same terms as Perl
1058 itself.
1059 If you find any value in this module, mail me! All hints, tips, flames
1061 and wishes are welcome at <nadim@khemir.net>.
1062
1064 Data::TreeDumper::00. Data::Dumper.
1065 Data::TreeDumper::Renderer::DHTML.
1067 Devel::Size::Report.Devel::Size.
1069 PBS: the Perl Build System from which Data::TreeDumper was extracted.
1071
1073 Hey! The above document had some coding errors, which are explained
1074 below:
1075 Around line 2501:
1077 =over should be: '=over' or '=over positive_number'
1078perl v5.12.0 2008-11-01 TreeDumper(3)