NAME

TreeNode - A perl module for building node trees


SYNOPSIS

use TreeNode;

$node1 = new TreeNode(); $node1->foo_(``bar''); print ``Value of field 'foo' is: ''.$node1->foo_().``\n'';

# Add some children $node2 = new TreeNode(); $node2->name_(``First''); $node3 = new TreeNode(); $node3->name_(``Second''); $node1->pushChild($node2); $node1->pushChild($node3);

# List out some field of the children foreach $node ($node1->listChildren()) { print ``Child called: ''.$node->name_().``\n''; }

# Remove the last added child $node1->popChild();

#Another way of listing children while ($node = $node1->eachChild()) { print ``Child called: ''.$node->name_().``\n''; }


DESCRIPTION

This module allows generic tree-like structures to be built up using a TreeNode as the basic building block. Each node can have zero or more child nodes and can also contain a list of arbitrary fields. Each node is created externally and then added as the child of an existing node with the pushChild() method. Children can also be listed using eachChild() and listChildren(), and removed with popChild().

When a node is first created it has no fields. To create a new field you simply set its value. A field is accessed via a method which is the name of the field with an underscore (_) appended. For examples, see the synopsis above. Fields can be set by using the accessor method with a single argument which is the new value for that field. They can be read using the same method with no arguments. They can also be listed with eachField() and listFields().


METHODS

new
The constructor takes no arguments and returns a reference to a new TreeNode object with no fields initialised and no children.

pushChild
This method is for adding children to the node. It takes a reference to a TreeNode as an argument and adds it to the list of children. It returns the reference that it was passed. There is nothing to stop you placing any other scalar values as children of a TreeNode, but this will cause the display method to fail if it can't access a method called listChildren on each child node. Also, external code may rely on the children of TreeNodes also being TreeNodes.

popChild
The inverse of pushChild, popChild removes the most recently added child node from the list and returns it.

eachChild
Works in a similar manner to the each function for hashes. When first called it returns the first child. Each subsequent invocation returns the next child, and when there are no more children undef is returned. Just like the each function, changing the list of children whilst iterating through it can cause elements to be skipped or repeated. The iterator can be reset by iterating through the whole list or calling eachChild with an argument - in this case its only function will be to reset the iterator. Note that unlike hashes, children always come back in the order in which they were added (but removing a child with popChild then adding it back with pushChild will result in it being at the end of the list wherever it was before it was removed).

listChildren
Returns a list of all children of the current node.

eachField
This method iterates through the fields of a node in exactly the same way as the each function iterates through a hash. It's operation should be identical.

listFields
The operation of this method should be identical to that of the keys function applied to hashes, except that it lists the fields of the node.

deleteField
Removes a field from the list associated with a node. Note that assigning a field the undefined value does NOT remove it - that is only possible with this method. Further assignments to the field deleted will cause it to reappear with the new value as normal.

display
Prints a hierarchical listing of this node and all its children to the currently selected filehandle. This includes all fields.

field_
Fields can be accessed by using a method consisting of the field name followed by an underscore (_). Passing an argument to the method sets the value of the field to that of the argument, passing no argument causes the current value to be returned. Setting the value of a field that doesn't exist causes it to be created with the new value. Retrieving the value of a field that hasn't been created returns undef.

findNode
This method makes it possible to locate a specific node by supplying a ``path'' to that node. A path is a sequence of strings for a particular field which specify a route from the root node to the required one. For example, a set of nodes may all have a ``name'' attribute. If the root node is called ``root'', which has a child called ``foo'' which, in turn, has a child ``bar'', then the path to the last node would be ``root foo bar''. The call to findNode would take the form:
    $myRoot->findNode("name", "root foo bar");

findNode can also take an optional third argument specifying the pattern to use to split the second argument - this defaults to /\s+/. If the specified node isn't found, undef is returned.


AUTHOR

Andrew Pearce