XML::SAX::Machines is a collection of APIs that allow complex SAX machines
to be constructed without a huge amount of extra typing.
This distribution contains three kinds of modules: machines, helpers, and
filters. Here's how they are laid out:
- XML::SAX::* contains machines and helpers.
- XML::SAX::Machines lets you import the "classic" constructor
functions like Tap(), Pipeline(), Manifold(), and ByRecord().
- Each machine type has a class that implements it, like
XML::SAX::Tap, XML::SAX::Pipeline, etc.
- There is currently only one available helper,
XML::SAX::EventMethodMaker, which is most useful for building a
collection of methods to handle different events in the same way,
without having to know all of their names. It is also useful as a
reference for all of the SAX events by looking at the source code,
which contains simple tables of what events occur for what kind of
handler (compiled by Robin Berjon).
- XML::Filter::* contains filters that are used by ByRecord and Manifold
machines to handle SAX events (machines don't handle SAX events, they
delegate to the generators/filters/handlers they contain).
- XML::Filter::DocSplitter - Splits one doc in to multiple
documents, optionally coordinating with an aggregator like
XML::Filter::Merger to reassemble them. ByRecord uses this.
- XML::Filter::Distributor - buffers a document and reemits it to
each handler in turn. Used by Manifold.
- XML::Filter::Tee - a dynamically reconfigurable tee fitting. Does
not buffer. Used by Tap. Morally equivalent to
XML::Filter::SAXT but more flexible.
- XML::Filter::Merger - collects multiple documents and merges them,
inserting all secondary documents in to one master document.
Used by both ByRecord and Manifold.
All of the XML::Filter::* classes are useful outside of the machines
that use them. For instance, XML::Filter::DocSplitter has been used
(not by me) in a Pipeline to split a huge record oriented file in to
individual files containing single records (using a custom class derived
from XML::SAX::Writer). XML::Filter::Merger is useful as a general way
to implement <XInclude> style processing when XInclude is not a good
fit.
See the examples/ directory for, well, examples (and feel free to write
up creative examples, eventually I'd like to compile a cookbook).
To give a more concrete idea of how SAX machines are typically used,
here's how to build a pipeline of SAX processors:
use XML::SAX::Machines qw( Pipeline );
use My::SAX::Filter2;
my $p = Pipeline(
"My::SAX::Filter1",
My::SAX::Filter2->new( ... ),
\$output
);
$p->parse_uri( $ARGV[0] );
That loads (if need be) XML::SAX::Writer and calls it's new() function
with an Output => \$output option, calls the passed-in instance of
XML::SAX::Filter2 and calls its set_handler() method to point it to the
XML::SAX::Writer that was just created, and then loads (if need be)
My::SAX::Filter1 and calls it's new() function with a Handler => option
pointing to the XML::SAX::Filter2 instance.
