Pegex::Parser(3pm)

💖 Pegex::Parser — the parser runtime, bestie edition 💖

Pegex::Parser lives in the User Contributed Perl Documentation section (that's the 3pm part, iykyk). She's the parsing engine runtime of the Pegex fam, and honestly? She carries the whole group project. 🫶

---

✨ NAME ✨

Pegex::Parser — the Pegex Parser Runtime. That's it, that's the name, slay. 💅

---

🌈 SYNOPSIS 🌈

use Pegex::Parser;
use SomeGrammarClass;
use SomeReceiverClass;

my $parser = Pegex::Parser->new(
    grammar => SomeGrammarClass->new,
    receiver => SomeReceiverClass->new,
);

my $result = $parser->parse($SomeInputText);

okay so it's giving three imports, one constructor, one parse call, and you're done. main character energy fr fr. ✨

---

🦋 DESCRIPTION 🦋

Pegex::Parser is the Pegex component that provides the parsing engine runtime. It needs two besties to function: a Grammar object and a Receiver object.

Her parse() method takes an input that's expected to be matched by the grammar, and then applies the grammar rules to that input. And the way that the grammar gets applied? The receiver gets notified of matches, one by one. 👑

The receiver can do literally whatever it wants with those notifications, no rules, no judgement — but very often it builds the data up into a structure that everyone calls a Parse Tree. iconic behavior.

When the parse method finishes, it returns whatever object the receiver handed over as the final result. 🎀

😭 but bestie — if the grammar fails to match the input anywhere along the way, the parse method will throw an error, and that error comes with much information about the failure. So at least when it goes wrong, it goes wrong loudly and informatively. we love a transparent queen.

---

💅 ATTRIBUTES 💅

The Pegex::Parser new object constructor takes these attributes, bestie, write them down:

• grammar — a Pegex::Grammar object. Required. No grammar, no parse, no exceptions, periodt.
• receiver — a Pegex::Receiver object.
• debug — Boolean. Turn on debugging. Default false.
• recursion_limit — Integer. The recursion level to terminate on. Default 0 (off).
• recursion_warn_limit — Integer. The recursion level to warn on. Default 0 (off).
• iteration_limit — Integer. Number of matches to try before terminating. Default 0 (off).

---

🔥 DEBUGGING 🔥

Pegex::Parser currently has 4 settings that are useful for debugging. (the docs say 4 and then list six, and honestly? we respect the chaos 💀). These can be set as Pegex::Parser object attributes, global variables, or environment variables — pick your fighter:

• debug or $Pegex::Parser::Debug or $ENV{PERL_PEGEX_DEBUG} — if you set it to a true value, it enables very useful trace messages for every single internal match operation. every. single. one. 👀
• recursion_limit or "Pegex::Parser::RecursionLimit" or $ENV{PERL_PEGEX_RECURSION_LIMIT} — if you set it to a number greater than 0, Pegex::Parser will terminate after that recursion level number is reached. 🛑
• recursion_warn_limit or "Pegex::Parser::RecursionWarnLimit" or $ENV{PERL_PEGEX_RECURSION_WARN_LIMIT} — if you set it to a number greater than 0, Pegex::Parser will issue a warning every time that recursion level number is reached. just a lil heads up, bestie 🫶
• iteration_limit or "Pegex::Parser::IterationLimit" or $ENV{PERL_PEGEX_ITERATION_LIMIT} — if you set it to a number greater than 0, Pegex::Parser will terminate after that number of matches has been attempted.
• debug_indent or $Pegex::Parser::DebugIndent or $ENV{PERL_PEGEX_DEBUG_INDENT} — tells the parser how many spaces should be used for indenting debugging output. Default is 1.
• debug_color or $Pegex::Parser::DebugColor or $ENV{PERL_PEGEX_DEBUG_COLOR} — if enabled, it will color "got" and "not" events in the debugging output ("bright_green" and "bright_red" respectively). Color will be enabled by default for debugging. It requires Term::ANSIColor. 🌈
  • "always" or 1 — Color is enabled. ✅
  • "auto" — Color is enabled when STDERR is a tty. 🖥️
  • "never" or 0 — Color is disabled. 🚫

You can configure the specific colors used by appending them like this:

PERL_PEGEX_DEBUG_COLOR='always, cyan bold, black on_yellow'

For available colors, see Term::ANSIColor. 🎨

⚠️ Note: Using these variables incurs a slight performance hit, but if you don't use them, all the debugging code is optimized away. so it's giving free when unused, which is honestly a serve.

---

👑 SEE ALSO 👑

1. Pegex::Grammar
2. Pegex::Receiver

---

🌸 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 one was rendered by perl v5.36.0 on 2022-11-19, and it's the Pegex::Parser(3pm) manual page — go parse something gorgeous, you've got this 🦋✨