Tree::To::TextLines - Render a tree object as indented text lines
This document describes version 0.061 of Tree::To::TextLines (from Perl distribution Tree-To-Text), released on 2021-05-06.
use Tree::To::TextLines qw(render_tree_as_text); my $tree = ...; # you can build a tree e.g. using Tree::From::Struct, Tree::From::ObjArray, or Tree::From::TextLines
Using default option:
print render_tree_as_text($tree);
Sample output:
Tree::Example::HashNode=HASH(0xca80e0) Tree::Example::HashNode::Sub1=HASH(0xbd8c10) Tree::Example::HashNode::Sub2=HASH(0xd8b518) Tree::Example::HashNode::Sub1=HASH(0xd8b710) Tree::Example::HashNode::Sub2=HASH(0xd8bc50) Tree::Example::HashNode::Sub1=HASH(0xd8b788) Tree::Example::HashNode::Sub1=HASH(0xd8b830) Tree::Example::HashNode::Sub1=HASH(0xd8b8d8) Tree::Example::HashNode::Sub1=HASH(0xd8b3b0) Tree::Example::HashNode::Sub2=HASH(0xd8b620) Tree::Example::HashNode::Sub1=HASH(0xd8b980) Tree::Example::HashNode::Sub2=HASH(0xd8bce0) Tree::Example::HashNode::Sub1=HASH(0xd8ba58) Tree::Example::HashNode::Sub1=HASH(0xd8bb00) Tree::Example::HashNode::Sub1=HASH(0xd8bba8) Tree::Example::HashNode::Sub1=HASH(0xd8b470)
Customize options:
print render_tree_as_text({ #indent => 2, show_guideline => 1, # default: 0 id_attribute => 'id', # default: undef #show_attribute_name => 1, #show_class_name => 0, #extra_attributes => [..., ...], # default: undef }, $tree);
id:1 |-- id:2 | \-- id:5 | |-- id:7 | | \-- id:15 | |-- id:8 | |-- id:9 | \-- id:10 |-- id:3 | \-- id:6 | |-- id:11 | | \-- id:16 | |-- id:12 | |-- id:13 | \-- id:14 \-- id:4
This function renders a tree object $tree as lines of text, each line showing a node and indented differently according to the node's position in the tree. A child node will be indented more deeply than its parent node.
$tree
Tree object of any kind of class is accepted as long as the class responds to children and the method returns a list or arrayref of children nodes. The name of the children method children can be customized using get_children_method option.
children
get_children_method
This function is the complement for build_tree_from_text_lines function in Tree::From::TextLines.
build_tree_from_text_lines
When on_show_node option is specified, that routine will be called with ($node, $level, $seniority, $is_last_child, $opts) and the return value will be used to display each node. Otherwise, the default behavior to show each node is as follow:
on_show_node
($node, $level, $seniority, $is_last_child, $opts)
By default a node will be shown using:
"$node"
that is, class name followed by its stringified value, which by default when not overloaded by the object will be something like:
Foo=HASH(0x1472160)
If id_attribute is specified, then instead the node will be shown using:
id_attribute
$node->id
where id is the name of the ID attribute.
id
Rule to render value of attribute: If attribute name does not match /\A\w+\z/ or a node does not respond to the getter method of that name, and the object is hash-based, then hash key of that name will be used instead. If said hash key does not exist also, undef will be used. When displaying the value of an attribute, Data::Dmp will be used for non-number strings and references.
/\A\w+\z/
undef
After that, if extra_attributes is set (e.g. to ["foo", "bar"]), will show the value of the attributes:
extra_attributes
["foo", "bar"]
$node->id . " " . ref($node) . " " . $node->foo . " " . $node->bar
The same rule for ID attribute will be used to render the value of these attributes.
If show_class_name is set to true, will prepend with class name in parentheses, e.g.:
show_class_name
($class) ...
Available options:
get_children_method => str (default: children)
Example:
get_children_method => "get_children"
By default, children is the method that will be used on node objects to retrieve children nodes. But you can customize that using this option. Note that the method must return either a list or arrayref of nodes.
indent => int (default: 2)
Number of spaces for each indent level.
show_guideline => bool (default: 0)
If set to false, then the tree will just a set of indented lines, e.g.:
id:1 id:2 id:3 id:4 id:5
If set to true, guidelines will be shown, e.g.:
id:1 |-- id:2 |-- id:3 | \-- id:4 \-- id:5
id_attribute => str (default: undef)
Name of ID attribute. If ID attribute is not specified, each node will be shown as stringified object (only first line used), e.g.:
Tree::Object::Hash=HASH(0x209a160) Tree::Object::Hash=HASH(0xfc9160) Tree::Object::Hash=HASH(0xac7160)
If ID attribute is used, the value of this attribute will be used instead, e.g.:
id:node0 id:node1 id:node2
show_class_name => bool (default: 0)
Whether to show class name before showing node, e.g. when false:
When true:
(Tree::Object) id:1 (Tree::Object) id:2 (Tree::Object) id:3 (Tree::Object::Subclass) id:4 (Tree::Object) id:5
extra_attributes => array of str (default: undef)
When specified, will show the extra attributes after the ID attribute and class name, e.g. when set to ["foo","bar"]:
["foo","bar"]
id:1 foo:a bar:b id:2 foo:c bar:b id:3 foo: bar:d id:4 foo:a2 bar:b2 id:5 foo:a bar:b
show_attribute_name => bool (default: 1)
When set to true, each time an attribute is shown its name will be printed first, e.g.:
When set to false:
1 a b 2 c b 3 d 4 a2 b2 5 a b
on_show_node => code
Can be used to completely customize how to display a node. It will be called with these arguments:
where $level is 0 for the root node, 1 for the root's children, and so on. $seniority is 0 for the first child, 1 for the second, and so on. $is_last_child will be set to true if node is the last child. The code should return a string that will be used to display a node.
$level
$seniority
$is_last_child
Please visit the project's homepage at https://metacpan.org/release/Tree-To-Text.
Source repository is at https://github.com/perlancar/perl-Tree-To-Text.
Please report any bugs or feature requests on the bugtracker website https://github.com/perlancar/perl-Tree-To-Text/issues
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
Tree::From::Text, Tree::From::TextLines
Tree::From::Struct, Tree::From::ObjArray
perlancar <perlancar@cpan.org>
This software is copyright (c) 2021, 2020 by perlancar@cpan.org.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Tree::To::Text, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Tree::To::Text
CPAN shell
perl -MCPAN -e shell install Tree::To::Text
For more information on module installation, please visit the detailed CPAN module installation guide.