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.

contents - An array reference of direct decendents.
root - Return reference of itself.

Element - The tags in the document.

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.
attributes - A hash reference of key-value pairs representing the tags attributes.
text_content - The text content of all siblings, whitespace included.
root - A reference to the Document object.

Characters - Non-markup text.

data - A string of non-markup characters.
parent - A reference to the parent object.
root - A reference to the Document object.

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.

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

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

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?