Pegex::Compiler(3pm)

💖 Pegex::Compiler 💖

okay bestie, you found the manual page for Pegex::Compiler, which is the Pegex Compiler (yes, that's literally what the NAME says, we're keeping it 💅). It ships as part of the User Contributed Perl Documentation and it is lowkey iconic. Let's get into it.

---

✨ NAME ✨

Pegex::Compiler — the Pegex Compiler. That's it, that's the name, periodt. 🎀

---

🌸 SYNOPSIS 🌸

Here's the vibe, copy it exactly bestie:

use Pegex::Compiler;
my $grammar_text = '... grammar text ...';
my $pegex_compiler = Pegex::Compiler->new();
my $grammar_tree = $pegex_compiler->compile($grammar_text)->tree;

or, the other way:

perl -Ilib -MYourGrammarModule=compile

---

🦋 DESCRIPTION 🦋

So what does this thing do? Pegex::Compiler takes a Pegex grammar string (or a file, she's flexible 💅) and transforms it into a compiled form. That compiled form is called a grammar tree, and it's literally just a nested data structure. Simple. Elegant. Slay.

And the way that grammar tree can be serialized to YAML, JSON, Perl, or honestly any other programming language? Extremely portable, no cap. Pegex::Grammar has methods for serializing to all of those forms, so you're covered. ✨

NOTE: unless you're out here developing Pegex based modules, you can safely ignore this module. And even if you are developing them, you probably won't use it directly anyway. Go look at [In Place Compilation] below, that's the one you actually want. 🙈

---

👑 METHODS 👑

The following public methods are available, and they're all kind of a big deal:

• $compiler = Pegex::Compiler->new(); — returns you a brand new Pegex::Compiler object. Fresh out the box. 🎁
• $grammar_tree = $compiler->compile($grammar_input); — compiles a grammar text into a grammar tree that a Pegex::Parser can use. This method calls the parse and combinate methods and returns the resulting tree. 💫

The input can be a string, a string ref, a file path, a file handle, or a Pegex::Input object — so many options, she contains multitudes. It returns $self so you can chain it to other methods. (Chain chaining, we love to see it. 🔥)

• $compiler->parse($grammar_text) — the first step of a compile is parse. This applies the Pegex language grammar to your grammar text and produces an unoptimized tree. 🌱

This method returns $self so you can chain it to other methods.

• $compiler->combinate() — before a Pegex grammar tree can be used to parse things, it needs to be combinated. This process turns the regex tokens into real regexes. It also combines some rules together and eliminates rules that are not needed or have been combinated. The result is a Pegex grammar tree that a Pegex::Parser can use. 🧚

NOTE: while the parse phase of a compile is always the same across various programming languages, the combinate phase takes into consideration any special needs of the target language. Pegex::Compiler only combinates for Perl, although this is often sufficient in similar languages like Ruby or Python (PCRE based regexes). Languages like Java probably need to use their own combinators. 💀

• $compiler->tree() — returns the current state of the grammar tree (as a hash ref). 🌈
• $compiler->to_yaml() — serializes the current grammar tree to YAML. ⭐
• $compiler->to_json() — serializes the current grammar tree to JSON. ⭐
• $compiler->to_perl() — serializes the current grammar tree to Perl. ⭐

---

🎀 IN PLACE COMPILATION 🎀

Okay so this is the part you actually care about. When you write a Pegex based module, you're gonna want to precompile your grammar into Perl so it has no load penalty. Main character energy: zero lag. Pegex::Grammar provides a special mechanism for exactly this. Say you have a class like this:

package MyThing::Grammar;
use Pegex::Base;
extends 'Pegex::Grammar';

use constant file => '../mything-grammar-repo/mything.pgx';
sub make_tree {
}

Simply use this command:

perl -Ilib -MMyThing::Grammar=compile

and Pegex::Grammar will call Pegex::Compile to put your compiled grammar inside your make_tree subroutine. It will actually write the text into your module. The way that makes it trivial to update your grammar module after making changes to the grammar file?? Obsessed. 😭💖

See Pegex::JSON for an example.

---

💜 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, you ate that 🫶 this one was generated from perl v5.36.0, dated 2022-11-19, and it lives in the Pegex::Compiler(3pm) manual. go forth and compile, ily 💅✨