NAME¶
Pegex::Receiver - Base Class for All Pegex Receivers
SYNOPSIS¶
package MyReceiver;
use base 'Pegex::Receiver';
# Handle data for a specific rule
sub got_somerulename {
my ($self, $got) = @_;
# ... process ...
return $result;
}
# Handle data for any other rule
sub gotrule {
my ($self, $got) = @_;
return $result;
}
# Pre-process
sub initial { ... }
# Post-process
sub final {
...;
return $final_result;
}
DESCRIPTION¶
In Pegex, a
receiver is the class object that a
parser passes
captured data to when a
rule in a
grammar matches a part of an
input stream. A receiver provides
action methods to turn parsed
data into what the parser is intended to do.
This is the base class of all Pegex receiver classes.
It doesn't do much of anything, which is the correct thing to do. If you use
this class as your receiver if won't do any extra work. See Pegex::Tree for a
receiver base class that will help organize your matches by default.
How A Receiver Works¶
A Pegex grammar is made up of
named-rules,
regexes, and
groups. When a
regex matches, the parser makes array of its
capture strings. When a
group matches, the parser makes an array of all
the submatch arrays. In this way a
parse tree forms.
When a
named-rule matches, an action method is called in the receiver
class. The method is passed the current
parse tree and returns what
parser will consider the new parse tree.
This makes for a very elegant and understandable API.
API¶
This section documents the methods that you can include in receiver subclass.
- "got_$rulename($got)"
- An action method for a specific, named rule.
sub got_rule42 {
my ($self, $got) = @_;
...
return $result;
}
The $got value that is passed in is the current value of the parse tree.
What gets returned is whatever you want to new value to be.
- "gotrule($got)"
- The action method for a named rule that does not have a specific action
method.
- "initial()"
- Called at the beginning of a parse operation, before the parsing
begins.
- "final($got)"
- Called at the end of a parse operation. Whatever this action returns, will
be the result of the parse.
Methods¶
- "parser"
- An attribute containing the parser object that is currently running. This
can be very useful to introspect what is happening, and possibly modify
the grammar on the fly. (Experts only!)
- "flatten($array)"
- A utility method that can turn an array of arrays into a single array. For
example:
$self->flatten([1, [2, [3, 4], 5], 6]);
# produces [1, 2, 3, 4, 5, 6]
Hashes are left unchanged. The array is modified in place, but is also the
return value.
AUTHOR¶
Ingy doet Net <ingy@cpan.org>
COPYRIGHT AND LICENSE¶
copyright 2010-2014. Ingy doet Net.
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
See <
http://www.perl.com/perl/misc/Artistic.html>