data::grove::parent(3)
NAME
Data::Grove::Parent - provide parent properties to
Data::Grove objects
SYNOPSIS
use Data::Grove::Parent; $root = $object->root; $rootpath = $object->rootpath; $tied = $object->add_magic([ $parent ]); $node = Data::Grove::Parent->new($hash [, $parent]); $node_list = Data::Grove::ParentList->new($array [, $parent]);
DESCRIPTION
Data::Grove::Parent is an extension to Data::Grove that
adds `"Parent"' and `"Raw"' properties to Data::Grove
objects and methods for returning the root node of a
grove, a list of nodes between and including the root node
and the current node, and a method that creates parented
nodes.
Data::Grove::Parent works by creating a Perl ``tied''
object that contains a parent reference (`"Parent"') and a
reference to the original Data::Grove object (`"Raw"').
Tying-magic is used so that every time you reference the
Data::Grove::Parent object it actually references the
underlying raw object.
When you retrieve a list or a property of the Raw object,
Data::Grove::Parent automatically adds magic to the
returned list or node. This means you only call
`add_magic()' once to create the first Data::Grove::Parent
object and then use the grove objects like you normally
would.
The most obvious use of this is so you don't have to call
a `"delete"' method when you want to release a grove or
part of a grove; since Data::Grove and Data::Grove::Parent
objects have no cyclic references, Perl can garbage col
lect them normally.
A secondary use is to allow you to reuse grove or property
set fragments in multiple trees. WARNING: Data::Grove
currently does not protect you from creating your own
cyclic references! This could lead to infinite loops if
you don't take care to avoid them.
METHODS
- $object->root()
$object->rootpath() - `"root()"' returns the root node if `$object' is a
`"Data::Grove::Parent"' object. `"rootpath()"'
returns an array of all the nodes between and includ
ing the root node and `$object'. - $tied = $object->add_magic([ $parent ])
- `"add_magic()"' returns a "Data::Grove::Parent" object
with `$object' as it's `"Raw"' object. If `$parent'
is given, that becomes the tied object's parent
object.
AUTHOR
Ken MacLeod, ken@bitsko.slc.ut.us