XML::Essex 0.01

XML::Essex is a Perl module for essex XML processing primitives.

Result Value

The return value will be returned to the caller. For handlers, this is usually a "1" for success or some other value, such as a data structure that has been built or the result of a query.

For generators and filters, it is important that the result of the next filter's end_document() is returned at the end of your Essex script, so that it may be used upstream of such modules as XML::Simple.

Errors should be reported using die().

Result Values

Essex is designed to Do The Right Thing for the vast majority of uses, so it manages result values automatically unless you take control. Below is a set of detailed rules for how it manages the result value for a filter's processing run, but the overview is:

· Filters normally do not need to manage a result. The result from the next filter downstream will be returned automatically, or an exception will be thrown if an incomplete document is sent downstream.
· Generators act like filters mostly, except that if a generator decides not to send any results downstream, it should either set a result value by calling result() with it, or return that result normally, just like a handler.
· Handlers should either set a result value by calling result() with it, or return that result normally.
· Generators, filters and handlers should all die() on unexpected conditions and most error conditions (a FALSE or undefined result is not necessarily an error condition for a handler).

Generators and filters generally should not return a value of their own because this will surprise calling code which is expecting a return value of the type that the final SAX handler returns.

Exported Functions

These are exported by default, use the use XML::Essex (); syntax to avoid exporting any of these or export only the ones you want.

The following export tags are also defined:

:read get read_from parse_doc isa next_event path type xeof
:rules on
:write put write_to start_doc end_doc start_elt chars ...

so you can

use XML::Essex qw( :read :rules );

for an Essex script that just handles input and uses some rules, or even:

use XML::Essex qw( parse_doc :rules );

for a purely rule-based script.

Importing only what you need is a little quicker and more memory efficient, but it cal also allow XML::Essex to run more efficiently. If you don't import any output functions (see :write above), it will not load the output routines. Same for the input and rule based APIs.

get

my $e = get;

Returns the next SAX event. Sets $_ as an EXPERIMENTAL feature.

Throws an exception (which is silently caught outside the main code) on end of input.

See isa() and type() functions and method (in XML::Essex::Object) for how to test what was just gotten.
read_from

read_from *STDIN; ## From a filehandle
read_from "-"; ## From *STDIN
read_from "foo.xml"; ## From a file or URI (URI support is parser dependant)
read_from $xml_string; ## From a string.
read_from undef; ## STDIN or files named in @ARGV, as appropriate

Tells the next get() or parse_doc() to read from the indicated source.

Calling read_from automatically disassembles the current processing chain and builds a new one (just like Perl's open() closes an already open filehandle).
push_output_filters

Adds an output filter to the end of the current list (and before the eventual writer). Can be a class name (which will be require()ed unless the class can already new()) or a reference to a filter.
parse_doc

Parses a single document from the current input. Morally equivalent to get() while 1; but exits normally (as opposed to throwing an exception) when the end of document is reached. Also slightly faster now and hopefully moreso when optimizations can be made.

Used to read to the end of a document, primarily in rule-based processing ("on").

TODO: Allow parse_doc to take rules.
put

Output one or more events. Usually these events are created by constructors like start_elt() (see XML::Generator::Essex for details) or are objects returned get() method.
write_to

write_to *STDOUT; ## To a filehandle
write_to "-"; ## To *STDOUT
write_to "foo.xml"; ## To a file or URI (URI support is parser dependant)
write_to $xml_string; ## To a string.

Tells the next put() to write the indicated source.

Miscellaneous

isa

get until isa "start_elt" and $_->name eq "foo";
$r = get until isa $r, "start_elt" and $_->name eq "foo";

Returns true if the parameter is of the indicated object type. Tests $_ unless more than one parameter is passed.
next_event

Like get() (see below), but does not remove the next event from the input stream.

get "start_document::*";
get if next_event->isa( "xml_decl" );
...process remainder of document...

path

get "start_element::*" until path eq "/path/to/foo:bar"

Returns the path to the current element as a string.
type

get until type eq "start_document";
$r = get until type $r eq "start_document";

Return the type name of the object. This is the class name with a leading XML::Essex:: stripped off. This is a wrapper around the event's type() method.
xeof

Return TRUE if the last event has been read.

Product's homepage

Requirements:

· Perl