Provided by: libtree-perl_1.10-0ubuntu1_all bug

NAME

       Tree::Fast - the fastest possible implementation of a tree in pure Perl

SYNOPSIS

         my $tree = Tree::Fast->new( 'root' );
         my $child = Tree::Fast->new( 'child' );
         $tree->add_child( {}, $child );

         $tree->add_child( { at => 0 }, Tree::Fast->new( 'first child' ) );
         $tree->add_child( { at => -1 }, Tree::Fast->new( 'last child' ) );

         my @children = $tree->children;
         my @some_children = $tree->children( 0, 2 );

         $tree->remove_child( 0 );

         my @nodes = $tree->traverse( $tree->POST_ORDER );

         my $traversal = $tree->traverse( $tree->POST_ORDER );
         while ( my $node = $traversal->() ) {
             # Do something with $node here
         }

         my $clone = $tree->clone;
         my $mirror = $tree->clone->mirror;

DESCRIPTION

       This is meant to be the core implementation for Tree, stripped down as much as possible.
       There is no error-checking, bounds-checking, event-handling, convenience methods, or
       anything else of the sort. If you want something fuller-featured, please look at Tree,
       which is a wrapper around Tree::Fast.

METHODS

   Constructors
   new([$value])
       Here, [] indicate an optional parameter.

       This will return a "Tree::Fast" object. It will accept one parameter which, if passed,
       will become the value (accessible by "value()"). All other parameters will be ignored.

       If you call "$tree->new([$value])", it will instead call "clone()", then set the value of
       the clone to $value.

   clone()
       This will return a clone of $tree. The clone will be a root tree, but all children will be
       cloned.

       If you call "Tree::Fast->clone([$value])", it will instead call "new()".

       NOTE: the value is merely a shallow copy. This means that all references will be kept.

   Behaviors
   add_child($options, @nodes)
       This will add all the @nodes as children of $tree. $options is a required hashref that
       specifies options for "add_child()". The optional parameters are:

       •   at

           This specifies the index to add @nodes at. If specified, this will be passed into
           splice(). The only exceptions are if this is 0, it will act as an unshift(). If it is
           unset or undefined, it will act as a push().

   remove_child($options, @nodes)
       This will remove all the @nodes from the children of $tree. You can either pass in the
       actual child object you wish to remove, the index of the child you wish to remove, or a
       combination of both.

       $options is a required hashref that specifies parameters for remove_child().  Currently,
       no parameters are used.

   mirror()
       This will modify the tree such that it is a mirror of what it was before. This means that
       the order of all children is reversed.

       NOTE: This is a destructive action. It will modify the tree's internal structure. If you
       wish to get a mirror, yet keep the original tree intact, use "my $mirror =
       $tree->clone->mirror".

   traverse( [$order] )
       Here, [] indicate an optional parameter.

       When called in list context ("my @traversal = $tree->traverse()"), this will return a list
       of the nodes in the given traversal order. When called in scalar context ("my $traversal =
       $tree->traverse()"), this will return a closure that will, over successive calls, iterate
       over the nodes in the given traversal order. When finished it will return false.

       The default traversal order is pre-order.

       The various traversal orders do the following steps:

       •   Pre-order

           This will return the node, then the first sub tree in pre-order traversal, then the
           next sub tree, etc.

           Use "$tree->PRE_ORDER" as the $order.

       •   Post-order

           This will return the each sub-tree in post-order traversal, then the node.

           Use "$tree->POST_ORDER" as the $order.

       •   Level-order

           This will return the node, then the all children of the node, then all grandchildren
           of the node, etc.

           Use "$tree->LEVEL_ORDER" as the $order.

   Accessors
   parent()
       This will return the parent of $tree.

   children( [ $idx, [$idx, ..] ] )
       Here, [] indicate optional parameters.

       This will return the children of $tree. If called in list context, it will return all the
       children. If called in scalar context, it will return the number of children.

       You may optionally pass in a list of indices to retrieve. This will return the children in
       the order you asked for them. This is very much like an arrayslice.

   value()
       This will return the value stored in the node.

   set_value([$value])
       Here, [] indicate an optional parameter.

       This will set the value stored in the node to $value, then return $self.

       If $value is not provided, undef is used.

   meta()
       This will return a hashref that can be used to store whatever metadata the client wishes
       to store. For example, Tree::Persist::DB uses this to store database row ids.

       It is recommended that you store your metadata in a subhashref and not in the top-level
       metadata hashref, keyed by your package name. Tree::Persist does this, using a unique key
       for each persistence layer associated with that tree.  This will help prevent clobbering
       of metadata.

NULL TREE

       If you call "$self->parent" on a root node, it will return a Tree::Null object. This is an
       implementation of the Null Object pattern optimized for usage with Tree::Fast. It will
       evaluate as false in every case (using overload) and all methods called on it will return
       a Tree::Null object.

   Notes
       •   Tree::Null does not inherit from anything. This is so that all the methods will go
           through AUTOLOAD vs. the actual method.

       •   However, calling isa() on a Tree::Null object will report that it is-a any object that
           is either Tree or in the Tree:: hierarchy.

       •   The Tree::Null object is a singleton.

       •   The Tree::Null object is defined, though. I couldn't find a way to make it evaluate as
           undefined. That may be a good thing.

CODE COVERAGE

       Please see the relevant sections of Tree.

SUPPORT

       Please see the relevant sections of Tree.

ACKNOWLEDGEMENTS

       •   Stevan Little for writing Tree::Simple, upon which Tree is based.

AUTHORS

       Rob Kinyon <rob.kinyon@iinteractive.com>

       Stevan Little <stevan.little@iinteractive.com>

       Thanks to Infinity Interactive for generously donating our time.

COPYRIGHT AND LICENSE

       Copyright 2004, 2005 by Infinity Interactive, Inc.

       <http://www.iinteractive.com>

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.