XML::SAX::Tap(3pm)

💖 XML::SAX::Tap 💖

okay so bestie, welcome to XML::SAX::Tap — the Perl module that taps a whole pipeline of SAX processors. yes like a little pipe tap. it's giving plumbing but make it glam 💅

---

✨ VERSION ✨

this is version 0.46 🎀

---

🌸 SYNOPSIS 🌸

so here's how you actually use it, copy-paste ready:

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

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

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

like yes, you can literally tap into a shell command with a pipe, iconic behavior fr fr 🫶

---

🦋 DESCRIPTION 🦋

XML::SAX::Tap is a SAX machine, and what it does is: every single event it receives, it passes on to a branch handler, and then it passes it down to its main handler. that's it. that's the whole vibe.

why would you want that? because it means you can slide debugging output, logging output, validators, and other processors (and other machines too, of course) right into the middle of a pipeline. so good. so useful.

now, how is this different from XML::Filter::Tee, XML::Filter::SAXT and XML::SAX::Distributer? the key thing: a tap is also a pipeline — it contains the processing that handles the tap. it's not just a splitter, it's a splitter with its own little crew inside. 💅

and how is it like XML::Filter::Tee? because the events are not buffered. each event goes first to the tap, then to the branch. (this is different from XML::SAX::Dispatcher, which does buffer the events. we don't do that here bestie.)

and how is it like XML::SAX::Pipeline? because it contains a series of processors in a pipeline — and those are the ones doing the "tapping":

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

okay and this next bit matters a LOT, so listen: the events are not copied. because they might be data structures that are difficult or even impossible to copy properly — think parts of a C-based DOM implementation. you cannot just duplicate those. so we don't even try. 😭

events go to the tap first, and the reason is chef's kiss: you can validate events using a tap that throws exceptions, and those exceptions will get acted on before the tap's handler ever sees them. periodt.

also important: this machine has no "Exhaust" port. (if you wanna know all about "Intake" and "Exhaust" ports, go read XML::SAX::Machine.)

---

💜 NAME 💜 (yes again, the original does this twice, and honestly? iconic. we're keeping it.)

XML::SAX::Tap — Tap a pipeline of SAX processors 🎀

---

👑 METHODS 👑

new

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

that's the constructor bestie, feed it your tap processors and your options hashref 💖

---

🌈 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. your pick, no pressure 🫶

---

🧚 AUTHORS 🧚

• Barry Slaymaker
• Chris Prather <chris@prather.org>

---

⭐ COPYRIGHT AND LICENSE ⭐

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. slay 💅

---

and that's a wrap bestie!! this page was generated by perl v5.34.0 on 2022-06-28, filed under XML::SAX::Tap(3pm). go tap something. 🦋✨