Rob Kinyon > Tree-1.01 > Tree

Download:
Tree-1.01.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 1.01   Source   Latest Release: Tree-1.05

NAME ^

Tree - an N-ary tree

SYNOPSIS ^

  my $tree = Tree->new( 'root' );
  my $child = Tree->new( 'child' );
  $tree->add_child( $child );

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

  $tree->set_value( 'toor' );
  my $value = $tree->value;

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

  my $height = $tree->height;
  my $width  = $tree->width;
  my $depth  = $tree->depth;
  my $size   = $tree->size;

  if ( $tree->has_child( $child ) ) {
      $tree->remove_child( $child );
  }

  $tree->remove_child( 0 );

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

  $tree->add_event_handler({
      add_child    => sub { ... },
      remove_child => sub { ... },
      value        => sub { ... },
  });

DESCRIPTION ^

This is meant to be a full-featured N-ary tree representation with configurable error-handling and a simple events system that allows for transparent persistence to a variety of datastores. It is derived from Tree::Simple, but has a simpler interface and much, much more.

METHODS ^

Constructor

new([$value])

This will return a Tree 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->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 optional unblessed 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 optional unblessed 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] )

This will return a list of the nodes in the given traversal order. The default traversal order is pre-order.

The various traversal orders do the following steps:

  • Pre-order (aka Prefix traversal)

    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 (aka Prefix traversal)

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

    Use $tree->POST_ORDER as the $order.

  • Level-order (aka Prefix traversal)

    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.

All behaviors will reset last_error().

State Queries

Accessors

ERROR HANDLING ^

Describe what the default error handlers do and what a custom error handler is expected to do.

Error-related methods

Default error handlers

QUIET

Use this error handler if you want to have quiet error-handling. The last_error method will retrieve the error from the last operation, if there was one. If an error occurs, the operation will return undefined.

WARN
DIE

EVENT HANDLING ^

Forest provides for basic event handling. You may choose to register one or more callbacks to be called when the appropriate event occurs. The events are:

Event handling methods

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. It will evaluate as false in every case (using overload) and all methods called on it will return a Tree::Null object.

Notes

CIRCULAR REFERENCES ^

Please q.v. Forest for more info on this topic.

WHAT'S NOT HERE ^

CODE COVERAGE ^

We use Devel::Cover to test the code coverage of our tests. Below is the Devel::Cover report on this module's test suite.

  ---------------------------- ------ ------ ------ ------ ------ ------ ------
  File                           stmt   bran   cond    sub    pod   time  total
  ---------------------------- ------ ------ ------ ------ ------ ------ ------
  blib/lib/Tree.pm              100.0  100.0   94.4  100.0  100.0   67.3   99.7
  blib/lib/Tree/Binary.pm        96.4   95.0  100.0  100.0  100.0   10.7   96.7
  blib/lib/Tree/Fast.pm          99.4   95.5   91.7  100.0  100.0   22.0   98.6
  Total                          98.9   96.8   94.9  100.0  100.0  100.0   98.5
  ---------------------------- ------ ------ ------ ------ ------ ------ ------

ACKNOWLEDGEMENTS ^

SUPPORT ^

The mailing list is at TreeCPAN@googlegroups.com. I also read http://www.perlmonks.com on a daily basis.

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.

syntax highlighting: