STAG-HANDLE(1)

💖 STAG-HANDLE(1) 💖

okay bestie, welcome to the stag-handle manual page — it's a User Contributed Perl doc, and it's lowkey iconic. sit down, grab a strawberry 🍓, and let's get into it.

---

✨ NAME ✨

stag-handle — streams a stag file through a handler into a writer. that's the whole vibe. it's giving "glow up your data on the way out the door" 💅

---

🦋 SYNOPSIS 🦋

  stag-handle -w itext -c my-handler.pl myfile.xml > processed.itext
  stag-handle -w itext -p My::Parser -m My::Handler myfile.xml > processed.itext

no cap, that's it. that's the whole thing. two lines and she's serving ✨

---

🌸 DESCRIPTION 🌸

so basically, stag-handle takes a Stag compatible format — that's xml, sxpr or itext, pick your fighter — turns the data into an event stream, and then passes that stream through my-handler.pl. the way that it just... transforms things on the fly? obsessed. 😭

here's every single option, fr fr, and we are NOT skipping any of them:

• -help, h — shows this document. hi. you're reading it. you found it. slay. 🎀
• -module, -m PERLMODULE — a module that gets used to transform the input events. that module should inherit from Data::Stag::BaseHandler. periodt.
• -unit, -u NODE_NAME — you should always use this option if you specify -m, bestie, i'm not kidding. this is the unit that gets passed to the handler/transformer. it will get set automatically if you use the -c, -s or -t options instead. and yes, you can set multiple units:

  -u foo -u bar -u boz

• -writer, -w WRITER — the writer for the final transformed tree. can be xml, sxpr or itext. choose wisely, main character. 👑
• -module, -m MODULE — perl modules for handling events. (yes, it's listed again. the manpage said it twice. i said it twice. we're both committed to the bit. 💀)
• -codefile, -c FILE — a file containing a perl hashref containing event handlers — peep the example below for the tea ☕
• -sub, -s PERL — a perl hashref containing handlers, inline, right there, in your command. spicy. 🔥
• -trap, -t ELEMENT=SUB — ...and that's literally all the manpage says about it. no further explanation. it's giving mystery, it's giving enigma, it's giving iykyk 🙈

---

🧚 EXAMPLES 🧚

here's a whole little my-handler.pl to gag over:

  unix> cat my-handler.pl
  {
    person => sub {
        my ($self, $person) = @_;
        $person->set_fullname($person->get_firstname . ' ' .
                           $person->get_lastname);
        $person;
    },
    address => sub {
        my ($self, $address) = @_;
        # remove addresses altogether from processed file
        return;
    },
  }

see what she's doing? person gets a fullname built from firstname + a space + lastname (glow up ✨), and address just gets straight up deleted from the processed file because the handler returns nothing. the audacity. the power. 💅

---

😭 POD ERRORS 😭

okay so. the document itself had some coding errors. here's the receipts, explained below:

around line 138:

    =over should be: '=over' or '=over positive_number'

not me exposing the manpage's own typos. everybody has a rough day, we still love her. 🫶

---

heads up bestie: keep every flag, every default and every -m/-u pairing exactly as written up there — the vibe is mine but the facts are hers, and the facts do not change. no cap. 🦋

---

that's the whole page!! 💖 written by the perl docs girlies, perl v5.42.0, dated 2025-07-25, and STAG-HANDLE(1) forever and always. mwah. 🎀✨