SYNOPSIS

    use Tree::Create::Callback qw(create_tree_using_callback);
    use Tree::Object::Hash; # for nodes

    # create a tree of height 4 containing 1 + 2 + 4 + 8 nodes
    my $tree = create_tree_using_callback(
        sub {
            my ($parent, $level, $seniority) = @_;
            # we should return ($node, $num_children)
            return (Tree::Object::Hash->new, $level >= 3 ? 0:2);
        }
    );

DESCRIPTION

   Building a tree manually can be tedious: you have to connect the parent
   and the children nodes together:

    my $root = My::TreeNode->new(...);
    my $child1 = My::TreeNode->new(...);
    my $child2 = My::TreeNode->new(...);

    $root->children([$child1, $child2]);
    $child1->parent($root);
    $child2->parent($root);

    my $grandchild1 = My::Class->new(...);
    ...

   This module provides a convenience function to build a tree of objects
   in a single command. You supply a callback to create node and the
   function will connect the parent and children nodes for you.

   The callback is called with these arguments:

    ($parent, $level, $seniority)

   where $parent is the parent node object (or undef if creating the root
   node, which is the first time the callback is called), $level indicates
   the current depth of the tree (starting from 0 for the root node, then
   1 for the root's children, then 2 for their children, and so on). You
   can use this argument to know where to stop creating nodes. $seniority
   indicates the position of the node against its sibling (0 means the
   node is the first child of its parent, 1 means the second, and so on).
   You can use this argument to perhaps customize the node according to
   its sibling order.

   The callback should return a list:

    ($node, $num_children)

   where $node is the created node object (the object can be of any class
   but it must respond to parent and children, see
   Role::TinyCommons::Tree::Node for more details on the requirement),
   $num_children is an integer that specifies the number of children that
   this node should have (0 means this node is to be a leaf node). The
   children will be created when the function calls the callback again
   later for each child node.

FUNCTIONS

create_tree_using_callback($cb) => obj

SEE ALSO

   Other Tree::Create::* modules, e.g. Tree::Create::Size.

   Other ways to create tree: Tree::FromStruct, Tree::FromText,
   Tree::FromTextLines.