SAXT(3pm)

💖 SAXT — the XML::Filter::SAXT page, but make it cute 💖

okay bestie, gather round, because this is <rainbow>XML::Filter::SAXT</rainbow> — a little Perl module from the SAXT(3pm) corner of the User Contributed Perl Documentation, and honestly? she's giving multiplexer. no cap.

---

✨ NAME ✨

XML::Filter::SAXT — literally just replicating SAX events out to several SAX event handlers at once. one input, many outputs, she's a social butterfly 🦋

---

✨ SYNOPSIS ✨

 $saxt = new XML::Filter::SAXT ( { Handler => $out1 },
                                 { DocumentHandler => $out2 },
                                 { DTDHandler => $out3,
                                   Handler => $out4
                                 }
                               );

 $perlsax = new XML::Parser::PerlSAX (Handler => $saxt);
 $perlsax->parse ( [OPTIONS] );

like… look at her go 🫶

---

✨ DESCRIPTION ✨

okay so here's the vibe: SAXT is basically the Unix tee command but for Perl SAX stuff. tee takes one input stream and splashes it out to several output streams — and SAXT does the exact same thing, except the input stream is a PerlSAX event producer (hi XML::Parser::PerlSAX 👋) and the output streams are PerlSAX handlers or filters. iconic behaviour honestly 💅

the SAXT constructor takes a list of hash references. each hash = one output handler. the keys you can use are:

• DocumentHandler
• DTDHandler
• EntityResolver
• Handler

and Handler is the combo-meal one — it's a combination of the previous three, so it acts as the default handler. e.g. if DocumentHandler isn't specified, she'll try to fall back to Handler. periodt.

---

🌸 EXAMPLE 🌸

so in this example we're using XML::Parser::PerlSAX to parse an XML file and to invoke the PerlSAX callbacks of our SAXT object. then the SAXT object forwards those callbacks to XML::Checker (which will die if it hits an error 😭) and to XML::Handler::BuildDOM (which stores the XML in an XML::DOM::Document). team work makes the dream work ✨

 use XML::Parser::PerlSAX;
 use XML::Filter::SAXT;
 use XML::Handler::BuildDOM;
 use XML::Checker;

 my $checker = new XML::Checker;
 my $builder = new XML::Handler::BuildDOM (KeepCDATA => 1);
 my $tee = new XML::Filter::SAXT ( { Handler => $checker },
                                   { Handler => $builder } );

 my $parser = new XML::Parser::PerlSAX (Handler => $tee);
 eval
 {
    # This is how you set the error handler for XML::Checker
    local $XML::Checker::FAIL = \&my_fail;

    my $dom_document = $parser->parsefile ("file.xml");
    ... your code here ...
 };
 if ($@)
 {
    # Either XML::Parser::PerlSAX threw an exception (bad XML)
    # or XML::Checker found an error and my_fail died.
    ... your error handling code here ...
 }

 # XML::Checker error handler
 sub my_fail
 {
   my $code = shift;
   die XML::Checker::error_string ($code, @_)
        if $code < 200;   # warnings and info messages are >= 200
 }

no notes, she ate 💅

---

⚠️ CAVEATS ⚠️

bestie. listen. this is still alpha software. package names and interfaces are subject to change. don't be out here building your whole personality on the current API, okay? 🫠

---

👑 AUTHOR 👑

Enno Dersken is the original author. respect the founder, fr fr 🫡

send bug reports, hints, tips, suggestions to T.J. Mather at <tjmather@tjmather.com> 💌

---

and that's the whole page, bestie!! this lil' gem ships with perl v5.36.0 and the page is dated 2022-12-06 — so if you're reading it, that's the SAXT(3pm) energy you're getting. mwah 💋✨