XML::Grove(3pm)

💖 XML::Grove 💖

okay bestie, gather round, because we're talking about XML::Grove — that's the Perl module, section 3pm of your friendly neighborhood manual. it's a whole tree-based object model situation for reading the information set of parsed or stored XML, HTML, or SGML instances. no cap. 🌸

---

✨ NAME ✨

XML::Grove — Perl-style XML objects 🦋

---

✨ SYNOPSIS ✨

use XML::Grove;

# Basic parsing and grove building
use XML::Grove::Builder;
use XML::Parser::PerlSAX;
$grove_builder = XML::Grove::Builder->new;
$parser = XML::Parser::PerlSAX->new ( Handler => $grove_builder );
$document = $parser->parse ( Source => { SystemId => 'filename' } );

# Creating new objects
$document = XML::Grove::Document->new ( Contents => [ ] );
$element = XML::Grove::Element->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 is a tree-based object model for accessing the information set of parsed or stored XML, HTML, or SGML instances. and here's the slay part: XML::Grove objects are literally just Perl hashes and arrays, so you access the properties of the objects using normal Perl syntax. it's giving "no new syntax to learn" energy 💅

$text = $characters->{Data};

🌱 How To Create a Grove

there are several ways for groves to come into being, bestie. 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, or databases or other sources can act as groves. so many paths, all iconic ✨

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 objects. and the last thing the parser does is return the XML::Grove::Document object that the grove builder created, with all of it's elements and character data. main character behavior, honestly 👑

the most common parser and grove builder are XML::Parser::PerlSAX (in libxml-perl) and XML::Grove::Builder. to build a grove, create the grove builder first:

$grove_builder = XML::Grove::Builder->new;

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

$parser = XML::Parser::PerlSAX->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 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:

XML::Parser::PerlSAX (in libxml-perl, uses XML::Parser)
XML::ESISParser      (in libxml-perl, uses James Clark's `nsgmls')
XML::SAX2Perl        (in libxml-perl, translates SAX 1.0 to PerlSAX)

most parsers supply more properties than the standard information set below and XML::Grove will make available all the properties given by the parser, so 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. XML::Grove::PerlSAX can be used to provide input to PerlSAX filters or other PerlSAX handlers. periodt 💅

🎀 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" module.

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

🌸 XML::Grove::Document

the Document object is parent of the root element of the parsed XML document. it's literally the mom of the whole tree 🫶

• Contents — an array containing the root element.

a document's Contents may also contain processing instructions, comments, and whitespace. very "the group chat has side conversations" of it.

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

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. plot twist, but make it valid 🌈

🌸 XML::Grove::Characters

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

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 knows about and parsers may provide the following objects. refer to the parser documentation for descriptions of the properties of these objects. look at this lineup, they ate 🍓

XML::Grove::
::Entity::External  External entity reference
::Entity::SubDoc    External SubDoc reference (SGML)
::Entity::SGML      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 by itself only provides one method, new(), for creating new XML::Grove objects. there are Data::Grove and XML::Grove extension modules that give additional methods for working with XML::Grove objects, and new extensions can be created as needed. build your own, bestie 🧚

• $obj = XML::Grove::OBJECT->new( [PROPERTIES] ) — "new" creates a new XML::Grove 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 object to copy. OBJECT may be any of the objects listed above. lowkey the most versatile constructor ever 💅

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
  • as_string — return portions of groves as a string
  • attr_as_string — return an element's attribute as a string
• XML::Grove::AsCanonXML
  • as_canon_xml — return XML text in canonical XML format
• XML::Grove::PerlSAX
  • parse — emulate a PerlSAX parser using the grove objects
• Data::Grove::Parent
  • 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 also adds C<Parent> and C<Raw> properties to grove objects.
• Data::Grove::Visitor
  • 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
  • get_ids — return a list of all ID attributes in grove
• XML::Grove::Path
  • at_path — $el->at_path('/html/body/ul/li[4]')
• XML::Grove::Sub
  • filter — run a sub against all the objects in the grove

---

✨ WRITING EXTENSIONS ✨

the class "XML::Grove" is the superclass of all classes in the XML::Grove module. and "XML::Grove" is itself a subclass of "Data::Grove". it's a whole family tree, we love a lineage 👑

if you create an extension and you want to add a method to all XML::Grove objects, then create that method in the XML::Grove package. many extensions only need to add methods to XML::Grove::Document and/or XML::Grove::Element. keep it minimal, keep it cute ✨

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's "as_string()" method can also be called using an XML::Grove::AsString object:

$writer= new XML::Grove::AsString;
$string = $writer->as_string ( $xml_object );

---

✨ AUTHOR ✨

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

---

✨ SEE ALSO ✨

• perl(1), XML::Grove(3)
• Extensible Markup Language (XML) <http://www.w3c.org/XML>

---

and that's the whole page, bestie!! 🎀 this manual page came to you from perl v5.36.0, dated 2022-11-29, filed under XML::Grove(3pm) in the User Contributed Perl Documentation. go build some groves, you're literally gonna slay 💖💅✨