README
1
2
3This archive contains the distribution XML-SAX-Machines,
4version 0.46:
5
6 manage collections of SAX processors
7
8This software is copyright (c) 2013 by Barry Slaymaker.
9
10This is free software; you can redistribute it and/or modify it under
11the same terms as the Perl 5 programming language system itself.
12
13
14
README.too
1README for XML-SAX-Machines
2
3XML::SAX::Machines is a collection of APIs that allow complex SAX machines
4to be constructed without a huge amount of extra typing.
5
6This distribution contains three kinds of modules: machines, helpers, and
7filters. Here's how they are laid out:
8
9- XML::SAX::* contains machines and helpers.
10 - XML::SAX::Machines lets you import the "classic" constructor
11 functions like Tap(), Pipeline(), Manifold(), and ByRecord().
12 - Each machine type has a class that implements it, like
13 XML::SAX::Tap, XML::SAX::Pipeline, etc.
14 - There is currently only one available helper,
15 XML::SAX::EventMethodMaker, which is most useful for building a
16 collection of methods to handle different events in the same way,
17 without having to know all of their names. It is also useful as a
18 reference for all of the SAX events by looking at the source code,
19 which contains simple tables of what events occur for what kind of
20 handler (compiled by Robin Berjon).
21
22- XML::Filter::* contains filters that are used by ByRecord and Manifold
23 machines to handle SAX events (machines don't handle SAX events, they
24 delegate to the generators/filters/handlers they contain).
25 - XML::Filter::DocSplitter - Splits one doc in to multiple
26 documents, optionally coordinating with an aggregator like
27 XML::Filter::Merger to reassemble them. ByRecord uses this.
28 - XML::Filter::Distributor - buffers a document and reemits it to
29 each handler in turn. Used by Manifold.
30 - XML::Filter::Tee - a dynamically reconfigurable tee fitting. Does
31 not buffer. Used by Tap. Morally equivalent to
32 XML::Filter::SAXT but more flexible.
33 - XML::Filter::Merger - collects multiple documents and merges them,
34 inserting all secondary documents in to one master document.
35 Used by both ByRecord and Manifold.
36
37All of the XML::Filter::* classes are useful outside of the machines
38that use them. For instance, XML::Filter::DocSplitter has been used
39(not by me) in a Pipeline to split a huge record oriented file in to
40individual files containing single records (using a custom class derived
41from XML::SAX::Writer). XML::Filter::Merger is useful as a general way
42to implement <XInclude> style processing when XInclude is not a good
43fit.
44
45See the examples/ directory for, well, examples (and feel free to write
46up creative examples, eventually I'd like to compile a cookbook).
47
48To give a more concrete idea of how SAX machines are typically used,
49here's how to build a pipeline of SAX processors:
50
51 use XML::SAX::Machines qw( Pipeline );
52 use My::SAX::Filter2;
53
54 my $p = Pipeline(
55 "My::SAX::Filter1",
56 My::SAX::Filter2->new( ... ),
57 \$output
58 );
59
60 $p->parse_uri( $ARGV[0] );
61
62That loads (if need be) XML::SAX::Writer and calls it's new() function
63with an Output => \$output option, calls the passed-in instance of
64XML::SAX::Filter2 and calls its set_handler() method to point it to the
65XML::SAX::Writer that was just created, and then loads (if need be)
66My::SAX::Filter1 and calls it's new() function with a Handler => option
67pointing to the XML::SAX::Filter2 instance.
68