Part 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.

Reserved Names: Intake and Exhaust

"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.

"Intake" and "Exhaust" are usually assigned automatically by single-purpose machines like XML::SAX::Pipeline and XML::SAX::Manifold.

SAX Processor Support

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.

Connections

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 :).

SAX machines detect loops at construction time.

Public Methods

new()

    my $m = $self->new( @machine_spec, \%options );
    

Creates $self using %options, and compiles the machine spec. This is the longhand form of "Machines( ... )".

find_part

Gets a part contained by this machine by name, number or object reference:

    $c = $m->find_part( $name );
    $c = $m->find_part( $number );
    $c = $m->find_part( $obj );    ## useful only to see if $obj is in $m
    

If a machine contains other machines, parts of the contained machines may be accessed by name using unix directory syntax:

    $c = $m->find_part( "/Intake/Foo/Bar" );
    

(all paths must be absolute).

Parts may also be accessed by number using array indexing:

    $c = $m->find_part(0);  ## Returns first part or undef if none
    $c = $m->find_part(-1); ## Returns last part or undef if none
    $c = $m->find_part( "Foo/0/1/-1" );
    

There is no way to guarantee that a part's position number means anything, since parts can be reconnected after their position numbers are assigned, so using a part name is recommended.

Throws an exception if the part is not found, so doing things like

   $m->find_part( "Foo" )->bar()
    

garner informative messages when "Foo" is not found. If you want to test a result code, do something like

    my $p = eval { $m->find_part };
    unless ( $p ) {
        ...handle lookup failure...
    }
    

parts

    for ( $m->parts ) { ... }
    

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.

all_parts

    for ( $m->all_parts ) { ... }
    

Gets all parts in this machine, not just top level ones. This includes any machines contained by this machine and their parts.

set_handler

    $m->set_handler( $handler );
    $m->set_handler( DTDHandler => $handler );
    

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:

    $part->set_handler( $handler );
    $part->set_handlers( $handler0, $handler1, ... );
    

If the type is some other handler type, these are called as:

    $part->set_handler( $type => $handler );
    $part->set_handlers( { $type0 => $handler0 }, ... );
    

trace_parts

    $m->trace_parts;          ## trace all top-level parts
    $m->trace_parts( @ids );  ## trace the indicated parts
    

Uses Devel::TraceSAX to enable tracing of all events received by the parts of this machine. Does not enable tracing of parts contained in machines in this machine; for that, see trace_all_parts.

trace_all_parts

    $m->trace_all_parts;      ## trace all parts
    

Uses Devel::TraceSAX to trace all events received by the parts of this machine.

untracify_parts

    $m->untracify_parts( @ids );
    

Converts the indicated parts to SAX processors with tracing enabled. This may not work with processors that use AUTOLOAD.

Internal and Helper Methods

_compile_specs

    my @comp = $self->_compile_specs( @_ );
    

Runs through a list of module names, output specifiers, etc., and builds the machine.

    $scalar     --> "$scalar"->new
    $ARRAY_ref  --> pipeline @$ARRAY_ref
    $SCALAR_ref --> XML::SAX::Writer->new( Output => $SCALAR_ref )
    $GLOB_ref   --> XML::SAX::Writer->new( Output => $GLOB_ref )
    

generate_description

    $m->generate_description( $h );
    $m->generate_description( Handler => $h );
    $m->generate_description( Pipeline ... );
    

Generates a series of SAX events to the handler of your choice.

See XML::Handler::Machine2GraphViz on CPAN for a way of visualizing machine innards.