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.