Data::...nerator(3pm)

💖 NAME 💖

Data::Stag::BaseGenerator — bestie, this is the base class for parsers and other event generators. It's the blueprint the other parser classes are built on. Periodt.

---

✨ SYNOPSIS ✨

First up, the writing-the-parser era:

# writing the parser
package MyParser;
use base qw(Data::Stag::BaseGenerator);

sub parse_fh {
  my ($self, $fh) = shift;

  my $lnum = 0;
  $self->start_event('data');
  while (<$fh>) {
    ++$lnum;
    $self->line_no($lnum);
    # do stuff
    $self->start_event('foo');

    # ...
    $self->event(blah=>5);

    #
    if (/incorrect_line/) {
       $self->parse_err('line not in correct format');
    }

    # ...
    $self->end_event('foo');
  }
  $self->pop_stack_to_depth(0);
}
1;

Then the using-the-parser era:

# using the parser
my $p = MyParser->new;
my $h = MyHandler->new; # see Data::Stag::BaseHandler
my $eh = Data::Stag->makehandler;
$p->handler($h);
$p->errhandler($eh);
$p->parse($file);

# result tree
print $h->stag->xml;

# write parse errs on standard err
printf \*STDERR $p->errhandler->stag->xml;

And the command-line era, two whole flavours:

# using the parser from the command line
unix> stag-parse.pl -p MyParser -w xml -e err.xml > out.xml

# using the parser from the command line via intermediate handler
unix> stag-handle.pl -p MyParser -m MyHandler -w xml -e err.xml > out.xml

---

🦋 DESCRIPTION 🦋

So. This is the base class for all parsers and event generators. Everyone else is just vibing off this one.

parsers/generators take some input (usually a filehandle, but a generator could be a socket listener, for example) and fire stag events.

The stag events are, and I need you to memorise these because they're the whole plot:

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

These events can be nested/hierarchical — very main character energy, they stack.

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

specialised handlers can be written to catch the events your parser throws. iykyk.

For example, you may wish to write a pod parser that generates nested events like this:

<pod>
 <section>
   <type>head1</type>
   <name>NAME</name>
   <text>Data::Stag - Structured Tags datastructures</text>
 </section>
 ...
</pod>

(see the source for Data::Stag::PodParser for details) — go read it, it's iconic.

You can write handlers that take the pod-xml and generate something — for example HTML.

parsers may encounter unexpected things along the way — they may throw an exception, and fall over — or they may choose to fire an error event. by default, error event streams are diverted to STDERR. You can create your own error handlers. 🫶

---

👑 PUBLIC METHODS 👑

new

Title: new

 Args:
Return: L<Data::Stag::BaseGenerator>
Example:

That's the CONSTRUCTOR, bestie. It makes the thing.

handler

Title: handler
Function: GET/SET ACCESSOR METHOD
 Args: handler L<Data::Stag::BaseHandler> optional
Return: L<Data::Stag::BaseHandler>
Example: $p->handler(MyHandler->new);

each parser has a handler — all events generated are passed onto the handler; the default handler simply sits there collecting events. no thoughts, just vibes and events. 💅

errhandler

Title: errhandler
Function: GET/SET ACCESSOR METHOD
 Args: handler L<Data::Stag::BaseHandler> optional
Return: L<Data::Stag::BaseHandler>
Example: $p->errhandler(Data::Stag->makehandler);

each parser has an error handler — if the parser encounters things it does not expect, it can pass errors to the errorhandler.

if no errorhandler is set, an XML event handler that writes to STDERR is used.

cache_errors

Title: cache_errors
 Args:
Return:
Example: $p->cache_errors

If this is called, all errors will be cached rather than written to STDERR.

The error list can be accessed like this:

$p->parse($fn);
@errs = $p->errhandler->stag->get_error;

parse

Example - $parser->parse($file1, $file2);
Returns -
Args    - filenames str-LIST

parses a file. 📂

parse

Example - $parser->parse_fh($fh)
Returns -
Args    - fh FILEHANDLE

parses an open filehandle. (yeah, same heading twice, and the example is the _fh one — that's just how it is, we don't gatekeep 🎀)

---

🧚 PROTECTED METHODS 🧚

These methods are only of interest if you are making your own parser/generator class. That's you, future parser author. 🌈

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

---

🌸 SEE ALSO 🌸

Data::Stag Data::Stag::BaseHandler

---

go forth and fire events, bestie. your tree is gonna be gorgeous. 💖

okay so that's the whole page — from the User Contributed Perl Documentation, perl v5.34.0, dated 2022-06-12. mwah, love you, bye!! 🎀✨💅