.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "MultiNode 3pm"
.TH MultiNode 3pm "2003-05-27" "perl v5.10.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MultiNode.pm  \-\- a multi node tree object.  Most useful for 
modeling heirarchial data structures.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&  use Tree::MultiNode;
\&  use strict; 
\&  use warnings;
\&  my $tree   = new Tree::MultiNode;
\&  my $handle = new Tree::MultiNode::Handle($tree);
\&
\&  $handle\->set_key("top");
\&  $handle\->set_value("level");
\&
\&  $handle\->add_child("child","1");
\&  $handle\->add_child("child","2");
\&
\&  $handle\->first();
\&  $handle\->down();
\&
\&  $handle\->add_child("grandchild","1\-1");
\&  $handle\->up();
\&
\&  $handle\->last();
\&  $handle\->down();
\&
\&  $handle\->add_child("grandchild","2\-1");
\&  $handle\->up();
\&  
\&  $handle\->top();
\&  &dump_tree($handle);
\&
\&  my $depth = 0;
\&  sub dump_tree
\&  {
\&    ++$depth;
\&    my $handle = shift;
\&    my $lead = \*(Aq \*(Aq x ($depth*2);
\&    my($key,$val);
\&  
\&    ($key,$val) = $handle\->get_data();
\&
\&    print $lead, "key:   $key\en";
\&    print $lead, "val:   $val\en";
\&    print $lead, "depth: $depth\en";
\&  
\&    my $i;
\&    for( $i = 0; $i < scalar($handle\->children); ++$i ) {
\&      $handle\->down($i);
\&        &dump_tree($handle);
\&      $handle\->up();
\&    }
\&    \-\-$depth;
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Tree::MultiNode, Tree::MultiNode::Node, and MultiNode::Handle are objects 
modeled after \*(C+ classes that I had written to help me model heirarchical 
information as datastructures (such as the relationships between records in 
an \s-1RDBMS\s0).  The tree is basicly a list of lists type data structure, where 
each node has a key, a value, and a list of children.  The tree has no
internal sorting, though all operations perserve the order of the child 
nodes.
.Sh "Creating a Tree"
.IX Subsection "Creating a Tree"
The concept of creating a handle based on a tree lets you have multiple handles
into a single tree without having to copy the tree.  You have to use a handle
for all operations on the tree (other than construction).
.PP
When you first construct a tree, it will have a single empty node.  When you
construct a handle into that tree, it will set the top node in the tree as 
it's current node.
.PP
.Vb 2
\&  my $tree   = new Tree::MultiNode;
\&  my $handle = new Tree::MultiNode::Handle($tree);
.Ve
.Sh "Using a Handle to Manipulate the Tree"
.IX Subsection "Using a Handle to Manipulate the Tree"
At this point, you can set the key/value in the top node, or start adding
child nodes.
.PP
.Vb 2
\&  $handle\->set_key("blah");
\&  $handle\->set_value("foo");
\&
\&  $handle\->add_child("quz","baz");
\&  # or
\&  $handle\->add_child();
.Ve
.PP
add_child can take 3 paramters \*(-- a key, a value, and a 
position.  The key and value will set the key/value of the child on construction.
If pos is passed, the new child will be inserted into the list of children.
.PP
To move the handle so it points at a child (so you can start manipulating that
child), there are a series of methods to call:
.PP
.Vb 6
\&  $handle\->first();   # sets the current child to the first in the list
\&  $handle\->next();    # sets the next, or first if there was no next
\&  $handle\->prev();    # sets the previous, or last if there was no next
\&  $handle\->last();    # sets to the last child
\&  $handle\->down();    # positions the handle\*(Aqs current node to the 
\&                      # current child
.Ve
.PP
To move back up, you can call the method up:
.PP
.Vb 1
\&  $handle\->up();      # moves to this node\*(Aqs parent
.Ve
.PP
\&\fIup()\fR will fail if the current node has no parent node.  Most of the member 
functions return either undef to indicate failure, or some other value to 
indicate success.
.ie n .Sh "$Tree::MultiNode::debug"
.el .Sh "\f(CW$Tree::MultiNode::debug\fP"
.IX Subsection "$Tree::MultiNode::debug"
If set to a true value, it enables debugging output in the code.  This will 
likely be removed in future versions as the code becomes more stable.
.SH "API REFERENCE"
.IX Header "API REFERENCE"
.Sh "Tree::MultiNode"
.IX Subsection "Tree::MultiNode"
The tree object.
.Sh "Tree::MultiNode::new"
.IX Subsection "Tree::MultiNode::new"
.Vb 2
\&  @param    package name or tree object [scalar]
\&  @returns  new tree object
.Ve
.PP
Creates a new Tree.  The tree will have a single top level node when created.
The first node will have no value (undef) in either it's key or it's value.
.PP
.Vb 1
\&  my $tree = new Tree::MultiNode;
.Ve
.Sh "Tree::MultiNode::Node"
.IX Subsection "Tree::MultiNode::Node"
Please note that the Node object is used internaly by the MultiNode object.  
Though you have the ability to interact with the nodes, it is unlikely that
you should need to.  That being said, the interface is documented here anyway.
.Sh "Tree::MultiNode::Node::new"
.IX Subsection "Tree::MultiNode::Node::new"
.Vb 3
\&  new($)
\&    @param    package name or node object to clone [scalar]
\&    @returns  new node object
\&
\&  new($$)
\&    @param    key   [scalar]
\&    @param    value [scalar]
\&    @returns  new node object
.Ve
.PP
Creates a new Node.  There are three behaviors for new.  A constructor with no
arguments creates a new, empty node.  A single argument of another node object
will create a clone of the node object.  If two arguments are passed, the first
is stored as the key, and the second is stored as the value.
.PP
.Vb 4
\&  # clone an existing node
\&  my $node = new Tree::MultiNode::Node($oldNode);
\&  # or
\&  my $node = $oldNode\->new();
\&
\&  # create a new node
\&  my $node = new Tree::MultiNode::Node;
\&  my $node = new Tree::MultiNode::Node("fname");
\&  my $node = new Tree::MultiNode::Node("fname","Larry");
.Ve
.Sh "Tree::MultiNode::Node::key"
.IX Subsection "Tree::MultiNode::Node::key"
.Vb 2
\&  @param     key [scalar]
\&  @returns   the key [scalar]
.Ve
.PP
Used to set, or retreive the key for a node.  If a parameter is passed,
it sets the key for the node.  The value of the key member is alwyays
returned.
.PP
.Vb 1
\&  print $node3\->key(), "\en";    # \*(Aqfname\*(Aq
.Ve
.Sh "Tree::MultiNode::Node::value"
.IX Subsection "Tree::MultiNode::Node::value"
.Vb 2
\&  @param    the value to set [scalar]
\&  @returns  the value [scalar]
.Ve
.PP
Used to set, or retreive the value for a node.  If a parameter is passed,
it sets the value for the node.  The value of the value member is alwyays
returned.
.PP
.Vb 1
\&  print $node3\->value(), "\en";   # \*(AqLarry\*(Aq
.Ve
.Sh "Tree::MultiNode::Node::clear_key"
.IX Subsection "Tree::MultiNode::Node::clear_key"
.Vb 1
\&  @returns  the deleted key
.Ve
.PP
Clears the key member bu deleting it.
.PP
.Vb 1
\&  $node3\->clear_key();
.Ve
.Sh "Tree::MultiNode::Node::clear_value"
.IX Subsection "Tree::MultiNode::Node::clear_value"
.Vb 1
\&  @returns  the deleted value
.Ve
.PP
Clears the value member bu deleting it.
.PP
.Vb 1
\&  $node3\->clear_value();
.Ve
.Sh "Tree::MultiNode::Node::children"
.IX Subsection "Tree::MultiNode::Node::children"
.Vb 1
\&  @returns  reference to children [array reference]
.Ve
.PP
Returns a refrence to the array that contains the children of the
node object.
.PP
.Vb 1
\&  $array_ref = $node3\->children();
.Ve
.Sh "Tree::MultiNode::Node::child_keys Tree::MultiNode::Node::child_values Tree::MultiNode::Node::child_kv_pairs"
.IX Subsection "Tree::MultiNode::Node::child_keys Tree::MultiNode::Node::child_values Tree::MultiNode::Node::child_kv_pairs"
These functions return arrays consisting of the appropriate data
from the child nodes.
.PP
.Vb 3
\&  my @keys     = $handle\->child_keys();
\&  my @vals     = $handle\->child_values();
\&  my %kv_pairs = $handle\->child_kv_pairs();
.Ve
.Sh "Tree::MultiNode::Node::child_key_positions"
.IX Subsection "Tree::MultiNode::Node::child_key_positions"
This function returns a hashtable that consists of the
child keys as the hash keys, and the position in the child
array as the value.  This allows for a quick and dirty way
of looking up the position of a given key in the child list.
.PP
.Vb 1
\&  my %h = $node\->child_key_positions();
.Ve
.Sh "Tree::MultiNode::Node::parent"
.IX Subsection "Tree::MultiNode::Node::parent"
Returns a refrence to the parent node of the current node.
.PP
.Vb 1
\&  $node_parent = $node3\->parent();
.Ve
.Sh "Tree::MultiNode::Node::dump"
.IX Subsection "Tree::MultiNode::Node::dump"
Used for diagnostics, it prints out the members of the node.
.PP
.Vb 1
\&  $node3\->dump();
.Ve
.Sh "Tree::MultiNode::Handle"
.IX Subsection "Tree::MultiNode::Handle"
Handle is used as a 'pointer' into the tree.  It has a few attributes that it keeps
track of.  These are:
.PP
.Vb 4
\&  1. the top of the tree 
\&  2. the current node
\&  3. the current child node
\&  4. the depth of the current node
.Ve
.PP
The top of the tree never changes, and you can reset the handle to point back at
the top of the tree by calling the \fItop()\fR method.
.PP
The current node is where the handle is 'pointing' in the tree.  The current node
is changed with functions like \fItop()\fR, \fIdown()\fR, and \fIup()\fR.
.PP
The current child node is used for traversing downward into the tree.  The members
\&\fIfirst()\fR, \fInext()\fR, \fIprev()\fR, \fIlast()\fR, and \fIposition()\fR can be used to set the current child,
and then traverse down into it.
.PP
The depth of the current node is a measure of the length of the path
from the top of the tree to the current node, i.e. the top of the node
has a depth of 0, each of its children has a depth of 1, etc.
.Sh "Tree::MultiNode::Handle::New"
.IX Subsection "Tree::MultiNode::Handle::New"
Constructs a new handle.  You must pass a tree object to Handle::New.
.PP
.Vb 2
\&  my $tree   = new Tree::MultiNode;
\&  my $handle = new Tree::MultiNode::Handle($tree);
.Ve
.Sh "Tree::MultiNode::Handle::tree"
.IX Subsection "Tree::MultiNode::Handle::tree"
Returns the tree that was used to construct the node.  Useful if you're
trying to create another node into the tree.
.PP
.Vb 1
\&  my $handle2 = new Tree::MultiNode::Handle($handle\->tree());
.Ve
.Sh "Tree::MultiNode::Handle::get_data"
.IX Subsection "Tree::MultiNode::Handle::get_data"
Retrieves both the key, and value (as an array) for the current node.
.PP
.Vb 1
\&  my ($key,$val) = $handle\->get_data();
.Ve
.Sh "Tree::MultiNode::Handle::get_key"
.IX Subsection "Tree::MultiNode::Handle::get_key"
Retrieves the key for the current node.
.PP
.Vb 1
\&  $key = $handle\->get_key();
.Ve
.Sh "Tree::MultiNode::Handle::set_key"
.IX Subsection "Tree::MultiNode::Handle::set_key"
Sets the key for the current node.
.PP
.Vb 1
\&  $handle\->set_key("lname");
.Ve
.Sh "Tree::MultiNode::Handle::get_value"
.IX Subsection "Tree::MultiNode::Handle::get_value"
Retreives the value for the current node.
.PP
.Vb 1
\&  $val = $handle\->get_value();
.Ve
.Sh "Tree::MultiNode::Handle::set_value"
.IX Subsection "Tree::MultiNode::Handle::set_value"
Sets the value for the current node.
.PP
.Vb 1
\&  $handle\->set_value("Wall");
.Ve
.Sh "Tree::MultiNode::Handle::get_child"
.IX Subsection "Tree::MultiNode::Handle::get_child"
get_child takes an optional paramater which is the position of the child
that is to be retreived.  If this position is not specified, get_child 
attempts to return the current child.  get_child returns a Node object.
.PP
.Vb 1
\&  my $child_node = $handle\->get_child();
.Ve
.Sh "Tree::MultiNode::Handle::add_child"
.IX Subsection "Tree::MultiNode::Handle::add_child"
This member adds a new child node to the end of the array of children for the
current node.  There are three optional parameters:
.PP
.Vb 3
\&  \- a key
\&  \- a vlaue
\&  \- a position
.Ve
.PP
If passed, the key and value will be set in the new child.  If a position is 
passed, the new child will be inserted into the current array of children at
the position specified.
.PP
.Vb 3
\&  $handle\->add_child();                    # adds a blank child
\&  $handle\->add_child("language","perl");   # adds a child to the end
\&  $handle\->add_child("language","C++",0);  # adds a child to the front
.Ve
.Sh "Tree::MultiNode::Handle::depth"
.IX Subsection "Tree::MultiNode::Handle::depth"
Gets the depth for the current node.
.PP
.Vb 1
\&  my $depth = $handle\->depth();
.Ve
.Sh "Tree::MultiNode::Handle::select"
.IX Subsection "Tree::MultiNode::Handle::select"
Sets the current child via a specified value \*(-- basicly it iterates
through the array of children, looking for a match.  You have to 
supply the key to look for, and optionaly a sub ref to find it.  The 
default for this sub is
.PP
.Vb 1
\&  sub { return shift eq shift; }
.Ve
.PP
Which is sufficient for testing the equality of strings (the most common
thing that I think will get stored in the tree).  If you're storing multiple
datatypes as keys, you'll have to write a sub that figures out how to 
perform the comparisions in a sane manner.
.PP
The sub ref should take 2 args, and compare them \*(-- return false if they
don't match, and true if they do.
.PP
.Vb 1
\&  $handle\->select(\*(Aqlname\*(Aq, sub { return shift eq shift; } );
.Ve
.Sh "Tree::MultiNode::Handle::position"
.IX Subsection "Tree::MultiNode::Handle::position"
Sets, or retreives the current child position.
.PP
.Vb 2
\&  print "curr child pos is: ", $handle\->position(), "\en";
\&  $handle\->position(5);    # sets the 6th child as the current child
.Ve
.Sh "Tree::MultiNode::Handle::first Tree::MultiNode::Handle::next Tree::MultiNode::Handle::prev Tree::MultiNode::Handle::last"
.IX Subsection "Tree::MultiNode::Handle::first Tree::MultiNode::Handle::next Tree::MultiNode::Handle::prev Tree::MultiNode::Handle::last"
These functions manipulate the current child member.  \fIfirst()\fR sets the first
child as the current child, while \fIlast()\fR sets the last.  \fInext()\fR, and \fIprev()\fR will
move to the next/prev child respectivly.  If there is no current child node,
\&\fInext()\fR will have the same effect as \fIfirst()\fR, and \fIprev()\fR will operate as \fIlast()\fR.
\&\fIprev()\fR fails if the current child is the first child, and \fInext()\fR fails if the
current child is the last child \*(-- i.e. they do not wrap around.
.PP
These functions will fail if there are no children for the current node.
.PP
.Vb 4
\&  $handle\->first();  # sets to the 0th child
\&  $handle\->next();   # to the 1st child
\&  $handle\->prev();   # back to the 0th child
\&  $handle\->last();   # go straight to the last child.
.Ve
.Sh "Tree::MultiNode::Handle::down"
.IX Subsection "Tree::MultiNode::Handle::down"
\&\fIdown()\fR moves the handle to point at the current child node.  It fails
if there is no current child node.  When \fIdown()\fR is called, the current
child becomes invalid (undef).
.PP
.Vb 1
\&  $handle\->down();
.Ve
.Sh "Tree::MultiNode::Handle::up"
.IX Subsection "Tree::MultiNode::Handle::up"
\&\fIdown()\fR moves the handle to point at the parent of the current node.  It fails
if there is no parent node.  When \fIup()\fR is called, the current child becomes 
invalid (undef).
.PP
.Vb 1
\&  $handle\->up();
.Ve
.Sh "Tree::MultiNode::Handle::top"
.IX Subsection "Tree::MultiNode::Handle::top"
Resets the handle to point back at the top of the tree.  
When \fItop()\fR is called, the current child becomes invalid (undef).
.PP
.Vb 1
\&  $handle\->top();
.Ve
.Sh "Tree::MultiNode::Handle::children"
.IX Subsection "Tree::MultiNode::Handle::children"
This returns an array of Node objects that represents the children of the
current Node.  Unlike \fINode::children()\fR, the array \fIHandle::children()\fR is not
a refrnece to an array, but an array.  Useful if you need to iterate through
the children of the current node.
.PP
.Vb 4
\&  print "There are: ", scalar($handle\->children()), " children\en";
\&  foreach $child ($handle\->children()) {
\&    print $child\->key(), " : ", $child\->value(), "\en";
\&  }
.Ve
.Sh "Tree::MultiNode::Handle::child_key_positions"
.IX Subsection "Tree::MultiNode::Handle::child_key_positions"
This function returns a hashtable that consists of the
child keys as the hash keys, and the position in the child
array as the value.  This allows for a quick and dirty way
of looking up the position of a given key in the child list.
.PP
.Vb 1
\&  my %h = $handle\->child_key_positions();
.Ve
.Sh "Tree::MultiNode::Handle::get_child_key"
.IX Subsection "Tree::MultiNode::Handle::get_child_key"
Returns the key at the specified position, or from the corresponding child
node.
.PP
.Vb 1
\&  my $key = $handle\->get_child_key();
.Ve
.Sh "Tree::MultiNode::Handle::get_child_value"
.IX Subsection "Tree::MultiNode::Handle::get_child_value"
Returns the value at the specified position, or from the corresponding child
node.
.PP
.Vb 1
\&  my $value = $handle\->get_child_value();
.Ve
.Sh "Tree::MultiNode::Handle::remove_child"
.IX Subsection "Tree::MultiNode::Handle::remove_child"
Returns \fITree::MultiNode::Node::child_kv_paris()\fR for the
current node for this handle.
.PP
.Vb 1
\&  my %pairs = $handle\->kv_pairs();
.Ve
.Sh "Tree::MultiNode::Handle::remove_child"
.IX Subsection "Tree::MultiNode::Handle::remove_child"
.Sh "Tree::MultiNode::Handle::child_keys"
.IX Subsection "Tree::MultiNode::Handle::child_keys"
Returns the keys from the current node's children.
Returns undef if there is no currnet node.
.Sh "Tree::MultiNode::Handle::traverse"
.IX Subsection "Tree::MultiNode::Handle::traverse"
.Vb 4
\&  $handle\->traverse(sub {
\&    my $h = shift;
\&    printf "%sk: %s v: %s\en",(\*(Aq  \*(Aq x $handle\->depth()),$h\->get_data();
\&  });
.Ve
.PP
Traverse takes a subroutine reference, and will visit each node of the tree,
starting with the node the handle currently points to, recrusivly down from the
current position of the handle.  Each time the subroutine is called, it will be
passed a handle which points to the node to be visited.  Any additional
arguments after the sub ref will be passed to the traverse function _before_
the handle is passed.  This should allow you to pass constant arguments to the
sub ref.
.PP
Modifying the node that the handle points to will cause traverse to work
from the new node forward.
.Sh "Tree::MultiNode::Handle::traverse or to have the subref to be a method on an object (and still pass the object's 'self' to the method)."
.IX Subsection "Tree::MultiNode::Handle::traverse or to have the subref to be a method on an object (and still pass the object's 'self' to the method)."
.Vb 1
\&  $handle\->traverse( \e&Some::Object::method, $obj, $const1, \e%const2 );
\&
\&  ...
\&  sub method
\&  {
\&    my $handle = pop;
\&    my $self   = shift;
\&    my $const1 = shift;
\&    my $const2 = shift;
\&    # do something
\&  }
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Algorithms in \*(C+
   Robert Sedgwick
   Addison Wesley 1992
   \s-1ISBN\s0 0201510596
.PP
The Art of Computer Programming  Volume 1 Fundamental Algorithms
  third edition, Donald E. Knuth
.SH "AUTHORS"
.IX Header "AUTHORS"
Kyle R. Burton mortis@voicenet.com (initial version, and maintenence)
Daniel X. Pape dpape@canis.uiuc.edu (see Changes file from the source
archive), Eric Joanis <joanis@cs.toronto.edu>
.SH "BUGS"
.IX Header "BUGS"
\&\- There is currently no way to remove a child node.