The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Tree-To-Text-0.061
River stage two • 4 direct dependents • 20 total dependents
/ Tree::To::TextLines

NAME

Tree::To::TextLines - Render a tree object as indented text lines

VERSION

This document describes version 0.061 of Tree::To::TextLines (from Perl distribution Tree-To-Text), released on 2021-05-06.

SYNOPSIS

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

Sample output:

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

DESCRIPTION

FUNCTIONS

render_tree_as_text([ \%opts, ] $tree) => str

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

This function is the complement for build_tree_from_text_lines function in Tree::From::TextLines.

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:

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:

$node->id

where id is the name of the ID attribute.

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.

After that, if extra_attributes is set (e.g. to ["foo", "bar"]), will show the value of the attributes:

$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.:

($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:

    id:1
  id:2
  id:3
    id:4
  id:5

    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"]:

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

    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

    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:

    ($node, $level, $seniority, $is_last_child, $opts)

    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.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Tree-To-Text.

SOURCE

Source repository is at https://github.com/perlancar/perl-Tree-To-Text.

BUGS

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.

SEE ALSO

Tree::From::Text, Tree::From::TextLines

Tree::From::Struct, Tree::From::ObjArray

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

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.