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 referred 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 underlying 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

$Data::TreeDumper::Displaycallerlocation¶

This package variable is very useful 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 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 boring. 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 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 package the variable is tied to. This works for hashes and arrays as well as for objects 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 would rather not see in a dump. One of the most common is "\r" embedded in a text string from MS-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]

DISPLAY_NO_VALUE¶

Only element names are added to the tree rendering

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_ARGUMENT => ['your', 'arguments']

The filter routine is passed these arguments:

1 - a reference to the node which is going to be displayed

2 - the node's 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")

5 - the dumper's setup

5 - the filter arguments (see below)

The filter returns the node's type, possibly a 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) ;

Filters are not as complicated as they sound and they are very powerful, 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 happens 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 refs 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 the 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 in 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/>) 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 per 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 speed processing up.

  # 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 private 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 for limiting 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¶

The value of INDENTATION will be prepended to every line of the tree dump.

  INDENTATION => '   ' ;

WRAP_WIDTH¶

if this option is set, Data::TreeDumper will use it instead for the console width.

Callbacks¶

•

{RENDERER}{BEGIN} is called before the traversal of the data structure starts. This allows you to setup the document (ex:: html header).

my ($title, $type_address, $element, $size, $perl_address, $setup) = @_ ;

•

{RENDERER}{NODE} is called for each node in the data structure. The following arguments are passed to the callback

• {RENDERER}{END} is called after the last node has been processed.
• {RENDERER}{ ... } Arguments to the renderer can be stored 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 wishes. It is acceptable for the modules to also export a specific 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 either be passed to the GetRenderer sub or as elements in the {RENDERER} hash.

  print DumpTree($s, 'Tree', RENDERER => {NAME => 'DHTML', STYLE => \$style) ;

Package Data (à 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

[2] overrides (optional)

  print DumpTrees
          (
            [$s, "title", MAX_DEPTH => 1]
          , [$s2, "other_title", DISPLAY_ADDRESS => 0]
          , USE_ASCII => 1
          , MAX_DEPTH => 5
          ) ;