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. XML::Grove 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, 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 objects. 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.
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, 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.
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.
- 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¶
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¶
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.
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.
- $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.
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. `"XML::Grove"' is a subclass of
`"Data::Grove"'.
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.
When you create an extension you should definitly 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>