NAME

XML::SAX::Tap - Tap a pipeline of SAX processors

VERSION

version 0.46

SYNOPSIS

    use XML::SAX::Machines qw( Pipeline Tap ) ;

    my $m = Pipeline(
        "UpstreamFilter",
        Tap( "My::Reformatter", \*STDERR ),
        "DownstreamFilter",
    );

    my $m = Pipeline(
        "UpstreamFilter",
        Tap( "| xmllint --format -" ),
        "DownstreamFilter",
    );

DESCRIPTION

XML::SAX::Tap is a SAX machine that passes each event it receives on to a brach handler and then on down to it's main handler. This allows debugging output, logging output, validators, and other processors (and machines, of course) to be placed in a pipeline. This differs from XML::Filter::Tee, XML::Filter::SAXT and XML::SAX::Distributer in that a tap is also a pipeline; it contains the processoring that handles the tap.

It's like XML::Filter::Tee in that the events are not buffered; each event is sent first to the tap, and then to the branch (this is different from XML::SAX::Dispatcher, which buffers the events).

It's like XML::SAX::Pipeline in that it contains a series of processors in a pipeline; these comprise the "tapping" processors:

            +----------------------------------------------+
            |                  Tap instance                |
            |                                              |
            |  Intake                                      |
            |  +-----+    +---------+        +---------+   |
 upstream --+->| Tee |--->| Stage_0 |--...-->| Stage_N |   |
            |  +-----+    +---------+        +---------+   |
            |         \                                    |
            |          \                          Exhaust  |
            |           +----------------------------------+--> downstream
            |                                              |
            +----------------------------------------------+

The events are not copied, since they may be data structures that are difficult or impossibly to copy properly, like parts of a C-based DOM implementation.

Events go to the tap first so that you can validate events using a tap that throws exceptions and they will be acted on before the tap's handler sees them.

This machine has no "Exhaust" port (see XML::SAX::Machine for details about "Intake" and "Exhaust" ports).

NAME

XML::SAX::Tap - Tap a pipeline of SAX processors

METHODS

new

    my $tap = XML::SAX::Tap->new( @tap_processors, \%options );

AUTHOR

    Barrie Slaymaker <barries@slaysys.com>

COPYRIGHT

    Copyright 2002, Barrie Slaymaker, All Rights Reserved

You may use this module under the terms of the Artistic, GNU Public, or BSD licenses, as you choose.

AUTHORS

Barry Slaymaker
Chris Prather <chris@prather.org>

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.