NAME
XML::Parser::Style::Elemental - a slightly more advanced and flexible object tree style for XML::Parser
SYNOPSIS
#!/usr/bin/perl -w
use XML::Parser;
use Data::Dumper;
my $p = XML::Parser->new( Style => 'Elemental', Pkg => 'E' );
my $doc = <<DOC;
<foo>
<bar key="value">The world is foo enough.</bar>
</foo>
DOC
my ($e) = $p->parse($doc);
print Data::Dumper->Dump( [$e] );
my $test_node = $e->contents->[0];
print "root: ".$test_node->root." is ".$e."\n";
print "text content of ".$test_node->name."\n";
print $test_node->text_content;
DESCRIPTION
This module is similar to the XML::Parser Objects style, but slightly more advanced and flexible. Like the Objects style, an object is created for each element. Elemental uses a dynamic class factory to create objects with accessor methods or can use any supplied classes that support the same method signatures. This module also provides full namespace support when the Namespace
option is in use in addition to a No_Whitespace
option for stripping out extraneous non-markup characters that are commonly introduced when formatting XML to be human readable.
CLASS TYPES
Elemental style creates its parse tree with three class types -- Document, Element and Character. Developers have the option of using the built-in dynamic classes or registering their own. The following explains the purpose and method prototypes of each class type.
- Document - The root of the tree.
-
- name - The tag name. If the Namespace options is set to true, the extend name is stored.
- parent - A reference to the parent object.
- contents - An ordered array reference of direct descendents/children objects.
- text_content - The text content of all siblings, whitespace included.
- root - A reference to the Document object.
- Characters - Non-markup text.
OPTIONS
Elemental specific options are set in the XML::Parser constructor through a hash element with a key of 'Elemental', The value of Elemental is expected to be a hash reference with one of more of the option keys detailed in the following sections.
USING DYNAMIC CLASS OBJECTS
When parsing a document, Elemental uses a dynamic class factory to create minimal lightweight objects with accessor methods. These classes implement the pattern detailed in "CLASS TYPES" in addition to a parameterless constructor method of new
. Similar to the Objects style these classes are blessed into the package set with the Pkg
option.
Here we create a parser that uses Elemental to create Document, Element and Characters objects in the E package.
my $p = XML::Parser->new( Style => 'Elemental', Pkg => 'E' );
REGISTERING CLASSES
If you require something more functional then the generated dynamic classes you can register your own with Elemental. Like the Elemental class types, the option keys are Document
, Element
and Characters
. Here we register three classes and turn on the No_Whitespace
option.
my $p = XML::Parser->new( Style => 'Elemental',
Namespace => 1,
Elemental=>{
Document=>'Foo::Doc',
Element=>'Foo::El',
Characters=>'Foo::Chars',
No_Whitespace=>1
}
);
Note that, the same class can be registered for more then one class type as long as it supports all of the necessary method prototypes it is being registered to handle. See "CLASS TYPES" for more detail.
NO_WHITESPACE
When set to true, No_Whitespace
causes Elemental to pass over character strings of all whitespace instead of creating a new Character object. This options is helpful in stripping out extraneous non-markup characters that are commonly introduced when formatting XML to be human readable.
SEE ALSO
TO DO
Implement xml::base support instead of No_Whitespace.
LICENSE
The software is released under the Artistic License. The terms of the Artistic License are described at http://www.perl.com/language/misc/Artistic.html.
AUTHOR & COPYRIGHT
Except where otherwise noted, XML::Parser::Style::Elemental is Copyright 2004, Timothy Appnel, cpan@timaoutloud.org. All rights reserved.
6 POD Errors
The following errors were encountered while parsing the POD:
- Around line 137:
=begin without a target?
- Around line 183:
'=item' outside of any '=over'
- Around line 226:
You forgot a '=back' before '=head1'
- Around line 282:
'=item' outside of any '=over'
- Around line 284:
You forgot a '=back' before '=head1'
- Around line 298:
'=end' without a target?