# XML::Grove - Perl-style XML objects - perldoc - [phpMan]

## NAME
    [XML::Grove](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown) - Perl-style XML objects

## SYNOPSIS
     use [XML::Grove](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown);

     # Basic parsing and grove building
     use [XML::Grove::Builder](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3ABuilder/markdown);
     use [XML::Parser::PerlSAX](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AParser%3A%3APerlSAX/markdown);
     $grove_builder = [XML::Grove::Builder](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3ABuilder/markdown)->new;
     $parser = [XML::Parser::PerlSAX](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AParser%3A%3APerlSAX/markdown)->new ( Handler => $grove_builder );
     $document = $parser->parse ( Source => { SystemId => 'filename' } );

     # Creating new objects
     $document = [XML::Grove::Document](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3ADocument/markdown)->new ( Contents => [ ] );
     $element = [XML::Grove::Element](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3AElement/markdown)->new ( Name => 'tag',
                                           Attributes => { },
                                           Contents => [ ] );

     # Accessing XML objects
     $tag_name = $element->{Name};
     $contents = $element->{Contents};
     $parent = $element->{Parent};
     $characters->{Data} = 'XML is fun!';

## DESCRIPTION
    [XML::Grove](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown) is a tree-based object model for accessing the information set of parsed or stored
    XML, HTML, or SGML instances. [XML::Grove](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown) objects are Perl hashes and arrays where you access the
    properties of the objects using normal Perl syntax:

      $text = $characters->{Data};

### How To Create a Grove
    There are several ways for groves to come into being, they can be read from a file or string
    using a parser and a grove builder, they can be created by your Perl code using the `new()'
    methods of [XML::Grove::Objects](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3AObjects/markdown), or databases or other sources can act as groves.

    The most common way to build groves is using a parser and a grove builder. The parser is the
    package that reads the characters of an XML file, recognizes the XML syntax, and produces
    ``events'' reporting when elements (tags), text (characters), processing instructions, and other
    sequences occur. A grove builder receives (``consumes'' or ``handles'') these events and builds
    [XML::Grove](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown) objects. The last thing the parser does is return the [XML::Grove::Document](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3ADocument/markdown) object
    that the grove builder created, with all of it's elements and character data.

    The most common parser and grove builder are [XML::Parser::PerlSAX](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AParser%3A%3APerlSAX/markdown) (in libxml-perl) and
    [XML::Grove::Builder](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3ABuilder/markdown). To build a grove, create the grove builder first:

      $grove_builder = [XML::Grove::Builder](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3ABuilder/markdown)->new;

    Then create the parser, passing it the grove builder as it's handler:

      $parser = [XML::Parser::PerlSAX](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AParser%3A%3APerlSAX/markdown)->new ( Handler => $grove_builder );

    This associates the grove builder with the parser so that every time you parse a document with
    this parser it will return an [XML::Grove::Document](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3ADocument/markdown) object. To parse a file, use the `"Source"'
    parameter to the `parse()' method containing a `"SystemId"' parameter (URL or path) of the file
    you want to parse:

      $document = $parser->parse ( Source => { SystemId => 'kjv.xml' } );

    To parse a string held in a Perl variable, use the `"Source"' parameter containing a `"String"'
    parameter:

      $document = $parser->parse ( Source => { String => $xml_text } );

    The following are all parsers that work with [XML::Grove::Builder](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3ABuilder/markdown):

      [XML::Parser::PerlSAX](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AParser%3A%3APerlSAX/markdown) (in libxml-perl, uses [XML::Parser](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AParser/markdown))
      [XML::ESISParser](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AESISParser/markdown)      (in libxml-perl, uses James Clark's `nsgmls')
      [XML::SAX2Perl](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3ASAX2Perl/markdown)        (in libxml-perl, translates SAX 1.0 to PerlSAX)

    Most parsers supply more properties than the standard information set below and [XML::Grove](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown) will
    make available all the properties given by the parser, refer to the parser documentation to find
    out what additional properties it may provide.

    Although there are not any available yet (August 1999), PerlSAX filters can be used to process
    the output of a parser before it is passed to [XML::Grove::Builder](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3ABuilder/markdown). [XML::Grove::PerlSAX](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3APerlSAX/markdown) can be
    used to provide input to PerlSAX filters or other PerlSAX handlers.

