{
    "content": [
        {
            "type": "text",
            "text": "# XML::Grove (perldoc)\n\n## NAME\n\nXML::Grove - Perl-style XML objects\n\n## SYNOPSIS\n\nuse XML::Grove;\n# Basic parsing and grove building\nuse XML::Grove::Builder;\nuse XML::Parser::PerlSAX;\n$grovebuilder = XML::Grove::Builder->new;\n$parser = XML::Parser::PerlSAX->new ( Handler => $grovebuilder );\n$document = $parser->parse ( Source => { SystemId => 'filename' } );\n# Creating new objects\n$document = XML::Grove::Document->new ( Contents => [ ] );\n$element = XML::Grove::Element->new ( Name => 'tag',\nAttributes => { },\nContents => [ ] );\n# Accessing XML objects\n$tagname = $element->{Name};\n$contents = $element->{Contents};\n$parent = $element->{Parent};\n$characters->{Data} = 'XML is fun!';\n\n## DESCRIPTION\n\nXML::Grove is a tree-based object model for accessing the information set of parsed or stored\nXML, HTML, or SGML instances. XML::Grove objects are Perl hashes and arrays where you access the\nproperties of the objects using normal Perl syntax:\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (2 subsections)\n- **METHODS**\n- **WRITING EXTENSIONS**\n- **AUTHOR**\n- **SEE ALSO** (1 subsections)\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "XML::Grove",
        "section": "",
        "mode": "perldoc",
        "summary": "XML::Grove - Perl-style XML objects",
        "synopsis": "use XML::Grove;\n# Basic parsing and grove building\nuse XML::Grove::Builder;\nuse XML::Parser::PerlSAX;\n$grovebuilder = XML::Grove::Builder->new;\n$parser = XML::Parser::PerlSAX->new ( Handler => $grovebuilder );\n$document = $parser->parse ( Source => { SystemId => 'filename' } );\n# Creating new objects\n$document = XML::Grove::Document->new ( Contents => [ ] );\n$element = XML::Grove::Element->new ( Name => 'tag',\nAttributes => { },\nContents => [ ] );\n# Accessing XML objects\n$tagname = $element->{Name};\n$contents = $element->{Contents};\n$parent = $element->{Parent};\n$characters->{Data} = 'XML is fun!';",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 21,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 6,
                "subsections": [
                    {
                        "name": "How To Create a Grove",
                        "lines": 46
                    },
                    {
                        "name": "Using Groves",
                        "lines": 68
                    }
                ]
            },
            {
                "name": "METHODS",
                "lines": 46,
                "subsections": []
            },
            {
                "name": "WRITING EXTENSIONS",
                "lines": 14,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 1,
                "subsections": [
                    {
                        "name": "perl",
                        "lines": 2
                    }
                ]
            }
        ],
        "sections": {
            "NAME": {
                "content": "XML::Grove - Perl-style XML objects\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "use XML::Grove;\n\n# Basic parsing and grove building\nuse XML::Grove::Builder;\nuse XML::Parser::PerlSAX;\n$grovebuilder = XML::Grove::Builder->new;\n$parser = XML::Parser::PerlSAX->new ( Handler => $grovebuilder );\n$document = $parser->parse ( Source => { SystemId => 'filename' } );\n\n# Creating new objects\n$document = XML::Grove::Document->new ( Contents => [ ] );\n$element = XML::Grove::Element->new ( Name => 'tag',\nAttributes => { },\nContents => [ ] );\n\n# Accessing XML objects\n$tagname = $element->{Name};\n$contents = $element->{Contents};\n$parent = $element->{Parent};\n$characters->{Data} = 'XML is fun!';\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "XML::Grove is a tree-based object model for accessing the information set of parsed or stored\nXML, HTML, or SGML instances. XML::Grove objects are Perl hashes and arrays where you access the\nproperties of the objects using normal Perl syntax:\n\n$text = $characters->{Data};\n",
                "subsections": [
                    {
                        "name": "How To Create a Grove",
                        "content": "There are several ways for groves to come into being, they can be read from a file or string\nusing a parser and a grove builder, they can be created by your Perl code using the `\"new()\"'\nmethods of XML::Grove::Objects, or databases or other sources can act as groves.\n\nThe most common way to build groves is using a parser and a grove builder. The parser is the\npackage that reads the characters of an XML file, recognizes the XML syntax, and produces\n``events'' reporting when elements (tags), text (characters), processing instructions, and other\nsequences occur. A grove builder receives (``consumes'' or ``handles'') these events and builds\nXML::Grove objects. The last thing the parser does is return the XML::Grove::Document object\nthat the grove builder created, with all of it's elements and character data.\n\nThe most common parser and grove builder are XML::Parser::PerlSAX (in libxml-perl) and\nXML::Grove::Builder. To build a grove, create the grove builder first:\n\n$grovebuilder = XML::Grove::Builder->new;\n\nThen create the parser, passing it the grove builder as it's handler:\n\n$parser = XML::Parser::PerlSAX->new ( Handler => $grovebuilder );\n\nThis associates the grove builder with the parser so that every time you parse a document with\nthis parser it will return an XML::Grove::Document object. To parse a file, use the `\"Source\"'\nparameter to the `\"parse()\"' method containing a `\"SystemId\"' parameter (URL or path) of the\nfile you want to parse:\n\n$document = $parser->parse ( Source => { SystemId => 'kjv.xml' } );\n\nTo parse a string held in a Perl variable, use the `\"Source\"' parameter containing a `\"String\"'\nparameter:\n\n$document = $parser->parse ( Source => { String => $xmltext } );\n\nThe following are all parsers that work with XML::Grove::Builder:\n\nXML::Parser::PerlSAX (in libxml-perl, uses XML::Parser)\nXML::ESISParser      (in libxml-perl, uses James Clark's `nsgmls')\nXML::SAX2Perl        (in libxml-perl, translates SAX 1.0 to PerlSAX)\n\nMost parsers supply more properties than the standard information set below and XML::Grove will\nmake available all the properties given by the parser, refer to the parser documentation to find\nout what additional properties it may provide.\n\nAlthough there are not any available yet (August 1999), PerlSAX filters can be used to process\nthe output of a parser before it is passed to XML::Grove::Builder. XML::Grove::PerlSAX can be\nused to provide input to PerlSAX filters or other PerlSAX handlers.\n"
                    },
                    {
                        "name": "Using Groves",
                        "content": "The properties provided by parsers are available directly using Perl's normal syntax for\naccessing hashes and arrays. For example, to get the name of an element:\n\n$elementname = $element->{Name};\n\nBy convention, all properties provided by parsers are in mixed case. `\"Parent\"' properties are\navailable using the `\"Data::Grove::Parent\"' module.\n\nThe following is the minimal set of objects and their properties that you are likely to get from\nall parsers:\n\nXML::Grove::Document\nThe Document object is parent of the root element of the parsed XML document.\n\nContents    An array containing the root element.\n\nA document's `Contents' may also contain processing instructions, comments, and whitespace.\n\nSome parsers provide information about the document type, the XML declaration, or notations and\nentities. Check the parser documentation for property names.\n\nXML::Grove::Element\nThe Element object represents elements from the XML source.\n\nParent      The parent object of this element.\n\nName        A string, the element type name of this element\n\nAttributes  A hash of strings or arrays\n\nContents    An array of elements, characters, processing instructions, etc.\n\nIn a purely minimal grove, the attributes of an element will be plain text (Perl scalars). Some\nparsers provide access to notations and entities in attributes, in which case the attribute may\ncontain an array.\n\nXML::Grove::Characters\nThe Characters object represents text from the XML source.\n\nParent      The parent object of this characters object\n\nData        A string, the characters\n\nXML::Grove::PI\nThe PI object represents processing instructions from the XML source.\n\nParent      The parent object of this PI object.\n\nTarget      A string, the processing instruction target.\n\nData        A string, the processing instruction data, or undef if none was supplied.\n\nIn addition to the minimal set of objects above, XML::Grove knows about and parsers may provide\nthe following objects. Refer to the parser documentation for descriptions of the properties of\nthese objects.\n\nXML::Grove::\n::Entity::External  External entity reference\n::Entity::SubDoc    External SubDoc reference (SGML)\n::Entity::SGML      External SGML reference (SGML)\n::Entity            Entity reference\n::Notation          Notation declaration\n::Comment           <!-- A Comment -->\n::SubDoc            A parsed subdocument (SGML)\n::CData             A CDATA marked section\n::ElementDecl       An element declaration from the DTD\n::AttListDecl       An element's attribute declaration, from the DTD\n"
                    }
                ]
            },
            "METHODS": {
                "content": "XML::Grove by itself only provides one method, new(), for creating new XML::Grove objects. There\nare Data::Grove and XML::Grove extension modules that give additional methods for working with\nXML::Grove objects and new extensions can be created as needed.\n\n$obj = XML::Grove::OBJECT->new( [PROPERTIES] )\n`\"new\"' creates a new XML::Grove object with the type *OBJECT*, and with the initial\n*PROPERTIES*. *PROPERTIES* may be given as either a list of key-value pairs, a hash, or an\nXML::Grove object to copy. *OBJECT* may be any of the objects listed above.\n\nThis is a list of available extensions and the methods they provide (as of Feb 1999). Refer to\ntheir module documentation for more information on how to use them.\n\nXML::Grove::AsString\nasstring       return portions of groves as a string\nattrasstring  return an element's attribute as a string\n\nXML::Grove::AsCanonXML\nascanonxml    return XML text in canonical XML format\n\nXML::Grove::PerlSAX\nparse           emulate a PerlSAX parser using the grove objects\n\nData::Grove::Parent\nroot            return the root element of a grove\nrootpath        return an array of all objects between the root\nelement and this object, inclusive\n\nData::Grove::Parent also adds `C<Parent>' and `C<Raw>' properties\nto grove objects.\n\nData::Grove::Visitor\naccept          call back a subroutine using an object type name\nacceptname     call back using an element or tag name\nchildrenaccept for each child in Contents, call back a sub\nchildrenacceptname  same, but using tag names\nattraccept     call back for the objects in attributes\n\nXML::Grove::IDs\ngetids         return a list of all ID attributes in grove\n\nXML::Grove::Path\natpath         $el->atpath('/html/body/ul/li[4]')\n\nXML::Grove::Sub\nfilter          run a sub against all the objects in the grove\n",
                "subsections": []
            },
            "WRITING EXTENSIONS": {
                "content": "The class `\"XML::Grove\"' is the superclass of all classes in the XML::Grove module.\n`\"XML::Grove\"' is a subclass of `\"Data::Grove\"'.\n\nIf you create an extension and you want to add a method to *all* XML::Grove objects, then create\nthat method in the XML::Grove package. Many extensions only need to add methods to\nXML::Grove::Document and/or XML::Grove::Element.\n\nWhen you create an extension you should definitely provide a way to invoke your module using\nobjects from your package too. For example, XML::Grove::AsString's `\"asstring()\"' method can\nalso be called using an XML::Grove::AsString object:\n\n$writer= new XML::Grove::AsString;\n$string = $writer->asstring ( $xmlobject );\n",
                "subsections": []
            },
            "AUTHOR": {
                "content": "Ken MacLeod, ken@bitsko.slc.ut.us\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "",
                "subsections": [
                    {
                        "name": "perl",
                        "content": "Extensible Markup Language (XML) <http://www.w3c.org/XML>\n"
                    }
                ]
            }
        }
    }
}