Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
TreeDumper(3)	      User Contributed Perl Documentation	 TreeDumper(3)

NAME
       Data::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 Overrides
       Data::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_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")
       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/>) 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.

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 [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 Rendering
       Data::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
       o {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) = @_ ;

	     1 $title

	     2 $type_address

	     3 $element

	     4 $perl_size

	     5 $perl_address

	     6 $setup

       o {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)
       o {RENDERER}{END} is called after the last node has been	processed.

       o {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
       o COLOR_LEVELS

       o DISPLAY_ADDRESS

       o DISPLAY_PATH

       o DISPLAY_PERL_SIZE

       o DISPLAY_ROOT_ADDRESS

       o DISPLAY_PERL_ADDRESS

       o FILTER

       o GLYPHS

       o INDENTATION

       o LEVEL_FILTERS

       o MAX_DEPTH

       o DISPLAY_NUMBER_OF_ELEMENTS_OVER_MAX_DEPTH

       o NUMBER_LEVELS

       o QUOTE_HASH_KEYS

       o QUOTE_VALUES

       o REPLACEMENT_LIST

       o START_LEVEL

       o USE_ASCII

       o WRAP_WIDTH

       o VIRTUAL_WIDTH

       o NO_OUTPUT

       o DISPLAY_OBJECT_TYPE

       o DISPLAY_INHERITANCE

       o DISPLAY_TIE

       o 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-2010 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 2454:
	   You can't have =items (as at	line 2458) unless the first thing
	   after the =over is an =item

       Around line 2612:
	   Non-ASCII character seen before =encoding in	'(A '. Assuming	CP1252

perl v5.32.0			  2011-05-19			 TreeDumper(3)

NAME | SYNOPSIS | Output | DESCRIPTION | Configuration and Overrides | Custom glyphs | Level numbering and tagging | Level coloring | Wrapping | Custom Rendering | Zero width console | OVERRIDE list | Interface | Bugs | Examples | DEPENDENCY | EXPORT | AUTHOR | SEE ALSO | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Data::TreeDumper&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help