Data::Grove::Parent - phpMan

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 AT bitsko.us

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