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

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 including 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

SEE ALSO

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