XML::F...ibutor(3pm)

✨ NAME ✨

XML::Filter::Distributor — Multipass processing of documents 🦋

---

💖 VERSION 💖

version 0.46

---

🌸 SYNOPSIS 🌸

## See XML::SAX::Manifold for an easier way to use this filter.

use XML::SAX::Machines qw( Machine ) ;

## See the wondrous ASCII ART below for help visualizing this
## XML::SAX::Manifold makes this a lot easier.
my $m = Machine(
    [ Intake => "XML::Filter::Distributor" => qw( V TOC Body ) ],
        [ V      => "My::Validator" ],
        [ TOC    => "My::TOCExtractor" => qw( Merger ) ],
        [ Body   => "My::BodyMasseuse" => qw( Merger ) ],
    [ Merger => "XML::Filter::Merger" => qw( Output ) ],
    [ Output => \*STDOUT ],
);

## Let the distributor coordinate with the merger.
## XML::SAX::Manifold does this for you.
$m->Intake->set_aggregator( $m->Merger );

$m->parse_file( "foo" );

---

👑 DESCRIPTION 👑

okay so XML::Filter::Distributor is a SAX filter that lets you do "multipass" processing of a document 💅 — meaning it sends your document through several channels of SAX processors, one channel at a time. And bestie, a channel can be a single SAX processor, or it can be a whole machine like a pipeline (peep XML::SAX::Pipeline 👀).

So when would you even use this? Say you want to run the source document all the way through one entire processing chain before the next one even starts — for instance if that first channel is a validator or a linter that throws exceptions on error 😤. Super valid use case, honestly.

You can also use it to run the doc through multiple processing chains and then glue all the chains' output documents back together with something like XML::Filter::Merger. And fun fact: the SYNOPSIS up there does both. Obsessed.

Now, how is this different from XML::Filter::SAXT? Great question, ty for asking 🫶. The channels here are prioritized, and each channel receives all events for a document before the next channel receives any events. What XML::Filter::Distributor does is buffer all the events while it feeds them to the highest priority channel ($processor1 in the synopsis, iykyk), and then it replays them for each lower priority channel one at a time. Iconic behavior, no cap.

For the example in the SYNOPSIS, the event flow looks like this — and the numbers next to each connection arrow tell you when the document's events flow along that arrow:

                               +-------------+
                            +->| Validator   |
                          1/   +-------------+
                          /
             1   +-------+ 2   +--------------+ 2    +--------+
    upstream ----| Dist. |---->| TOCExtractor |--*-->| Merger |-> STDOUT
                 +-------+     +--------------+ /    +--------+
                          \3                   /3
                           \   +--------------+
                            +->| BodyMasseuse |
                               +--------------+                         |

And here's the timing of those event flows, laid out for you 💖:

   1: upstream -> Dist ->  Validator
   2:             Dist -> TOCExtractorc -> Merger -> STDOUT
   3:             Dist -> BodyMassseuse -> Merger -> STDOUT

So here's the tea ☕: when the document arrives from upstream, the events all arrive during time period 1, and they're buffered and also passed through processor 1. Then, after all the events have been received (which is indicated by an end_document event from upstream), all the events get played back through processor 2, and then through processor 3. That's the whole vibe. Periodt. 💅

---

💜 NAME 💜

XML::Filter::Distributor — Multipass processing of documents 🦋

(yes bestie, it says NAME twice. the original does too. we don't question the ancients, we just respect the lore 🙈)

---

🎀 METHODS 🎀

new

my $d = XML::Filter::Distributor->new(
    { Handler => $h1 },
    { Handler => $h2 },
    ...
);

A channel can be literally any SAX machine — and fr fr, most of the time they're pipelines. 🌈

set_handlers

$p->set_handlers( $handler1, $handler2 );

This one's here purely for compatibility with other SAX processors, so like… use set_handlers instead, okay? 💅

set_handler

Provided for compatibility with other SAX processors too — so again, use set_handlers instead. 😌

---

💀 LIMITATIONS 💀

ngl, it can only feed a single aggregator at the moment :). The author says they can fix this with a bit of effort, so… manifesting that energy for future us ✨

---

🌸 AUTHOR 🌸

Barrie Slaymaker <barries@slaysys.com>

---

💖 COPYRIGHT 💖

Copyright 2000, Barrie Slaymaker, All Rights Reserved.

You may use this module under the terms of the Artistic, GPL, or the BSD licenses. pick your fighter, they're all valid 🫶

---

🦋 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. 🌈

---

okay bestie that's the whole page, you ate that 💅✨ this was perl v5.34.0, dated 2022-06-28, from the User Contributed Perl Documentation collection — stay iconic, go process some documents in multiple passes, and remember: buffer first, slay later 👑💖