22[ ![ npm version] ( https://img.shields.io/npm/v/phpeggy )] ( https://www.npmjs.com/package/phpeggy )
33[ ![ License] ( https://img.shields.io/badge/license-mit-blue )] ( https://opensource.org/licenses/MIT )
44
5+ - [ Migrating from phpegjs] ( #migrating-from-phpegjs )
6+ - [ Requirements] ( #requirements )
7+ - [ Installation] ( #installation )
8+ - [ Usage] ( #usage )
9+ - [ Generating a Parser] ( #generating-a-parser )
10+ - [ JS API] ( #js-api )
11+ - [ Command Line] ( #command-line )
12+ - [ Using the Parser] ( #using-the-parser )
13+ - [ Grammar Syntax and Semantics] ( #grammar-syntax-and-semantics )
14+ - [ Conversion Guide - Peggy action blocks to PHPeggy] ( #guide-for-converting-peggy-action-blocks-to-phpeggy )
15+
516# PHPeggy
617
718A PHP code generation plugin for
@@ -34,36 +45,38 @@ Follow these steps to upgrade:
3445
3546## Requirements
3647
37- * [ Peggy] ( https://peggyjs.org/ ) (known compatible with v3.0.0)
48+ * [ Peggy] ( https://peggyjs.org/ ) (known compatible with version 5)
49+ * PHP version >=8 for the created parser
50+ * ` mbstring ` extension enabled
3851
39- Installation
40- ------------
52+ ## Installation
4153
4254### Node.js
4355
44- Install Peggy with ` phpeggy ` plugin
56+ Install Peggy with PHPeggy plugin
4557
4658``` sh
47- $ npm install peggy@3 .0.0 phpeggy
59+ $ npm install peggy@^5 .0.0 phpeggy
4860```
4961
50- Usage
51- -----
62+ ## Usage
5263
5364### Generating a Parser
5465
55- In Node.js, require both the Peggy parser generator and the ` phpeggy ` plugin:
66+ #### JS API
67+
68+ In Node.js, require both the Peggy parser generator and the PHPeggy plugin:
5669
5770``` js
58- var peggy = require (" peggy"
59- var phpeggy = require (" phpeggy"
71+ const peggy = require (" peggy"
72+ const phpeggy = require (" phpeggy"
6073```
6174
62- To generate a PHP parser, pass both the ` phpeggy ` plugin and your grammar to
75+ To generate a PHP parser, pass both the PHPeggy plugin and your grammar to
6376` peggy.generate ` :
6477
6578``` js
66- var parser = peggy .generate (" start = ('a' / 'b')+"
79+ const parser = peggy .generate (" start = ('a' / 'b')+"
6780 plugins: [phpeggy]
6881});
6982```
@@ -88,7 +101,7 @@ Supported options of `peggy.generate`:
88101You can also pass options specific to the PHPeggy plugin as follows:
89102
90103``` js
91- var parser = peggy .generate (" start = ('a' / 'b')+"
104+ const parser = peggy .generate (" start = ('a' / 'b')+"
92105 plugins: [phpeggy],
93106 phpeggy: { /* phpeggy-specific options */
94107});
@@ -99,17 +112,36 @@ Here are the options available to pass this way:
99112 * ` parserNamespace ` - namespace of generated parser (default: ` PHPeggy ` ). If
100113 value is ` '' ` or ` null ` , no namespace will be used.
101114 * ` parserClassName ` - name of generated class for parser (default: ` Parser ` ).
102- * ` mbstringAllowed ` - whether to allow usage of PHP's ` mb_* ` functions which
103- depend on the ` mbstring ` extension being installed (default: ` true ` ). This
104- can be disabled for compatibility with a wider range of PHP configurations,
105- but this will also disable several features of Peggy (case-insensitive
106- string matching, case-insensitive character classes, and empty character
107- classes). Attempting to use these features with ` mbstringAllowed: false `
108- will cause ` passes.check ` to throw an error.
109115 * ` header ` - you can provide a custom header that will be added at the top of the parser, e.g. ` /* My custom header */ ` .
110116
111- Using the Parser
112- ----------------
117+ #### Command Line
118+
119+ To generate a parser from your grammar, use the peggy command:
120+
121+ ``` bash
122+ npx peggy --plugin /path/to/phpeggy/src/phpeggy.js arithmetics.pegjs
123+ ```
124+
125+ The following options might be of interest in the context of PHPeggy:
126+
127+ - ` --allowed-start-rules <rules> `
128+ - ` --cache `
129+ - ` --extra-options <options> `
130+ - ` -c, --extra-options-file <file> `
131+ - ` -o, --output <file> `
132+ - ` -S, --start-rule <rule> `
133+
134+ ` --format ` is irrelevant as PHPeggy will only provide PHP source code.
135+
136+ Here is a more complex example:
137+
138+ ``` bash
139+ npx peggy -o arithmeticsParser.php --plugin /path/to/phpeggy/src/phpeggy.js arithmetics.pegjs --cache --extra-option ' { "phpeggy" : { "parserNamespace" : "MyNameSpace", "parserClassName" : "ArithmeticsParser", "header" : "/* My custom header */" } }'
140+ ```
141+
142+ A more detailed description of the different options can be found in the [ peggy documentation] ( https://peggyjs.org/documentation.html#generating-a-parser-command-line ) .
143+
144+ ## Using the Parser
113145
1141461 ) Save parser generated by ` peggy.generate ` to a file
115147
@@ -145,6 +177,7 @@ catch (PHPeggy\SyntaxError $e) {
145177
146178Which will look similar to:
147179
180+ <!-- eslint-disable-next-line markdown/fenced-code-language -->
148181```
149182SyntaxError: Expected "a" but "b" found.
150183 --> Input string:1:1
@@ -160,21 +193,21 @@ maintain compatibility with PCRE versions that are missing Unicode support
160193array (one array element per UTF-8 character) and pass this array into
161194` $parser->parse() ` instead of the string input.
162195
163- Grammar Syntax and Semantics
164- ----------------------------
196+ ## Grammar Syntax and Semantics
165197
166198See [ documentation of Peggy] ( https://peggyjs.org/documentation.html ) with following differences:
167199
168200* action and predicate blocks should be written in PHP.
169201* the _ per-parse initializer_ code block is used to provide additional methods, properties and constants to the Parser class. A special method ` function initialize() ` can be provided and resembles the Peggy per-parse initializer i.e. this method is called before the generated parser starts parsing (see [ examples/fizzbuzz.pegjs] ( examples/fizzbuzz.pegjs ) ). All methods have access to the input (` $this->input ` ) and the options (` $this->options ` ).
170202* the _ global initializer_ code block can be used to add use statements, classes, functions, constants, ...
203+ * [ Importing External Rules] ( https://peggyjs.org/documentation.html#importing-external-rules ) works only from the Command Line.
171204
172205Original Peggy rule:
173206
174207``` js
175208media_list = head: medium tail: (" ," S * medium)* {
176- var result = [head];
177- for (var i = 0 ; i < tail .length ; i++ ) {
209+ let result = [head];
210+ for (let i = 0 ; i < tail .length ; i++ ) {
178211 result .push (tail[i][2 ]);
179212 }
180213 return result;
@@ -206,8 +239,8 @@ media_list = head:medium tail:("," S* medium)* {
206239 return $result;
207240 ?> **/
208241
209- var result = [head];
210- for (var i = 0 ; i < tail .length ; i++ ) {
242+ let result = [head];
243+ for (let i = 0 ; i < tail .length ; i++ ) {
211244 result .push (tail[i][2 ]);
212245 }
213246 return result;
@@ -221,8 +254,7 @@ You can also use the following utility functions in PHP action blocks:
221254- ` ord_unicode($code) ` - return the UTF-8 code for a character (analogue of
222255 JavaScript's ` String.prototype.charCodeAt(0) ` function).
223256
224- Guide for converting Peggy action blocks to PHPeggy
225- ---------------------------------------------------
257+ ## Guide for converting Peggy action blocks to PHPeggy
226258
227259| Javascript code | PHP analogue |
228260| --------------------------------- | ----------------------------------------- |
0 commit comments