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

           Barrie Slaymaker <barries@slaysys.com>

       •   Barry Slaymaker

       •   Chris Prather <chris@prather.org>

           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.

       This software is copyright (c) 2013 by Barry Slaymaker.

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

perl v5.34.0                                       2022-06-28                                 XML::SAX::Tap(3pm)

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

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

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

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

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

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

       version 0.46