TreeNode - A perl module for building node trees
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'';
}
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().
- 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.
Andrew Pearce