1Pegex::Compiler(3)    User Contributed Perl Documentation   Pegex::Compiler(3)
2
3
4

NAME

6       Pegex::Compiler - Pegex Compiler
7

SYNOPSIS

9           use Pegex::Compiler;
10           my $grammar_text = '... grammar text ...';
11           my $pegex_compiler = Pegex::Compiler->new();
12           my $grammar_tree = $pegex_compiler->compile($grammar_text)->tree;
13
14       or:
15
16           perl -Ilib -MYourGrammarModule=compile
17

DESCRIPTION

19       The Pegex::Compiler transforms a Pegex grammar string (or file) into a
20       compiled form. The compiled form is known as a grammar tree, which is
21       simply a nested data structure.
22
23       The grammar tree can be serialized to YAML, JSON, Perl, or any other
24       programming language. This makes it extremely portable. Pegex::Grammar
25       has methods for serializing to all these forms.
26
27       NOTE: Unless you are developing Pegex based modules, you can safely
28       ignore
29             this module. Even if you are you probably won't use it directly.
30       See [In
31             Place Compilation] below.
32

METHODS

34       The following public methods are available:
35
36       "$compiler = Pegex::Compiler->new();"
37           Return a new Pegex::Compiler object.
38
39       "$grammar_tree = $compiler->compile($grammar_input);"
40           Compile a grammar text into a grammar tree that can be used by a
41           Pegex::Parser. This method is calls the "parse" and "combinate"
42           methods and returns the resulting tree.
43
44           Input can be a string, a string ref, a file path, a file handle, or
45           a Pegex::Input object. Return $self so you can chain it to other
46           methods.
47
48       "$compiler->parse($grammar_text)"
49           The first step of a "compile" is "parse". This applies the Pegex
50           language grammar to your grammar text and produces an unoptimized
51           tree.
52
53           This method returns $self so you can chain it to other methods.
54
55       "$compiler->combinate()"
56           Before a Pegex grammar tree can be used to parse things, it needs
57           to be combinated. This process turns the regex tokens into real
58           regexes. It also combines some rules together and eliminates rules
59           that are not needed or have been combinated. The result is a Pegex
60           grammar tree that can be used by a Pegex::Parser.
61
62           NOTE: While the parse phase of a compile is always the same for
63           various
64                 programming languages, the combinate phase takes into
65           consideration and
66                 special needs of the target language. Pegex::Compiler only
67           combinates
68                 for Perl, although this is often sufficient in similar
69           languages like
70                 Ruby or Python (PCRE based regexes). Languages like Java
71           probably need
72                 to use their own combinators.
73
74       "$compiler->tree()"
75           Return the current state of the grammar tree (as a hash ref).
76
77       "$compiler->to_yaml()"
78           Serialize the current grammar tree to YAML.
79
80       "$compiler->to_json()"
81           Serialize the current grammar tree to JSON.
82
83       "$compiler->to_perl()"
84           Serialize the current grammar tree to Perl.
85

IN PLACE COMPILATION

87       When you write a Pegex based module you will want to precompile your
88       grammar into Perl so that it has no load penalty. Pegex::Grammar
89       provides a special mechanism for this. Say you have a class like this:
90
91           package MyThing::Grammar;
92           use Pegex::Base;
93           extends 'Pegex::Grammar';
94
95           use constant file => '../mything-grammar-repo/mything.pgx';
96           sub make_tree {
97           }
98
99       Simply use this command:
100
101           perl -Ilib -MMyThing::Grammar=compile
102
103       and Pegex::Grammar will call Pegex::Compile to put your compiled
104       grammar inside your "make_tree" subroutine. It will actually write the
105       text into your module. This makes it trivial to update your grammar
106       module after making changes to the grammar file.
107
108       See Pegex::JSON for an example.
109

AUTHOR

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

114       Copyright 2010-2020. Ingy döt Net.
115
116       This program is free software; you can redistribute it and/or modify it
117       under the same terms as Perl itself.
118
119       See <http://www.perl.com/perl/misc/Artistic.html>
120
121
122
123perl v5.36.0                      2022-07-22                Pegex::Compiler(3)
Impressum