A generic SAX machine (an instance of XML::SAX::Machine) is a container of SAX processors (referred to as "parts") connected in arbitrary ways.

Each parameter to Machine() (or XML::SAX::Machine-new()>) represents one top level part of the machine. Each part has a name, a processor, and one or more handlers (usually specified by name, as shown in the SYNOPSIS).

Since SAX machines may be passed in as single top level parts, you can also create nested, complex machines ($filter3 in the SYNOPSIS could be a Pipeline, for example).

A SAX machines can act as a normal SAX processors by connecting them to other SAX processors:

Although it's not required, each part in a machine can be named. This is useful for retrieving and manipulating the parts (see "part", for instance), and for debugging, since debugging output (see "trace_parts" and "trace_all_parts") includes the names.

Part names must be valid Perl subroutine names, beginning with an uppercase character. This is to allow convenience part accessors methods like

$c = $m->NameOfAFilter;

to work without ever colliding with the name of a method (all method names are completely lower case). Only filters named like this can be accessed using the magical accessor functions.

The names c<Intake> and Exhaust are reserved. Intake refers to the first part in the processing chain. This is not necessarily the first part in the constructor list, just the first part to receive external events.

Exhaust refers to the output of the machine; no part may be named Exhaust, and any parts with a handler named Exhaust will deliver their output to the machine's handler. Normally, only one part should deliver it's output to the Exhaust port.

Calling $m->set_handler() alters the Exhaust port, assuming any processors pointing to the Exhaust provide a set_handler() method like XML::SAX::Base's.

The XML::SAX::Machine class is very agnostic about what SAX processors it supports; about the only constraint is that it must be a blessed reference (of any type) that does not happen to be a Perl IO::Handle (which are assumed to be input or output filehandles).

The major constraint placed on SAX processors is that they must provide either a set_handler or set_handlers method (depending on how many handlers a processor can feed) to allow the SAX::Machine to disconnect and reconnect them. Luckily, this is true of almost any processor derived from XML::SAX::Base. Unfortunately, many SAX older (SAX1) processors do not meet this requirement; they assume that SAX processors will only ever be connected together using their constructors.

SAX machines allow you to connect the parts however you like; each part is given a name and a list of named handlers to feed. The number of handlers a part is allowed depends on the part; most filters only allow once downstream handler, but filters like XML::Filter::SAXT and XML::Filter::Distributor are meant to feed multiple handlers.

Parts may not be connected in loops ("cycles" in graph theory terms). The machines specified by:

[ A => "Foo" => "A" ], ## Illegal!

and

[ A => "Foo" => "B" ], ## Illegal!
[ B => "Foo" => "A" ],

. Configuring a machine this way would cause events to flow in an infinite loop, and/or cause the first processor in the cycle to start receiving events from the end of the cycle before the input document was complete. Besides, it's not a very useful topology :).

Gets an arbitrarily ordered list of top level parts in this machine. This is all of the parts directly contained by this machine and none of the parts that may be inside them. So if a machine contains an XML::SAX::Pipeline as one of it's parts, the pipeline will be returned but not the parts inside the pipeline.

Sets the machine's handler and sets the handlers for all parts that have Exhaust specified as their handlers. Requires that any such parts provide a set_handler or (if the part has multiple handlers) a set_handlers method.

NOTE: handler types other than "Handler" are only supported if they are supported by whatever parts point at the Exhaust. If the handler type is Handler, then the appropriate method is called as:

XML::SAX::Machine provides all SAX1 and SAX2 events and delgates them to the processor indicated by $m->find_part( "Intake" ). This adds some overhead, so if you are concerned about overhead, you might want to direct SAX events directly to the Intake instead of to the machine.

It also provides parse...() routines so it can whip up a parser if need be. This means: parse(), parse_uri(), parse_string(), and parse_file() (see XML::SAX::EventMethodMaker for details). There is no way to pass methods directly to the parser unless you know that the Intake is a parser and call it directly. This is not so important for parsing, because the overhead it takes to delegate is minor compared to the effort needed to parse an XML document.

Separate initialization from construction time; there should be somthing like a $m->connect( ....machine_spec... ) that new() calls to allow you to delay parts speficication and reconfigure existing machines.