# 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@bitsko.slc.ut.us>

## SEE ALSO
    [perl(1)], Data::[Grove(3)]