Data::...Handler(3pm)

💖 NAME 💖

Data::Stag::BaseHandler — bestie, this is the base class for writing tag stream handlers. It's the vibe blueprint every other handler copies from. (It lives in the User Contributed Perl Documentation manual, and the header calls it Data::...Handler(3pm) — that's the page you're on rn 💅)

---

✨ SYNOPSIS ✨

okay so here's the whole energy, in code:

# EXAMPLE 1
package MyPersonHandler;
use base qw(Data::Stag::BaseHandler);

# handler that prints <person> nodes as they are parsed;
# after each <person> node is intercepted, it is discarded
# (it does not go to form the final tree)
sub e_person {
    my $self = shift;
    my $node = shift;
    printf "Person name:%s address:%s\n",
      $node->sget('name'), $node->sget('address');
    return;               # prune this from tree
}
1;

# EXAMPLE 2
package MyStatsHandler;
use base qw(Data::Stag::BaseHandler);

# handler that modifies tree as it goes
# changes <measurement><unit>inch</unit><quantity>10</quantity></measurement>
# to      <measurement><unit>cm</unit><quantity>25</quantity></measurement>
sub e_measurement {
    my $self = shift;
    my $node = shift;
    if ($node->sget('unit') eq 'inch') {
        $node->set('unit', 'cm');
        $node->set('quantity', $node->get('quantity') * 2.5);
    }
    return $node;     # replace <measurement> with new data in result tree
}
1;

# Using the handlers
my $handler = MyHandler->new;
my $stag = Data::Stag->parse(-fh=>$fh, -handler=>$handler);

# Using a handler from the command line:
unix> stag-handle.pl -m MyHandler input.xml > post-processed.xml

---

🌸 DESCRIPTION 🌸

It's the Default Simple Event Handler, and every other handler inherits from this class. Periodt.

Also peep Data::Stag and Data::Stag::BaseGenerator — they're the other two-thirds of this trio.

So Stag has an event-handling architecture, right? Parsers or generators generate or fire events. And these events can be hierarchical/nested, exactly like stag nodes are. The events get caught by handlers. And by default, whatever events nobody catches just stack up to form stag trees. Cute, honestly. 🫶

Stag ships with built-in parsers for parsing xml, sxpr and itext data. You can build your own parsers for your own formats, specific to your own data — those should inherit from Data::Stag::BaseGenerator.

Stag also has built-in handlers for these formats. And you can construct your own — either as modules that inherit from this one, or as hashes of anonymous subroutines. Two paths, both valid. ✨

If you're writing your own handler that writes out to another format, you may wish to inherit from Data::Stag::Writer.

🎀 CATCHING EVENTS 🎀

This class catches Data::Stag node events (start, end and body) and lets the subclassing module intercept them. Unintercepted events get pushed into a tree. The final tree is returned at the end of a parse() call. That's the whole deal.

This class can take SAX events and turn them into simple Data::Stag events. Glow-up behaviour fr fr. 💅

the events recognised are

start_event(node-name)
evbody(node-data)
end_event(node-name)

and also

event(node-name, node-data|[nodes])

which is just a wrapper for the other events. Nothing more, nothing less, no cap.

you can either intercept these methods; or you can define methods

s_<element_name>
e_<element_name>

that get called on the start/end of an event; you can dynamically change the structure of the tree by returning nodes from these methods. Main character energy: you're literally rewriting the tree as it's built.

# the follow handler prunes <foo> nodes from the tree, and writes
# out data from the <person> node
# when parsing large datasets, it can be a good idea to prune nodes
# from the tree, so the result tree of the parse is not too big
my $h = Data::Stag->makehandler( foo => 0,
                                 person => sub {
                                     my $self = shift;
                                     my $node = shift;
                                     printf "Person name:%s address:%s\n",
                                       $node->sget('name'), $node->sget('address');
                                     return;
                                 });
my $parser = MyParser->new;
$parser->handler($h);
$parser->parse(-fh=>$fh);
my $result_tree = $h->stag;

---

👑 PUBLIC METHODS - 👑

new

• Title: new
• Args:
• Return: L<Data::Stag::BaseHandler>
• Example:

returns the tree that was built from all uncaught events

tree (stag)

• Title: tree
• Synonym: stag
• Args:
• Return: L<Data::Stag>
• Example: print $parser->handler->tree->xml;

returns the tree that was built from all uncaught events

---

🌈 CAUGHT EVENTS 🌈

A Data::Stag::BaseGenerator class will generate events by calling the following methods on this class:

• start_event NODENAME
• evbody DATA
• end_event NODENAME {optional}
• event NODENAME DATA

These events can be nested/hierarchical. Nested events, nesting inside nested events, like a little matryoshka of data. 🦋

If uncaught, these events are stacked into a stag tree, which can be written as xml or one of the other stag formats.

---

💅 PROTECTED METHODS - 💅

s_*

• Args: handler L<Data::Stag::BaseHandler>
• Return:
• Example:

autogenerated method — called by the parser when ever it starts a node; * matches the node name.

override this class providing the name of the node you wish to intercept

e_*

• Args: handler L<Data::Stag::BaseHandler>, node L<Data::Stag>
• Return: node L<Data::Stag>
• Example:

autogenerated method — called by the parser when ever it ends a node; * matches the node name.

override this class providing the name of the node you wish to intercept

CONSUMES

define this in your handler class to make explicit the list of node names that your parser consumes; this is then used if your handler is placed in a chain

package MyHandler;
use base qw(Data::Stag::BaseHandler);
sub CONSUMES {qw(person city)}
sub e_person {....}
sub e_city   {....}

depth

• Title: depth
• Args:
• Return: depth int
• Example:

depth of the nested event tree

up

• Title: up
• Args: dist int
• Return: node stag
• Example: $stag->up(-2);

when called when intercepting a node <foo>, this will look dist up the tree to find the container node

For example, if our data contains the node <blah> below:

<blah>
  <foo>
    <a>1</b>
  </foo>
  <foo>
    <a>2</b>
  </foo>
</blah>

# and we have the following code:
$h = Data::Stag->makehandler(foo=>sub {
                                       my ($self, $foo) = @_;
                                       print $foo->up(1)->xml;
                                       return});

The <foo> handler will be called twice; it will print the structure of the containing <blah> node, but the first time round, the <blah> node will not be complete.

bestie, note that last bit — the first time it fires, the container is still half-baked. Not a bug, just how it is. 😭

up_to

• Title: up_to
• Args: nodename str
• Return: node stag
• Example: $stag->up_to('blah');

Similar to up(), but it will go up the container event nodes until it finds one with the matching name.

---

and that's the whole page, bestie!! you now know how to catch events, prune nodes, rewrite trees mid-parse, and be the main character of your own data pipeline. slay. 💖✨

This was written by the User Contributed Perl Documentation crew, this particular build ships with perl v5.34.0 and is dated 2022-06-12, and yeah the page header/footer both call it Data::...Handler(3pm) — mystery ellipsis and all. bye bestie 🎀🦋