$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 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 collect 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.