TreeDumper(3) User Contributed Perl Documentation TreeDumper(3)NAMEData::TreeDumper - Improved replacement for Data::Dumper. Powerful
filtering capability.
SYNOPSIS
use Data::TreeDumper ;
my $sub = sub {} ;
my $s =
{
A =>
{
a =>
{
}
, bbbbbb => $sub
, c123 => $sub
, d => \$sub
}
, C =>
{
b =>
{
a =>
{
a =>
{
}
, b => sub
{
}
, c => 42
}
}
}
, ARRAY => [qw(elment_1 element_2 element_3)]
} ;
#-------------------------------------------------------------------
# package setup data
#-------------------------------------------------------------------
$Data::TreeDumper::Useascii = 0 ;
$Data::TreeDumper::Maxdepth = 2 ;
print DumpTree($s, 'title') ;
print DumpTree($s, 'title', MAX_DEPTH => 1) ;
print DumpTrees
(
[$s, "title", MAX_DEPTH => 1]
, [$s2, "other_title", DISPLAY_ADDRESS => 0]
, USE_ASCII => 1
, MAX_DEPTH => 5
) ;
Output
title:
|- A [H1]
| |- a [H2]
| |- bbbbbb = CODE(0x8139fa0) [C3]
| |- c123 [C4 -> C3]
| `- d [R5]
| `- REF(0x8139fb8) [R5 -> C3]
|- ARRAY [A6]
| |- 0 [S7] = elment_1
| |- 1 [S8] = element_2
| `- 2 [S9] = element_3
`- C [H10]
`- b [H11]
`- a [H12]
|- a [H13]
|- b = CODE(0x81ab130) [C14]
`- c [S15] = 42
DESCRIPTION
Data::Dumper and other modules do a great job of dumping data
structures. Their output, however, often takes more brain power to
understand than the data itself. When dumping large amounts of data,
the output can be overwhelming and it can be difficult to see the
relationship between each piece of the dumped data.
Data::TreeDumper also dumps data in a tree-like fashion but hopefully
in a format more easily understood.
Label
Each node in the tree has a label. The label contains a type and an
address. The label is displayed to the right of the entry name within
square brackets.
| |- bbbbbb = CODE(0x8139fa0) [C3]
| |- c123 [C4 -> C3]
| `- d [R5]
| `- REF(0x8139fb8) [R5 -> C3]
Address
The addresses are linearly incremented which should make it easier to
locate data. If the entry is a reference to data already displayed, a
-> followed with the address of the already displayed data is appended
within the label.
ex: c123 [C4 -> C3]
^ ^
| | address of the data refered to
|
| current element address
Types
S: Scalar, H: Hash, A: Array, C: Code,
R: Reference, RS: Scalar reference. Ox: Object, where x is the object
undelying type
Empty Hash or Array
No structure is displayed for empty hashes or arrays, the string "no
elements" is added to the display.
|- A [S10] = string
|- EMPTY_ARRAY (no elements) [A11]
|- B [S12] = 123
Configuration and OverridesData::TreeDumper has configuration options you can set to modify the
output it generates. DumpTree and PrintTree take overrides as trailing
arguments. Those overrides are active within the current dump call
only.
ex:
$Data::TreeDumper::Maxdepth = 2 ;
# maximum depth set to 1 for the duration of the call only
print DumpTree($s, 'title', MAX_DEPTH => 1) ;
PrintTree($s, 'title', MAX_DEPTH => 1) ; # shortcut for the above call
# maximum depth is 2
print DumpTree($s, 'title') ;
$Data::TreeDumper::Displaycallerlocation
This package variable is very usefull when you use Data::TreeDumper and
don't know where you called PrintTree or DumpTree, ie when debugging.
It displays the filename and line of call on STDOUT. It can't also be
set as an override, DISPLAY_CALLER_LOCATION => 1.
NO_PACKAGE_SETUP
Sometimes, the package setup you have is not what you want to use.
resetting the variable, making a call and setting the variables back is
borring. You can set NO_PACKAGE_SETUP to 1 and DumpTree will ignore the
package setup for the call.
print Data::TreeDumper::DumpTree($s, "Using package data") ;
print Data::TreeDumper::DumpTree($s, "Not Using package data", NO_PACKAGE_SETUP => 1) ;
DISPLAY_ROOT_ADDRESS
By default, Data::TreeDumper doesn't display the address of the root.
DISPLAY_ROOT_ADDRESS => 1 # show the root address
DISPLAY_ADDRESS
When the dumped data is not self-referential, displaying the address of
each node clutters the display. You can direct Data::TreeDumper to not
display the node address by using:
DISPLAY_ADDRESS => 0
DISPLAY_PATH
Add the path of the element to the its address.
DISPLAY_PATH => 1
ex: '- CopyOfARRAY [A39 -> A18 /{'ARRAY'}]
DISPLAY_OBJECT_TYPE
Data::TreeDumper displays the package in which an object is blessed.
You can suppress this display by using:
DISPLAY_OBJECT_TYPE => 0
DISPLAY_INHERITANCE
Data::TreeDumper will display the inheritance hierarchy for the object:
|- object = blessed in 'SuperObject' <- Potatoe [OH55]
| `- Data = 0 [S56]
DISPLAY_AUTOLOAD
if set, Data::TreeDumper will tag the object type with '[A]' if the
package has an AUTOLOAD function.
|- object_with_autoload = blessed in '[A]SuperObjectWithAutoload' <- Potatoe <- [A] Vegetable [O58]
| `- Data = 0 [S56]
DISPLAY_TIE
if DISPLAY_TIE is set, Data::TreeDumper will display which packae the
variable is tied to. This works for hashes and arrays as well as for
object which are based on hashes and arrays.
|- tied_hash (tied to 'TiedHash') [H57]
| `- x = 1 [S58]
|- tied_hash_object = (tied to 'TiedHash') blessed in 'SuperObject' <- [A]Potatoe <- Vegetable [O59]
| |- m1 = 1 [S60]
| `- m2 = 2 [S61]
PERL DATA
Setting one of the options below will show internal perl data:
Cells: <2234> HASH(0x814F20c)
|- A1 [H1] <204> HASH(0x824620c)
| `- VALUE [S2] = datadatadatadatadatadatadatadatadatadata <85>
|- A8 [H11] <165> HASH(0x8243d68)
| `- VALUE [S12] = C <46>
`- C2 [H19] <165> HASH(0x8243dc0)
`- VALUE [S20] = B <46>
DISPLAY_PERL_SIZE
Setting this option will show the size of the memory allocated for each
element in the tree within angle brackets.
DISPLAY_PERL_SIZE => 1
The excellent Devel::Size is used to compute the size of the perl data.
If you have deep circular data structures, expect the dump time to be
slower, 50 times slower or more.
DISPLAY_PERL_ADDRESS
Setting this option will show the perl-address of the dumped data.
DISPLAY_PERL_ADDRESS => 1
REPLACEMENT_LIST
Scalars may contain non printable characters that you rather not see in
a dump. One of the most common is "\r" embedded in text string from dos
files. Data::TreeDumper, by default, replaces "\n" by '[\n]' and "\r"
by '[\r]'. You can set REPLACEMENT_LIST to an array ref containing
elements which are themselves array references. The first element is
the character(s) to match and the second is the replacement.
# a fancy and stricter replacement for \n and \r
my $replacement = [ ["\n" => '[**Fancy \n replacement**]'], ["\r" => '\r'] ] ;
print DumpTree($smed->{TEXT}, 'Text:', REPLACEMENT_LIST => $replacement) ;
QUOTE_HASH_KEYS
QUOTE_HASH_KEYS and its package variable
$Data::TreeDumper::Quotehashkeys can be set if you wish to single quote
the hash keys. Hash keys are not quoted by default.
DumpTree(\$s, 'some data:', QUOTE_HASH_KEYS => 1) ;
# output
some data:
`- REF(0x813da3c) [H1]
|- 'A' [H2]
| |- 'a' [H3]
| |- 'b' [H4]
| | |- 'a' = 0 [S5]
QUOTE_VALUES
QUOTE_VALUES and its package variable $Data::TreeDumper::Quotevalues
can be set if you wish to single quote the scalar values.
DumpTree(\$s, 'Cells:', QUOTE_VALUES=> 1) ;
NO_NO_ELEMENTS
If this option is set, Data::TreeDumper will not add 'no elements' to
empty hashes and arrays
NO_OUTPUT
This option suppresses all output generated by Data::TreeDumper. This
is useful when you want to iterate through your data structures and
display the data yourself, manipulate the data structure, or do a
search (see "using filter as iterators" below)
Filters
Data::TreeDumper can sort the tree nodes with a user defined
subroutine. By default, hash keys are sorted.
FILTER => \&ReverseSort
FILTER => \&Data::TreeDumper::HashKeysSorter
FILTER_ARGUMENT => ['your', 'arguments']
The filter routine is passed these arguments:
1 - a reference to the node which is going to be displayed
2 - the nodes depth (this allows you to selectively display elements at
a certain depth)
3 - the path to the reference from the start of the dump.
4 - an array reference containing the keys to be displayed (see filter
chaining below) last argument can be undefined and can then be safely
ignored.
5 - the dumpers setup
5 - the filter arguments (see below)
The filter returns the node's type, an eventual new structure (see
below) and a list of 'keys' to display. The keys are hash keys or array
indexes.
In Perl:
($tree_type, $replacement_tree, @nodes_to_display) = $your_filter->($tree, $level, $path, $nodes_to_display, $setup) ;
Filter are not as complicated as they sound and they are very
powerfull, especially when using the path argument. The path idea was
given to me by another module writer but I forgot whom. If this writer
will contact me, I will give him the proper credit.
Lots of examples can be found in filters.pl and I'll be glad to help if
you want to develop a specific filter.
FILTER_ARGUMENT
it is possible to pass arguments to your filter, passing a reference
allows you to modify the arguments when the filter is run (that
happends for each node).
sub SomeSub
{
my $counter = 0 ;
my $data_structure = {.....} ;
DumpTree($data_structure, 'title', FILTER => \&CountNodes, FILTER_ARGUMENT => \$counter) ;
print "\$counter = $counter\n" ;
}
sub CountNodes
{
my ($structure, $level, $path, $nodes_to_display, $setup, $counter) = @_ ;
$$counter++ ; # remember to pass references if you want them to be changed by the filter
return(DefaultNodesToDisplay($structure)) ;
}
Key removal
Entries can be removed from the display by not returning their keys.
my $s = {visible => '', also_visible => '', not_visible => ''} ;
my $OnlyVisible = sub
{
my $s = shift ;
if('HASH' eq ref $s)
{
return('HASH', undef, grep {! /^not_visible/} keys %$s) ;
}
return(Data::TreeDumper::DefaultNodesToDisplay($s)) ;
}
DumpTree($s, 'title', FILTER => $OnlyVisible) ;
Label changing
The label for a hash keys or an array index can be altered. This can be
used to add visual information to the tree dump. Instead of returning
the key name, return an array reference containing the key name and the
label you want to display. You only need to return such a reference
for the entries you want to change, thus a mix of scalars and array ref
is acceptable.
sub StarOnA
{
# hash entries matching /^a/i have '*' prepended
my $tree = shift ;
if('HASH' eq ref $tree)
{
my @keys_to_dump ;
for my $key_name (keys %$tree)
{
if($key_name =~ /^a/i)
{
$key_name = [$key_name, "* $key_name"] ;
}
push @keys_to_dump, $key_name ;
}
return ('HASH', undef, @keys_to_dump) ;
}
return (Data::TreeDumper::DefaultNodesToDisplay($tree)) ;
}
print DumpTree($s, "Entries matching /^a/i have '*' prepended", FILTER => \&StarOnA) ;
If you use an ANSI terminal, you can also change the color of the
label. This can greatly improve visual search time. See the label
coloring example in colors.pl.
Structure replacement
It is possible to replace the whole data structure in a filter. This
comes handy when you want to display a "worked" version of the
structure. You can even change the type of the data structure, for
example changing an array to a hash.
sub ReplaceArray
{
# replace arrays with hashes!!!
my $tree = shift ;
if('ARRAY' eq ref $tree)
{
my $multiplication = $tree->[0] * $tree->[1] ;
my $replacement = {MULTIPLICATION => $multiplication} ;
return('HASH', $replacement, keys %$replacement) ;
}
return (Data::TreeDumper::DefaultNodesToDisplay($tree)) ;
}
print DumpTree($s, 'replace arrays with hashes!', FILTER => \&ReplaceArray) ;
Here is a real life example. Tree::Simple
(http://search.cpan.org/dist/Tree-Simple/
<http://search.cpan.org/dist/Tree-Simple/>) allows one to build tree
structures. The child nodes are not directly in the parent object
(hash). Here is an unfiltered dump of a tree with seven nodes:
Tree::Simple through Data::TreeDumper
|- _children
| |- 0
| | |- _children
| | | `- 0
| | | |- _children
| | | |- _depth = 1
| | | |- _node = 1.1
| | | `- _parent
| | |- _depth = 0
| | |- _node = 1
| | `- _parent
| |- 1
| | |- _children
| | | |- 0
| | | | |- _children
| | | | |- _depth = 1
| | | | |- _node = 2.1
| | | | `- _parent
| | | |- 1
| | | | |- _children
| | | | |- _depth = 1
| | | | |- _node = 2.1a
| | | | `- _parent
| | | `- 2
| | | |- _children
| | | |- _depth = 1
| | | |- _node = 2.2
| | | `- _parent
| | |- _depth = 0
| | |- _node = 2
| | `- _parent
| `- 2
| |- _children
| |- _depth = 0
| |- _node = 3
| `- _parent
|- _depth = -1
|- _node = 0
`- _parent = root
This is nice for the developer but not for a user wanting to oversee
the node hierarchy. One of the possible filters would be:
FILTER => sub
{
my $s = shift ;
if('Tree::Simple' eq ref $s)
{
my $counter = 0 ;
return
(
'ARRAY'
, $s->{_children}
, map{[$counter++, $_->{_node}]} @{$s->{_children}} # index generation
) ;
}
return(Data::TreeDumper::DefaultNodesToDisplay($s)) ;
}
Which would give this much more readable output:
Tree::Simple through Data::TreeDumper2
|- 1
| `- 1.1
|- 2
| |- 2.1
| |- 2.1a
| `- 2.2
`- 3
What about counting the children nodes? The index generating code
becomes:
map{[$counter++, "$_->{_node} [" . @{$_->{_children}} . "]"]} @{$s->{_children}}
Tree::Simple through Data::TreeDumper4
|- 1 [1]
| `- 1.1 [0]
|- 2 [3]
| |- 2.1 [0]
| |- 2.1a [0]
| `- 2.2 [0]
`- 3 [0]
Filter chaining
It is possible to chain filters. CreateChainingFilter takes a list of
filtering sub references. The filters must properly handle the third
parameter passed to them.
Suppose you want to chain a filter that adds a star before each hash
key label, with a filter that removes all (original) keys that match
/^a/i.
sub AddStar
{
my $s = shift ;
my $level = shift ;
my $path = shift ;
my $keys = shift ;
if('HASH' eq ref $s)
{
$keys = [keys %$s] unless defined $keys ;
my @new_keys ;
for (@$keys)
{
if('' eq ref $_)
{
push @new_keys, [$_, "* $_"] ;
}
else
{
# another filter has changed the label
push @new_keys, [$_->[0], "* $_->[1]"] ;
}
}
return('HASH', undef, @new_keys) ;
}
return(Data::TreeDumper::DefaultNodesToDisplay($s)) ;
} ;
sub RemoveA
{
my $s = shift ;
my $level = shift ;
my $path = shift ;
my $keys = shift ;
if('HASH' eq ref $s)
{
$keys = [keys %$s] unless defined $keys ;
my @new_keys ;
for (@$keys)
{
if('' eq ref $_)
{
push @new_keys, $_ unless /^a/i ;
}
else
{
# another filter has changed the label
push @new_keys, $_ unless $_->[0] =~ /^a/i ;
}
}
return('HASH', undef, @new_keys) ;
}
return(Data::TreeDumper::DefaultNodesToDisplay($s)) ;
} ;
DumpTree($s, 'Chained filters', FILTER => CreateChainingFilter(\&AddStar, \&RemoveA)) ;
level Filters
It is possible to define one filter for a specific level. If a filter
for a specific level exists it is used instead of the global filter.
LEVEL_FILTERS => {1 => \&FilterForLevelOne, 5 => \&FilterForLevelFive
... } ;
Type Filters
You can define filters for specific types of references. This filter
type has the highest priority.
here's a very simple filter that will display the specified keys for
the types
print DumpTree
(
$data,
'title',
TYPE_FILTERS =>
{
'Config::Hierarchical' => sub {'HASH', undef, qw(CATEGORIES) },
'PBS2::Node' => sub {'HASH', undef, qw(CONFIG DEPENDENCIES MATCH) },,
}
) ;
Using filters as iterators
You can iterate through your data structures and display data yourself,
manipulate the data structure, or do a search. While iterating through
the data structure, you can prune arbitrary branches to speedup
processing.
# this example counts the nodes in a tree (hash based)
# a node is counted if it has a '__NAME' key
# any field that starts with '__' is considered rivate and we prune so we don't recurse in it
# anything that is not a hash (the part of the tree that interests us in this case) is pruned
my $number_of_nodes_in_the_dependency_tree = 0 ;
my $node_counter =
sub
{
my $tree = shift ;
if('HASH' eq ref $tree && exists $tree->{__NAME})
{
$number_of_nodes_in_the_dependency_tree++ if($tree->{__NAME} !~ /^__/) ;
return('HASH', $tree, grep {! /^__/} keys %$tree) ; # prune to run faster
}
else
{
return('SCALAR', 1) ; # prune
}
} ;
DumpTree($dependency_tree, '', NO_OUTPUT => 1, FILTER => $node_counter) ;
See the example under FILTER which passes arguments through
Data::TreeDumper instead for using a closure as above
Start level
This configuration option controls whether the tree trunk is displayed
or not.
START_LEVEL => 1:
$tree:
|- A [H1]
| |- a [H2]
| |- bbbbbb = CODE(0x8139fa0) [C3]
| |- c123 [C4 -> C3]
| `- d [R5]
| `- REF(0x8139fb8) [R5 -> C3]
|- ARRAY [A6]
| |- 0 [S7] = element_1
| |- 1 [S8] = element_2
START_LEVEL => 0:
$tree:
A [H1]
|- a [H2]
|- bbbbbb = CODE(0x8139fa0) [C3]
|- c123 [C4 -> C3]
`- d [R5]
`- REF(0x8139fb8) [R5 -> C3]
ARRAY [A6]
|- 0 [S7] = element_1
|- 1 [S8] = element_2
ASCII vs ANSI
You can direct Data:TreeDumper to output ANSI codes instead of ASCII
characters. The display will be much nicer but takes slightly longer
(not significant for small data structures).
USE_ASCII => 0 # will use ANSI codes instead
Display number of elements
DISPLAY_NUMBER_OF_ELEMENTS => 1
When set, the number of elements of every array and hash is displayed
(not for objects based on hashes and arrays).
Maximum depth of the dump
Controls the depth beyond which which we don't recurse into a
structure. Default is -1, which means there is no maximum depth. This
is useful to limit the amount of data displayed.
MAX_DEPTH => 1
Number of elements not displayed because of maximum depth limit
Data::TreDumper will display the number of elements a hash or array has
but that can not be displayed because of the maximum depth setting.
DISPLAY_NUMBER_OF_ELEMENTS_OVER_MAX_DEPTH => 1
Indentation
Every line of the tree dump will be appended with the value of
INDENTATION.
INDENTATION => ' ' ;
Custom glyphs
You can change the glyphs used by Data::TreeDumper.
DumpTree(\$s, 's', , GLYPHS => ['. ', '. ', '. ', '. ']) ;
# output
s
. REF(0x813da3c) [H1]
. . A [H2]
. . . a [H3]
. . . b [H4]
. . . . a = 0 [S5]
. . . . b = 1 [S6]
. . . . c [H7]
. . . . . a = 1 [S8]
Four glyphs must be given. They replace the standard glyphs ['| ', '|-
', '`- ', ' ']. It is also possible to set the package variable
$Data::TreeDumper::Glyphs. USE_ASCII should be set, which it is by
default.
Level numbering and tagging
Data:TreeDumper can prepend the level of the current line to the tree
glyphs. This can be very useful when searching in tree dump either
visually or with a pager.
NUMBER_LEVELS => 2
NUMBER_LEVELS => \&NumberingSub
NUMBER_LEVELS can be assigned a number or a sub reference. When
assigned a number, Data::TreeDumper will use that value to define the
width of the field where the level is displayed. For more control, you
can define a sub that returns a string to be displayed on the left side
of the tree glyphs. The example below tags all the nodes whose level is
zero.
print DumpTree($s, "Level numbering", NUMBER_LEVELS => 2) ;
sub GetLevelTagger
{
my $level_to_tag = shift ;
sub
{
my ($element, $level, $setup) = @_ ;
my $tag = "Level $level_to_tag => ";
if($level == 0)
{
return($tag) ;
}
else
{
return(' ' x length($tag)) ;
}
} ;
}
print DumpTree($s, "Level tagging", NUMBER_LEVELS => GetLevelTagger(0)) ;
Level coloring
Another way to enhance the output for easier searching is to colorize
it. Data::TreeDumper can colorize the glyph elements or whole levels.
If your terminal supports ANSI codes, using Term::ANSIColors and
Data::TreeDumper together can greatly ease the reading of large dumps.
See the examples in 'color.pl'.
COLOR_LEVELS => [\@color_codes, $reset_code]
When passed an array reference, the first element is an array
containing coloring codes. The codes are indexed with the node level
modulo the size of the array. The second element is used to reset the
color after the glyph is displayed. If the second element is an empty
string, the glyph and the rest of the level is colorized.
COLOR_LEVELS => \&LevelColoringSub
If COLOR_LEVEL is assigned a sub, the sub is called for each glyph
element. It is passed the following elements:
1 - the nodes depth (this allows you to selectively display elements at
a certain depth)
It should return a coloring code and a reset code. If you return an
empty string for the reset code, the whole node is displayed using the
last glyph element color.
If level numbering is on, it is also colorized.
WrappingData::TreeDumper uses the Text::Wrap module to wrap your data to fit
your display. Entries can be wrapped multiple times so they snuggly fit
your screen.
| | |- 1 [S21] = 1
| | `- 2 [S22] = 2
| `- 3 [OH23 -> R17]
|- ARRAY_ZERO [A24]
|- B [S25] = scalar
|- Long_name Long_name Long_name Long_name Long_name Long_name
| Long_name Long_name Long_name Long_name Long_name Long_name
| Long_name Long_name Long_name Long_name Long_name [S26] = 0
You can direct DTD to not wrap your text by setting NO_WRAP = 1>.
WRAP_WIDTH
if this option is set, Data::TreeDumper will use it instead for the
console width.
Custom RenderingData::TreeDumper has a plug-in interface for other rendering formats.
The renderer callbacks are set by overriding the native renderer.
Thanks to Stevan Little author of Tree::Simple::View for getting
Data::TreeDumper on this track. Check
Data::TreeDumper::Renderer::DHTML.
DumpTree
(
$s
, 'Tree'
, RENDERER =>
{
BEGIN => \&RenderDhtmlBegin
, NODE => \&RenderDhtmlNode
, END => \&RenderDhtmlEnd
# data needed by the renderer
, PREVIOUS_LEVEL => -1
, PREVIOUS_ADDRESS => 'ROOT'
}
) ;
Callbacks
· {RENDERER}{BEGIN} is called before the traversal of the data
structure starts. This allows you to setup the document (ex:: html
header).
1 $title
2 $type_address
3 $element
4 $perl_size
5 $perl_address
6 $setup
· {RENDERER}{NODE} is called for each node in the data structure. The
following arguments are passed to the callback
1 $element
2 $level
3 $is_terminal (whether a deeper structure will follow or not)
4 $previous_level_separator (ASCII separators before this node)
5 $separator (ASCII separator for this element)
6 $element_name
7 $element_value
8 $td_address (address of the element, Ex: C12 or H34. Unique for
each element)
9 $link_address (link to another element, may be undef)
10 $perl_size (size of the lement in bytes, see option
DISPLAY_PERL_SIZE)
11 $perl_address (adress (physical) of the element, see option
DISPLAY_PERL_ADDRESS)
12 $setup (the dumper's settings)
· {RENDERER}{END} is called after the last node has been processed.
· {RENDERER}{ ... }Arguments to the renderer can be stores within the
{RENDERER} hash.
Renderer modules
Renderers should be defined in modules under Data::TreeDumper::Renderer
and should define a function called GetRenderer. GetRenderer can be
passed whatever arguments the developer whishes. It is acceptable for
the modules to also export a specifc sub.
print DumpTree($s, 'Tree', Data::TreeDumper::Renderer::DHTML::GetRenderer()) ;
or
print DumpTree($s, 'Tree', GetDhtmlRenderer()) ;
If {RENDERER} is set to a scalar, Data::TreeDumper will load the
specified module if it exists. GetRenderer will be called without
arguments.
print DumpTree($s, 'Tree', RENDERER => 'DHTML') ;
If {RENDERER}{NAME} is set to a scalar, Data::TreeDumper will load the
specified module if it exists. GetRenderer will be called without
arguments. Arguments to the renderer can aither be passed to the
GetRenderer sub or as elements in the {RENDERER} hash.
print DumpTree($s, 'Tree', RENDERER => {NAME => 'DHTML', STYLE => \$style) ;
Zero width console
When no console exists, while redirecting to a file for example,
Data::TreeDumper uses the variable VIRTUAL_WIDTH instead. Default is
120.
VIRTUAL_WIDTH => 120 ;
OVERRIDE list
· COLOR_LEVELS
· DISPLAY_ADDRESS
· DISPLAY_PATH
· DISPLAY_PERL_SIZE
· DISPLAY_ROOT_ADDRESS
· DISPLAY_PERL_ADDRESS
· FILTER
· GLYPHS
· INDENTATION
· LEVEL_FILTERS
· MAX_DEPTH
· DISPLAY_NUMBER_OF_ELEMENTS_OVER_MAX_DEPTH
· NUMBER_LEVELS
· QUOTE_HASH_KEYS
· QUOTE_VALUES
· REPLACEMENT_LIST
· START_LEVEL
· USE_ASCII
· WRAP_WIDTH
· VIRTUAL_WIDTH
· NO_OUTPUT
· DISPLAY_OBJECT_TYPE
· DISPLAY_INHERITANCE
· DISPLAY_TIE
· DISPLAY_AUTOLOAD
Interface
Package Data (a la Data::Dumper (as is the silly naming scheme))
Configuration Variables
$Data::TreeDumper::Startlevel = 1 ;
$Data::TreeDumper::Useascii = 1 ;
$Data::TreeDumper::Maxdepth = -1 ;
$Data::TreeDumper::Indentation = '' ;
$Data::TreeDumper::Virtualwidth = 120 ;
$Data::TreeDumper::Displayrootaddress = 0 ;
$Data::TreeDumper::Displayaddress = 1 ;
$Data::TreeDumper::Displaypath = 0 ;
$Data::TreeDumper::Displayobjecttype = 1 ;
$Data::TreeDumper::Displayinheritance = 0 ;
$Data::TreeDumper::Displaytie = 0 ;
$Data::TreeDumper::Displayautoload = 0 ;
$Data::TreeDumper::Displayperlsize = 0 ;
$Data::TreeDumper::Displayperladdress = 0 ;
$Data::TreeDumper::Filter = \&FlipEverySecondOne ;
$Data::TreeDumper::Levelfilters = {1 => \&Filter_1, 5 => \&Filter_5} ;
$Data::TreeDumper::Numberlevels = 0 ;
$Data::TreeDumper::Glyphs = ['| ', '|- ', '`- ', ' '] ;
$Data::TreeDumper::Colorlevels = undef ;
$Data::TreeDumper::Nooutput = 0 ; # generate an output
$Data::TreeDumper::Quotehashkeys = 0 ;
$Data::TreeDumper::Displaycallerlocation = 0 ;
API
PrintTreeprints on STDOUT the output of DumpTree.
DumpTree uses the configuration variables defined above. It takes the
following arguments:
[1] structure_to_dump
[2] title, a string to prepended to the tree (optional)
[3] overrides (optional)
print DumpTree($s, "title", MAX_DEPTH => 1) ;
DumpTrees uses the configuration variables defined above. It takes the
following arguments
[1] One or more array references containing
[a] structure_to_dump
[b] title, a string to prepended to the tree (optional)
[c] overrides (optional)
[2] overrides (optional)
print DumpTrees
(
[$s, "title", MAX_DEPTH => 1]
, [$s2, "other_title", DISPLAY_ADDRESS => 0]
, USE_ASCII => 1
, MAX_DEPTH => 5
) ;
Bugs
None that I know of in this release but plenty, lurking in the dark
corners, waiting to be found.
Examples
Four examples files are included in the distribution.
usage.pl shows you how you can use Data::TreeDumper.
filters.pl shows you how you how to do advance filtering.
colors.pl shows you how you how to colorize a dump.
try_it.pl is meant as a scratch pad for you to try Data::TreeDumper.
DEPENDENCY
Text::Wrap.
Term::Size or Win32::Console.
Optional Devel::Size if you want Data::TreeDumper to show perl sizes
for the tree elements.
EXPORT
DumpTree, DumpTrees and CreateChainingFilter.
AUTHOR
Khemir Nadim ibn Hamouda. <nadim@khemir.net>
Thanks to Ed Avis for showing interest and pushing me to re-write the
documentation.
Copyright (c) 2003-2006 Nadim Ibn Hamouda el Khemir. All rights
reserved. This program is free software; you can redis-
tribute it and/or modify it under the same terms as Perl
itself.
If you find any value in this module, mail me! All hints, tips, flames
and wishes are welcome at <nadim@khemir.net>.
SEE ALSO
Data::TreeDumper::00. Data::Dumper.
Data::TreeDumper::Renderer::DHTML.
Devel::Size::Report.Devel::Size.
PBS: the Perl Build System from which Data::TreeDumper was extracted.
POD ERRORS
Hey! The above document had some coding errors, which are explained
below:
Around line 2501:
=over should be: '=over' or '=over positive_number'
perl v5.14.1 2008-11-01 TreeDumper(3)
