$Id: README,v 1.12 1999/09/03 21:41:00 kmacleod Exp $


			      XML::Grove

	    A Perl 5 module providing simple access to the
       information set of parsed XML, HTML, or SGML instances.


                             Ken MacLeod
                         ken@bitsko.slc.ut.us

INTRODUCTION

    XML::Grove provides simple access to the information set of parsed
    XML, HTML, or SGML instances using a tree of Perl hashes.  This
    package also includes several extensions to XML::Grove that
    provide the following:

      * returning element contents as a string
      * returning element contents as XML, HTML, or Canonical XML
      * processing entire groves using the visitor pattern
      * processing entire groves using PerlSAX
      * running a filter over all nodes in the grove
      * substituting values into an XML template grove
      * indexing a grove by ID or other attributes
      * accessing elements and objects via URL-like paths
      * create grove objects using an easy shorthand

    See ``Using XML::Grove'' for an introduction to using XML::Grove.

    See the file Changes for user-visible changes.  See the `examples'
    directory for examples of using XML::Grove.  POD documentation is
    included in all non-alpha modules and scripts.  You should also be
    able to use the 'perldoc' utility to extract documentation from
    the module files directly.  HTML formatted docs are available at
    the XML::Grove home page <http://bitsko.slc.ut.us/XML-Grove/>.

    Newer versions of this module can be found on CPAN at
    <http://www.perl.com/CPAN/modules/by-module/XML/>.  To join the
    Perl-XML mailing list, send an email message to
    ListManager@ActiveState.com with the following text in the body:
    Subscribe Perl-XML

    Copyright (C) 1998, 1999 Ken MacLeod
    XML::Grove is distributed under the same terms as Perl.
    See the file COPYING for distribution terms.

MODULES

    The following modules are marked with their release status:

    STABLE -- has been in use for a while with few or no outstanding
              bugs
    BETA   -- interfaces are stable but there may still be bugs
    ALPHA  -- interfaces are changing, there may be lots of bugs, and
              there may not be docs available yet

    XML::Grove                 STABLE
        Declares all the XML::Grove object classes and provides a
        `new()' method for basic object creation.

    XML::Grove::Builder        STABLE
        Builds entires groves from *ML instances using PerlSAX parsers.

    XML::Grove::AsString       STABLE
        Adds `as_string()' methods to XML::Grove objects to return the
        character data of the object and any elements contained in the
        object.  The string may optionally be filtered, have entity
        references mapped to different replacement text, or written to
        a file.

    XML::Grove::AsCanonXML     STABLE
        Adds `as_canon_xml()' methods to XML::Grove objects to return
        a string or write objects to a file in ``Canonical XML''
        format.

    Data::Grove::Visitor       STABLE  (in libxml-perl)
        Processes or ``walks' an entire grove by making callbacks to a
        class you define.  Visitor calls your class once for every
        grove object (no start/end calls), allows arguments to be
        passed down during the walk, and you can stop any further
        processing below an element or other container.

    XML::Grove::PerlSAX        STABLE
        Processes an entire grove by making callbacks to a class you
        define using the PerlSAX API.  Calls start/end methods for
        container objects.  PerlSAX can be used to provide input to
        SAX filters.

    Data::Grove::Parent        STABLE  (in libxml-perl)
        Adds a Parent property and `root()' and `rootpath()' methods
        to grove objects.

    XML::Grove::Factory        BETA
        Provides objects and functions to easily create groves
        directly from Perl.

    XML::Grove::IDs            BETA
        Return a hash mapping ID or other attributes to the elements
        where they are defined.

    XML::Grove::Path           BETA
        Return an object in the grove using URL-like paths, e.g.
        `/html/head/title'.

    XML::Grove::Sub            BETA
        Run a sub or filter across all objects in the grove.

    XML::Grove::XPointer       DEPRECATED
        Implements a `xp_child()' method used by XML::Grove::Path.
        Does _not_ implement any current XPointer features.

    XML::Grove::ToObjects      OBSOLETE
        Convert XML to Perl objects via a mapping table.  Replaced by
        XML::PatAct::ToObjects in libxml-perl.


INSTALLATION

    XML::Grove requires Perl 5.005 and libxml-perl.  Most likely you
    will also want to get XML::Parser for reading XML documents.
    XML::Parser is available from CPAN:

<http://www.perl.com/CPAN/modules/by-module/XML/>

    XML::Grove installs as a standard Perl module

            perl Makefile.PL
            make
            make test
            make install