README for XML-SAX-Machines

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.