Pegex::Receiver(3pm)

💖 Pegex::Receiver 💖

okay so bestie, welcome to Pegex::Receiver — it's the base class for ALL Pegex receivers, and it lives in the User Contributed Perl Documentation section (that's the 3pm situation, iykyk). it's tiny, it's iconic, and honestly? it's giving minimalism. let's get into it 🦋

---

✨ SYNOPSIS ✨

here's the whole vibe of how you'd actually use this thing:

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;
}

like, that's it. that's the whole assignment. 💅

---

🌸 DESCRIPTION 🌸

so 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. basically: the parser finds stuff, the receiver catches it. a receiver hands you action methods so you can turn that parsed data into whatever the parser was actually supposed to do. main character energy, honestly.

this class right here is the base class of all Pegex receiver classes. 👑

and here's the gag: it doesn't do much of anything, which is the correct thing to do. no cap. if you use this class as your receiver, it won't do any extra work — zero side quests, zero surprises. and if you do want a receiver base class that'll help organize your matches by default? go look at Pegex::Tree. that one's got your back. 🫶

🧚 How A Receiver Works

a Pegex grammar is made up of three little ingredients: named-rules, regexes, and groups.

• when a regex matches → the parser makes an array of its capture strings.
• when a group matches → the parser makes an array of all the submatch arrays.

and that's how a parse tree forms, bestie. it builds itself. 🌈

then, when a named-rule matches → an action method gets called over in the receiver class. that method gets handed the current parse tree, and whatever it returns becomes the new parse tree as far as the parser is concerned.

the way this makes for such a very elegant and understandable API... obsessed. truly. 😭💖

---

💅 API 💅

this section documents the methods you can include in a receiver subclass. like, these are the ones you're allowed to write. go off.

• got_$rulename($got) — an action method for a specific, named rule. for example:

sub got_rule42 {
    my ($self, $got) = @_;
    ...
    return $result;
}

the $got value that gets passed in is the current value of the parse tree. and what you return? that becomes whatever you want the new value to be. your call, your rules. ✨

• gotrule($got) — the action method for a named rule that does not have a specific action method of its own. the catch-all bestie.
• initial() — called at the beginning of a parse operation, before the parsing begins. the little pre-game pep talk. 🎀
• final($got) — called at the end of a parse operation. and listen: whatever this action returns will be the result of the parse. no pressure or anything. 😌

⭐ Methods

• parser — an attribute containing the parser object that is currently running. this is very useful for introspecting what's happening, and possibly modifying the grammar on the fly. (Experts only! like, genuinely. don't just yolo this. 🔥)
• 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. and heads up: the array is modified in place, but it's also the return value. so like, both. it's giving multitasking. 💫

---

👑 AUTHOR 👑

Ingy döt Net <ingy@cpan.org>

---

🍓 COPYRIGHT AND LICENSE 🍓

Copyright 2010-2020. Ingy döt 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>

---

and that's the whole page, bestie!! 🎀 this was perl v5.36.0, dated 2022-11-19 — shoutout to the Pegex::Receiver(3pm) era, we love a tiny base class that does exactly nothing on purpose. slay, stay parsed, mwah 💖✨🦋