Data::Grove::Parent (3pm)

 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]);

Data::Grove::Parent is an extension to Data::Grove that adds `\*(C`Parent\*(C'' and `\*(C`Raw\*(C'' 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 (`\*(C`Parent\*(C'') and a reference to the original Data::Grove object (`\*(C`Raw\*(C''). 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 `\*(C`delete\*(C'' 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 collect them normally.

A secondary use is to allow you to reuse grove or property set fragments in multiple trees. \s-1WARNING:\s0 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.

`\*(C`root()\*(C'' returns the root node if `$object' is a `\*(C`Data::Grove::Parent\*(C'' object. `\*(C`rootpath()\*(C'' returns an array of all the nodes between and including the root node and `$object'. `\*(C`add_magic()\*(C'' returns a \*(C`Data::Grove::Parent\*(C' object with `$object' as it's `\*(C`Raw\*(C'' object. If `$parent' is given, that becomes the tied object's parent object.

Ken MacLeod, [email protected]

perl\|(1), Data::Grove\|(3)