.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Pegex::Compiler 3pm"
.TH Pegex::Compiler 3pm "2022-11-19" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Pegex::Compiler \- Pegex Compiler
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&    use Pegex::Compiler;
\&    my $grammar_text = \*(Aq... grammar text ...\*(Aq;
\&    my $pegex_compiler = Pegex::Compiler\->new();
\&    my $grammar_tree = $pegex_compiler\->compile($grammar_text)\->tree;
.Ve
.PP
or:
.PP
.Vb 1
\&    perl \-Ilib \-MYourGrammarModule=compile
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Pegex::Compiler transforms a Pegex grammar string (or file) into a
compiled form. The compiled form is known as a grammar tree, which is simply a
nested data structure.
.PP
The grammar tree can be serialized to \s-1YAML, JSON,\s0 Perl, or any other
programming language. This makes it extremely portable. Pegex::Grammar has
methods for serializing to all these forms.
.PP
\&\s-1NOTE:\s0 Unless you are developing Pegex based modules, you can safely ignore
      this module. Even if you are you probably won't use it directly. See [In
      Place Compilation] below.
.SH "METHODS"
.IX Header "METHODS"
The following public methods are available:
.ie n .IP """$compiler = Pegex::Compiler\->new();""" 4
.el .IP "\f(CW$compiler = Pegex::Compiler\->new();\fR" 4
.IX Item "$compiler = Pegex::Compiler->new();"
Return a new Pegex::Compiler object.
.ie n .IP """$grammar_tree = $compiler\->compile($grammar_input);""" 4
.el .IP "\f(CW$grammar_tree = $compiler\->compile($grammar_input);\fR" 4
.IX Item "$grammar_tree = $compiler->compile($grammar_input);"
Compile a grammar text into a grammar tree that can be used by a
Pegex::Parser. This method is calls the \f(CW\*(C`parse\*(C'\fR and \f(CW\*(C`combinate\*(C'\fR methods and
returns the resulting tree.
.Sp
Input can be a string, a string ref, a file path, a file handle, or a
Pegex::Input object. Return \f(CW$self\fR so you can chain it to other methods.
.ie n .IP """$compiler\->parse($grammar_text)""" 4
.el .IP "\f(CW$compiler\->parse($grammar_text)\fR" 4
.IX Item "$compiler->parse($grammar_text)"
The first step of a \f(CW\*(C`compile\*(C'\fR is \f(CW\*(C`parse\*(C'\fR. This applies the Pegex language
grammar to your grammar text and produces an unoptimized tree.
.Sp
This method returns \f(CW$self\fR so you can chain it to other methods.
.ie n .IP """$compiler\->combinate()""" 4
.el .IP "\f(CW$compiler\->combinate()\fR" 4
.IX Item "$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 can be used by a
Pegex::Parser.
.Sp
\&\s-1NOTE:\s0 While the parse phase of a compile is always the same for various
      programming languages, the combinate phase takes into consideration and
      special needs of the target language. Pegex::Compiler only combinates
      for Perl, although this is often sufficient in similar languages like
      Ruby or Python (\s-1PCRE\s0 based regexes). Languages like Java probably need
      to use their own combinators.
.ie n .IP """$compiler\->tree()""" 4
.el .IP "\f(CW$compiler\->tree()\fR" 4
.IX Item "$compiler->tree()"
Return the current state of the grammar tree (as a hash ref).
.ie n .IP """$compiler\->to_yaml()""" 4
.el .IP "\f(CW$compiler\->to_yaml()\fR" 4
.IX Item "$compiler->to_yaml()"
Serialize the current grammar tree to \s-1YAML.\s0
.ie n .IP """$compiler\->to_json()""" 4
.el .IP "\f(CW$compiler\->to_json()\fR" 4
.IX Item "$compiler->to_json()"
Serialize the current grammar tree to \s-1JSON.\s0
.ie n .IP """$compiler\->to_perl()""" 4
.el .IP "\f(CW$compiler\->to_perl()\fR" 4
.IX Item "$compiler->to_perl()"
Serialize the current grammar tree to Perl.
.SH "IN PLACE COMPILATION"
.IX Header "IN PLACE COMPILATION"
When you write a Pegex based module you will want to precompile your grammar
into Perl so that it has no load penalty. Pegex::Grammar provides a special
mechanism for this. Say you have a class like this:
.PP
.Vb 3
\&    package MyThing::Grammar;
\&    use Pegex::Base;
\&    extends \*(AqPegex::Grammar\*(Aq;
\&
\&    use constant file => \*(Aq../mything\-grammar\-repo/mything.pgx\*(Aq;
\&    sub make_tree {
\&    }
.Ve
.PP
Simply use this command:
.PP
.Vb 1
\&    perl \-Ilib \-MMyThing::Grammar=compile
.Ve
.PP
and Pegex::Grammar will call Pegex::Compile to put your compiled grammar
inside your \f(CW\*(C`make_tree\*(C'\fR subroutine. It will actually write the text into your
module. This makes it trivial to update your grammar module after making
changes to the grammar file.
.PP
See Pegex::JSON for an example.
.SH "AUTHOR"
.IX Header "AUTHOR"
Ingy döt Net <ingy@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2010\-2020. Ingy döt Net.
.PP
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
.PP
See <http://www.perl.com/perl/misc/Artistic.html>