### Using Groves
    The properties provided by parsers are available directly using Perl's normal syntax for
    accessing hashes and arrays. For example, to get the name of an element:

      $element_name = $element->{Name};

    By convention, all properties provided by parsers are in mixed case. `"Parent"' properties are
    available using the `"[Data::Grove::Parent](https://www.chedong.com/phpMan.php/perldoc/Data%3A%3AGrove%3A%3AParent/markdown)"' module.

    The following is the minimal set of objects and their properties that you are likely to get from
    all parsers:

  [XML::Grove::Document](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3ADocument/markdown)
    The Document object is parent of the root element of the parsed XML document.

    Contents    An array containing the root element.

    A document's `Contents' may also contain processing instructions, comments, and whitespace.

    Some parsers provide information about the document type, the XML declaration, or notations and
    entities. Check the parser documentation for property names.

  [XML::Grove::Element](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3AElement/markdown)
    The Element object represents elements from the XML source.

    Parent      The parent object of this element.

    Name        A string, the element type name of this element

    Attributes  A hash of strings or arrays

    Contents    An array of elements, characters, processing instructions, etc.

    In a purely minimal grove, the attributes of an element will be plain text (Perl scalars). Some
    parsers provide access to notations and entities in attributes, in which case the attribute may
    contain an array.

  [XML::Grove::Characters](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3ACharacters/markdown)
    The Characters object represents text from the XML source.

    Parent      The parent object of this characters object

    Data        A string, the characters

  [XML::Grove::PI](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3API/markdown)
    The PI object represents processing instructions from the XML source.

    Parent      The parent object of this PI object.

    Target      A string, the processing instruction target.

    Data        A string, the processing instruction data, or undef if none was supplied.

    In addition to the minimal set of objects above, [XML::Grove](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown) knows about and parsers may provide
    the following objects. Refer to the parser documentation for descriptions of the properties of
    these objects.

      [XML::Grove](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown)::
      ::[Entity::External](https://www.chedong.com/phpMan.php/perldoc/Entity%3A%3AExternal/markdown)  External entity reference
      ::[Entity::SubDoc](https://www.chedong.com/phpMan.php/perldoc/Entity%3A%3ASubDoc/markdown)    External SubDoc reference (SGML)
      ::[Entity::SGML](https://www.chedong.com/phpMan.php/perldoc/Entity%3A%3ASGML/markdown)      External SGML reference (SGML)
      ::Entity            Entity reference
      ::Notation          Notation declaration
      ::Comment           <!-- A Comment -->
      ::SubDoc            A parsed subdocument (SGML)
      ::CData             A CDATA marked section
      ::ElementDecl       An element declaration from the DTD
      ::AttListDecl       An element's attribute declaration, from the DTD

## METHODS
    [XML::Grove](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown) by itself only provides one method, new(), for creating new [XML::Grove](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown) objects. There
    are [Data::Grove](https://www.chedong.com/phpMan.php/perldoc/Data%3A%3AGrove/markdown) and [XML::Grove](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown) extension modules that give additional methods for working with
    [XML::Grove](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown) objects and new extensions can be created as needed.

    $obj = [XML::Grove::OBJECT](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3AOBJECT/markdown)->new( [PROPERTIES] )
        `"new"' creates a new [XML::Grove](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown) object with the type *OBJECT*, and with the initial
        *PROPERTIES*. *PROPERTIES* may be given as either a list of key-value pairs, a hash, or an
        [XML::Grove](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown) object to copy. *OBJECT* may be any of the objects listed above.

    This is a list of available extensions and the methods they provide (as of Feb 1999). Refer to
    their module documentation for more information on how to use them.

      [XML::Grove::AsString](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3AAsString/markdown)
        as_string       return portions of groves as a string
        attr_as_string  return an element's attribute as a string

      [XML::Grove::AsCanonXML](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3AAsCanonXML/markdown)
        as_canon_xml    return XML text in canonical XML format

      [XML::Grove::PerlSAX](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3APerlSAX/markdown)
        parse           emulate a PerlSAX parser using the grove objects

      [Data::Grove::Parent](https://www.chedong.com/phpMan.php/perldoc/Data%3A%3AGrove%3A%3AParent/markdown)
        root            return the root element of a grove
        rootpath        return an array of all objects between the root
                        element and this object, inclusive

        [Data::Grove::Parent](https://www.chedong.com/phpMan.php/perldoc/Data%3A%3AGrove%3A%3AParent/markdown) also adds `C<Parent>' and `C<Raw>' properties
        to grove objects.

      [Data::Grove::Visitor](https://www.chedong.com/phpMan.php/perldoc/Data%3A%3AGrove%3A%3AVisitor/markdown)
        accept          call back a subroutine using an object type name
        accept_name     call back using an element or tag name
        children_accept for each child in Contents, call back a sub
        children_accept_name  same, but using tag names
        attr_accept     call back for the objects in attributes

      [XML::Grove::IDs](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3AIDs/markdown)
        get_ids         return a list of all ID attributes in grove

      [XML::Grove::Path](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3APath/markdown)
        at_path         $el->at_path('/html/body/ul/li[4]')

      [XML::Grove::Sub](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3ASub/markdown)
        filter          run a sub against all the objects in the grove

## WRITING EXTENSIONS
    The class `"[XML::Grove](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown)"' is the superclass of all classes in the [XML::Grove](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown) module.
    `"[XML::Grove](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown)"' is a subclass of `"[Data::Grove](https://www.chedong.com/phpMan.php/perldoc/Data%3A%3AGrove/markdown)"'.

    If you create an extension and you want to add a method to *all* [XML::Grove](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown) objects, then create
    that method in the [XML::Grove](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove/markdown) package. Many extensions only need to add methods to
    [XML::Grove::Document](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3ADocument/markdown) and/or [XML::Grove::Element](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3AElement/markdown).

    When you create an extension you should definitely provide a way to invoke your module using
    objects from your package too. For example, [XML::Grove::AsString](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3AAsString/markdown)'s `as_string()' method can also
    be called using an [XML::Grove::AsString](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3AAsString/markdown) object:

      $writer= new [XML::Grove::AsString](https://www.chedong.com/phpMan.php/perldoc/XML%3A%3AGrove%3A%3AAsString/markdown);
      $string = $writer->as_string ( $xml_object );

## AUTHOR
    Ken MacLeod, <ken@bitsko.slc.ut.us>

## SEE ALSO
### perl

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