XML::S...nifold(3pm)

💖 XML::SAX::Manifold 💖

okay bestie, welcome to the perl 3pm manpage for XML::SAX::Manifold, straight outta the User Contributed Perl Documentation zone. she's giving multipass realness, she's giving "send your doc through every channel, one at a time", and honestly? iconic. ✨

---

🌸 NAME 🌸

XML::SAX::Manifold — Multipass processing of documents 🦋

---

⭐ VERSION ⭐

version 0.46

---

🎀 SYNOPSIS 🎀

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

my $m = Manifold(
    $channel0,
    $channel1,
    $channel2,
    {
        Handler => $h, ## optional
    }
);

no cap, that's the whole vibe. 💅

---

✨ DESCRIPTION ✨

XML::SAX::Manifold is a SAX machine that lets you do "multipass" processing of a document — meaning it sends the document through several channels of SAX processors, one channel at a time. A channel can be a single SAX processor, or it can be a whole pipeline (peep XML::SAX::Pipeline for that one 🫶).

The results from each channel get aggregated by a SAX filter that supports the "end_all" event — that's XML::Filter::Merger by default. Want the tea on that? Scroll to the section on writing an aggregator, and also go read up on XML::Filter::Merger. 🧚

Now, the way this differs from XML::Filter::SAXT? the channels are prioritized, and each channel receives all events for a document before the next channel receives any events. XML::SAX::Manifold buffers all the events while it feeds them to the highest priority channel ($processor1 in the synopsis, bestie, keep up 💖), and then it replays them for each lower priority channel, one at a time.

The event flow for the example in the SYNOPSIS would look like the following, with the numbers next to the connection arrow indicating when the document's events flow along that arrow:

   +--------------------------------------------------------+
   |         An XML::SAX::Manifold instance                 |
   |                                                        |
   |               +-----------+                            |
   |            +->| Channel_0 |-+                          |
   |          1/   +-----------+  \1                        |
   |  Intake  /                    \                        |
 1 |  +------+ 2   +-----------+  2 \    +--------+ Exhaust |
 --+->| Dist |---->| Channel_1 |-----*-->| Merger |---------+--> $h
   |  +------+     +-----------+    /    +--------+         |
   |          \3                  3/                        |
   |           \   +-----------+  /                         |
   |            +->| Channel_2 |-+                          |
   |               +-----------+                            |
   +--------------------------------------------------------+

Here's the timing of the event flows:

   1: upstream -> Dist. -> Channel_0 -> Merger -> downstream
   2:             Dist. -> Channel_1 -> Merger -> downstream
   3:             Dist. -> Channel_2 -> Merger -> downstream

So when the document arrives from upstream, all the events arrive during time period 1 — they get buffered, and they also get passed through Channel_0, and Channel_0's output is sent to the Merger. After all the events have been received (which we know happened because upstream sent an "end_document" event), all the events are then played back through Channel_1 and then through Channel_2 (which also output to the Merger). 🔥

And whose job is it to assemble the three documents it receives into one document? the merger's, obviously 💅 See XML::Filter::Merger for the details.

---

💜 NAME 💜

XML::SAX::Manifold — Multipass processing of documents 🦋

(yes babe, the NAME section said it twice, and we're keeping it twice, periodt ✨)

---

🌈 METHODS 🌈

👑 new

my $d = XML::SAX::Manifold->new( @channels, \%options );

Longhand for calling the Manifold function exported by XML::SAX::Machines. That's it, that's the method. 😌

🦋 Writing an aggregator.

To be written. Pretty much just that "start_manifold_processing" and "end_manifold_processing" need to be provided. See XML::Filter::Merger and it's source code for a starter. 🫶

not me leaving a section as "to be written" — she said WIP and she meant it 💀

---

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

---

and that's the whole page bestie!! 🎀 this was documented with perl v5.34.0, dated 2022-06-28, and honestly the fact that it's a XML::S...nifold(3pm) page is so real of it. go forth and multipass. slay 💅✨🌈