XML::Filter::Tee(3pm)

💖 XML::Filter::Tee 💖

okay bestie, welcome to XML::Filter::Tee — a Perl module (it's in the 3pm section of the manual, if you were wondering where you wandered into). Strap in, it's giving very ✨pipeline✨ energy.

---

🌸 NAME 🌸

XML::Filter::Tee — Send SAX events to multiple processor, with switching. Yes bestie, that's the whole name. Short, sweet, iconic. 💅

---

🎀 VERSION 🎀

version 0.46 — we are living in the 0.46 era, no cap.

---

🦋 SYNOPSIS 🦋

my $t = XML::Filter::Tee->new(
    { Handler => $h0 },
    { Handler => $h1 },
    { Handler => $h2 },
    ...
);

## Altering the handlers list:
$t->set_handlers( $h0, $h1, $h2, $h3 );

## Controlling flow to a handler by number and by reference:
$t->disable_handler( 0 );
$t->enable_handler( 0 );

$t->disable_handler( $h0 );
$t->enable_handler( $h0 );

## Use in a SAX machine (though see L<XML::SAX::Pipeline> and
## L<XML::SAX::Tap> for a more convenient way to build a machine
## like this):
my $m = Machine(
    [ Intake => "XML::Filter::Tee" => qw( A B ) ],
    [ A      => ">>log.xml" ],
    [ B      => \*OUTPUT ],
);

---

🌈 DESCRIPTION 🌈

So XML::Filter::Tee is a SAX filter, and what it does is take every single event it receives and pass it along to a whole list of downstream handlers. One event, many handlers. It's the group-chat forward of the XML world, fr fr. 🫶

It's like XML::Filter::SAXT in that the events are not buffered — each event gets sent first to the tap, and then to the branch. (This is different from XML::SAX::Dispatcher, which does buffer the events. Not the vibe.) But unlike XML::Filter::SAXT, it lets you reconfigure its list of handlers (that's set_handlers) and it lets you control which handlers are allowed to receive events. Those two features are literally designed to make XML::Filter::Tee instances more useful with SAX machines — but heads up bestie, they do add some overhead relative to XML::Filter::SAXT. Choices were made. 💅

The events are not copied, since they may be data structures that are difficult or impossible to copy properly — think parts of a C-based DOM implementation. Which means: the handlers must not alter the events, or the later handlers are gonna see those alterations. 😭 No touching. Look with your eyes.

---

🌸 NAME 🌸

XML::Filter::Tee — Send SAX events to multiple processor, with switching.

yes bestie, there are two NAME sections. that's just how this manpage is. we don't question it. we respect it. 👑

---

✨ METHODS ✨

new

my $t = XML::Filter::Tee->new(
    { Handler => $h0 },
    { Handler => $h1 },
    { Handler => $h2 },
    ...
);

set_handlers

$t->set_handlers( $h0, $h1, $h2 );
$t->set_handlers( {
        Handler => $h0,
    },
    {
        Handler => $h1,
    },
);

Replaces the current list of handlers with new ones. Out with the old, in with the new, slay. 🔥

You can also name handlers, which makes enabling/disabling them by name way easier:

$m->set_handlers( {
        Handler => $validator,
        Name    => "Validator",
    },
    {
        Handler => $outputer,
    },
);

$m->disable_handler( "Validator" );

disable_handler

$t->disable_handler( 0 );            ## By location
$t->disable_handler( "Validator" );  ## By name
$t->disable_handler( $h0 );          ## By reference

Stops sending events to the indicated handler. Bye bestie, you're on mute. 🙈

enable_handler

$t->enable_handler( 0 );            ## By location
$t->enable_handler( "Validator" );  ## By name
$t->enable_handler( $h0 );          ## By reference

Stops sending events to the indicated handler.

ngl, that's literally what the original docs say here for enable_handler — "Stops sending events". I'm not fixing it, I'm just telling you what's on the page. Do with that information what you will. 💀

---

💜 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. Pick your fave, babe. 🎀

---

👑 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. Free as in freedom, bestie. 🕊️

---

and that's the whole page, pookie!! 💖 this was generated for perl v5.34.0, dated 2022-06-28, under XML::Filter::Tee(3pm). go forth and tee your events, you're gonna ate. 🌈✨