data::grove(3pm) [debian man page]

Data::Grove(3pm)					User Contributed Perl Documentation					  Data::Grove(3pm)

NAME

       Data::Grove -- support for deeply nested structures

SYNOPSIS

	use Data::Grove;

	$object = MyPackage->new;

	package MyPackage;
	@ISA = qw{Data::Grove};

DESCRIPTION

       "Data::Grove" provides support for deeply nested tree or graph structures.  "Data::Grove" 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.

       "Data::Grove" 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.

       Two extension modules that come with "Data::Grove" are "Data::Grove::Parent" and "Data::Grove::Visitor".  "Data::Grove::Parent" adds a
       `"Parent"' property to grove objects and implements a `"root"' method to grove objects to return the root node of the tree from anywhere in
       the tree and a `"rootpath"' method to return a list of nodes between the root node and ``this'' node.  "Data::Grove::Visitor" adds callback
       methods `"accept"' and `"accept_name"' that call your handler or receiver module back by object type name or the object's name.

       "Data::Grove" 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.  "Data::Grove::Parent" is used to create temporary objects with parent pointers.

       Properties of data classes are accessed directly using Perl's hash functions (i.e. `"$object->{Property}"').  Extension modules may also
       define properties that they support or use, for example Data::Grove::Parent adds `"Parent"' and `"Raw"' properties and Visitor depends on
       `"Name"' and `"Content"' properties.

       See the module "XML::Grove" for an example implementation of "Data::Grove".

METHODS

       new( PROPERTIES )
	   Return a new object blessed into the SubClass, with the given properties.  PROPERTIES may either be a list of key/value pairs, a single
	   hash containing key/value pairs, or an existing "Data::Grove" object.  If an existing "Data::Grove" is passed to `"new()"', 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.

AUTHOR

       Ken MacLeod, ken@bitsko.slc.ut.us

SEE ALSO

       perl(1)

perl v5.10.1							    2003-10-21							  Data::Grove(3pm)

Data::Grove::Visitor(3pm)				User Contributed Perl Documentation				 Data::Grove::Visitor(3pm)

NAME

       Data::Grove::Visitor - add visitor/callback methods to Data::Grove objects

SYNOPSIS

	use Data::Grove::Visitor;

	@results = $object->accept ($visitor, ...);
	@results = $object->accept_name ($visitor, ...);
	@results = $object->children_accept ($visitor, ...);
	@results = $object->children_accept_name ($visitor, ...);

DESCRIPTION

       Data::Grove::Visitor adds visitor methods (callbacks) to Data::Grove objects.  A ``visitor'' is a class (a package) you write that has
       methods (subs) corresponding to the objects in the classes being visited.  You use the visitor methods by creating an instance of your
       visitor class, and then calling `"accept($my_visitor)"' on the top-most object you want to visit, that object will in turn call your
       visitor back with `"visit_OBJECT"', where OBJECT is the type of object.

       There are several forms of `"accept"'.  Simply calling `"accept"' calls your package back using the object type of the object you are
       visiting.  Calling `"accept_name"' on an element object calls you back with `"visit_name_NAME"' where NAME is the tag name of the element,
       on all other objects it's as if you called `"accept"'.

       All of the forms of `"accept"' return a concatenated list of the result of all `"visit"' methods.

       `"children_accept"' calls `"accept"' on each of the children of the element.  This is generally used in element callbacks to recurse down
       into the element's children, you don't need to get the element's contents and call `"accept"' on each item.  `"children_accept_name"' does
       the same but calling `"accept_name"' on each of the children.  `"attr_accept"' calls `"accept"' on each of the objects in the named
       attribute.

       Refer to the documentation of the classes you are visiting (XML::Grove, etc.) for the type names (`"element"', `"document"', etc.) of the
       objects it implements.

RESERVED NAMES

       The hash keys `"Contents"' and `"Name"' are used to indicate objects with children (for `"children_accept"') and named objects (for
       `"accept_name"').

NOTES

       These are random ideas that haven't been implemented yet:

       o   Several objects fall into subclasses, or you may want to be able to subclass a visited object and still be able to tell the difference.
	   In SGML::Grove I had used the package name in the callback (`"visit_SGML_Element"') instead of a generic name (`"visit_element"').  The
	   idea here would be to try calling `"visit_PACKAGE"' with the most specific class first, then try superclasses, and lastly to try the
	   generic.

AUTHOR

       Ken MacLeod, ken@bitsko.slc.ut.us

SEE ALSO

       perl(1), Data::Grove

       Extensible Markup Language (XML) <http://www.w3c.org/XML>

perl v5.10.1							    2003-10-21						 Data::Grove::Visitor(3pm)