.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Data::Grove 3pm"
.TH Data::Grove 3pm "2003-10-21" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Data::Grove \-\- support for deeply nested structures
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Data::Grove;
\&
\& $object = MyPackage\->new;
\&
\& package MyPackage;
\& @ISA = qw{Data::Grove};
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Data::Grove\*(C'\fR provides support for deeply nested tree or graph
structures.  \f(CW\*(C`Data::Grove\*(C'\fR is intended primarily for Perl module
authors writing modules with many types or classes of objects that
need to be manipulated and extended in a consistent and flexible way.
.PP
\&\f(CW\*(C`Data::Grove\*(C'\fR is best used by creating a core set of ``data'' classes
and then incrementally adding functionality to the core data classes
by using ``extension'' modules.  One reason for this design is so that
the data classes can be swapped out and the extension modules can work
with new data sources.  For example, these other data sources could be
disk-based, network-based or built on top of a relational database.
.PP
Two extension modules that come with \f(CW\*(C`Data::Grove\*(C'\fR are
\&\f(CW\*(C`Data::Grove::Parent\*(C'\fR and \f(CW\*(C`Data::Grove::Visitor\*(C'\fR.
\&\f(CW\*(C`Data::Grove::Parent\*(C'\fR adds a `\f(CW\*(C`Parent\*(C'\fR' property to grove objects
and implements a `\f(CW\*(C`root\*(C'\fR' method to grove objects to return the root
node of the tree from anywhere in the tree and a `\f(CW\*(C`rootpath\*(C'\fR' method
to return a list of nodes between the root node and ``this'' node.
\&\f(CW\*(C`Data::Grove::Visitor\*(C'\fR adds callback methods `\f(CW\*(C`accept\*(C'\fR' and
`\f(CW\*(C`accept_name\*(C'\fR' that call your handler or receiver module back by
object type name or the object's name.
.PP
\&\f(CW\*(C`Data::Grove\*(C'\fR objects do not contain parent references, Perl garbage
collection will delete them when no longer referenced and
sub-structures can be shared among several structures.
\&\f(CW\*(C`Data::Grove::Parent\*(C'\fR is used to create temporary objects with parent
pointers.
.PP
Properties of data classes are accessed directly using Perl's hash
functions (i.e. `\f(CW\*(C`$object\->{Property}\*(C'\fR').  Extension modules may
also define properties that they support or use, for example
Data::Grove::Parent adds `\f(CW\*(C`Parent\*(C'\fR' and `\f(CW\*(C`Raw\*(C'\fR' properties and
Visitor depends on `\f(CW\*(C`Name\*(C'\fR' and `\f(CW\*(C`Content\*(C'\fR' properties.
.PP
See the module \f(CW\*(C`XML::Grove\*(C'\fR for an example implementation of
\&\f(CW\*(C`Data::Grove\*(C'\fR.
.SH "METHODS"
.IX Header "METHODS"
.IP "new( \s-1PROPERTIES\s0 )" 4
.IX Item "new( PROPERTIES )"
Return a new object blessed into the SubClass, with the given
properties.  \s-1PROPERTIES\s0 may either be a list of key/value pairs, a
single hash containing key/value pairs, or an existing \f(CW\*(C`Data::Grove\*(C'\fR
object.  If an existing \f(CW\*(C`Data::Grove\*(C'\fR is passed to `\f(CW\*(C`new()\*(C'\fR', a
shallow copy of that object will be returned.  A shallow copy means
that you are returned a new object, but all of the objects underneath
still refer to the original objects.
.SH "AUTHOR"
.IX Header "AUTHOR"
Ken MacLeod, ken@bitsko.slc.ut.us
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1)