/ 
Data-TreeDumper-0.11
River stage two • 22 direct dependents • 28 total dependents
/ Data::TreeDumper

NAME

Data::TreeDumper - dumps a data structure in a tree fashion.

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 ;
  $Data::TreeDumper::Filter   = \&Data::TreeDumper::HashKeysSorter ;
  
  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
	  ) ;
  
  #-------------------------------------------------------------------
  # OO interface
  #-------------------------------------------------------------------
  
  my $dumper = new Data::TreeDumper() ;
  $dumper->UseAnsi(1) ;
  $dumper->Maxdepth(2) ;
  $dumper->Filter(\&Data::TreeDumper::HashKeysSorter) ;
  
  print $dumper->Dump($s, "Using OO interface") ;
  print $dumper->DumpMany
	  (
	    [$s, "title", MAX_DEPTH => 1]
	  , [$s2, "other_title", DISPLAY_ADDRESS => 0]
	  , USE_ASCII => 1
	  , MAX_DEPTH => 5
	  ) ;
   
  #-------------------------------------------------------------------
  # native interface
  #-------------------------------------------------------------------
  
  print Data::TreeDumper::TreeDumper
  	(
  	  $s
  	, {
  	    FILTER      => \&Data::TreeDumper::HashKeysSorter
  	  , START_LEVEL => 1
  	  , USE_ASCII   => 0
  	  , MAX_DEPTH   => 2
  	  , TITLE       => "Using Native interface\n"
  	  }
  	) ;

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 at dumping data structure but their output sometime takes more brain to understand than it takes to understand the data itself. When dumping big amounts of data, the output is overwhelming and it's difficult to see the relationship between each piece of the dumped data.

Data::TreeDumper dumps data in a trees like fashion hopping for the output to be easier on the beholder's eye and brain. But it might as well be the opposite!

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 address

Types

H: Hash, C: Code, A: Array, R: Reference,

O: Object, S: Scalar, RS: Scalar reference.

Empty Hash or Array

No structure is displayed for empty hashes or arrays, The address contains the type.

|- A [S10] = string
|- EMPTY_ARRAY [A11]
|- B [S12] = 123

Configuration and Overrides

Data::TreeDumper has configuration options you can set to modify the output it generates. How to set the options depends on which Interface you use and is explained bellow. The configuration options are available in all the Interfaces and are the Native interface arguments.

The package and object oriented interface 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) ;
	
  # maximum depth is 2
  print DumpTree($s, 'title') ;

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 are 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

Filters

Data::TreeDumper can sort the tree nodes with a user defined sub.

FILTER => \&ReverseSort
FILTER => \&Data::TreeDumper::HashKeysSorter

The filter sub is passed three arguments, a reference to the node which is going to be displayed, it's depth (this allows you to selectively display elements at a certain depth) and an array reference containing the keys to be displayed (see filter chaining bellow) last argument can be undefined and can then be safely ignored.

The filter returns the node's type, an eventual new structure (see bellow) and a list of 'keys' to display. The keys are hash keys or array indexes.

If you set FILTER to \&Data::TreeDumper::HashKeysSorter, hashes will be sorted in alphabetic order.

Key removal

Entries can be removed 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 for 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) ;

filter chaining

It is possible to chain filters. Data::TreeDumper exports CreateChainingFilter. 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 $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 $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)) ;

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] = elment_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] = elment_1
|- 1 [S8] = element_2

ASCII vs ANSI

You can direct Data:TreeDumper to output ANSI codes instead for ASCII characters. The display will be much nicer but takes slightly longer time (not significant for small data structures).

USE_ASCII => 0 # will use ANSI codes instead

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

Indentation

Every line of the tree dump will be appended with the value of INDENTATION.

INDENTATION => '   ' ;

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 bellow tags all the nodes which 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 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.

Wrapping

Data::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 [O23 -> 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

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_ROOT_ADDRESS

  • FILTER

  • INDENTATION

  • MAX_DEPTH

  • NUMBER_LEVELS

  • START_LEVEL

  • USE_ASCII

  • VIRTUAL_WIDTH

Interfaces

Data:TreeDumper has three interfaces. A 'package data' interface resembling Data::Dumper, an object oriented interface and the native interface. All interfaces return a string containing the dump.

Package Data (à la Data::Dumper)

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::Filter             = \&FlipEverySecondOne ;
$Data:TreeDumper::Numberlevels       = 0 ;
$Data:TreeDumper::Colorlevels        = undef ;

Functions

DumpTree uses the configuration variables defined above. It takes the following arguments

[1] structure_to_dump, this must be a reference
[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, this must be a reference
[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
	  ) ;

Object oriented Methods

  # constructor
  my $dumper = new Data::TreeDumper(MAX_DEPTH => 1) ;
  
  $dumper->UseAnsi(1) ;
  $dumper->UseAscii(1) ;
  $dumper->Maxdepth(2) ;
  $dumper->SetIndentation('   ') ;
  $dumper->SetVirtualWidth(80) ;
  $dumper->SetFilter(\&Data::TreeDumper::HashKeysSorter) ;
  $dumper->SetStartLevel(0) ;
  $dumper->DisplayRootAddress(1) ;
  $dumper->DisplayAddress(0) ;
  $dumper->NumberLevels(2) ;
  $dumper->ColorLevels(\&ColorLevelSub) ;
  
  $dumper->Dump($s, "Using OO interface", %OVERRIDES) ;
  $dumper->DumpMany
            (
	      [$s, "dump1", %OVERRIDES]
	    , [$s, "dump2", %OVERRIDES]
	    , %OVERRIDES
	    ) ;

Native

  Data::TreeDumper::TreeDumper
  	(
  	  $s
  	, {
  	    FILTER               => \&Data::TreeDumper::HashKeysSorter
  	  , START_LEVEL          => 1
  	  , USE_ASCII            => 0
  	  , MAX_DEPTH            => 2
  	  , TITLE                => "Using Native interface"
  	  , DISPLAY_ROOT_ADDRESS => 0
  	  , DISPLAY_ADDRESS      => 1
	  , INDENTATION          => ''
	  , NUMBER_LEVELS        => 0
	  , COLOR_LEVELS         => undef
  	}
  	) ;

Bugs

None 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.

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

The excellent Data::Dumper.

PBS: the Perl Build System from which Data::TreeDumper was extracted. Contact the author for more information about PBS.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 1392:

Non-ASCII character seen before =encoding in '(à'. Assuming CP1252