In Node.js, require the PEG.js parser generator module:
```javascript
```js
var peg = require("pegjs");
```
@ -156,56 +156,103 @@ In browser, include the PEG.js library in your web page or application using the
`<script>` tag. If PEG.js detects an AMD loader, it will define itself as a
module, otherwise the API will be available in the `peg` global object.
To generate a parser, call the `peg.generate` method and pass your grammar as a
parameter:
After this there are 3 methods that you will mainly use:
```javascript
var parser = peg.generate("start = ('a' / 'b')+");
```js
var grammar = "start = ('a' / 'b')+";
var ast, parser;
ast = peg.parser.parse(grammar);
parser = peg.compiler.compile(ast);
parser = peg.generate(grammar);
```
The method will return generated parser object or its source code as a string
(depending on the value of the `output` option — see below). It will throw an
exception if the grammar is invalid. The exception will contain `message`
property with more details about the error.
The most common is `peg.generate`, which is the API alternative to the
[PEG.js CLI shown above](#command-line). More about each method is
explained below, along with their respective options.
You can tweak the generated parser by passing a second parameter with an options
object to `peg.generate`. The following options are supported:
#### peg.parser.parse(input[, options])
* `allowedStartRules` — rules the parser will be allowed to start parsing from (default: the first rule in the grammar)
* `cache` — if `true`, makes the parser cache results, avoiding exponential parsing time in pathological cases but making the parser slower (default: `false`)
* `dependencies` — parser dependencies, the value is an object which maps variables used to access the dependencies to module IDs used to load them;<br>
valid only when `format` is set to `"amd"`, `"commonjs"`, `"es"`, or `"umd"` (default: `{}`)
* `exportVar` — name of an optional global variable into which the parser object is assigned to when no module loader is detected;
valid only when `format` is set to `"globals"` or `"umd"`
* `format` — format of the generated parser (`"amd"`, `"bare"`, `"commonjs"`, `"es"`, `"globals"`, or `"umd"`);
valid only when `output` is set to `"source"` (default: `"bare"`)
* `header` — this option is only handled if it's an array or a string:
* `[ string1, string2, ... ]` will add each element (all expected to be strings) as a separate line comment
* `string` will simply append the string (e.g. `"/* eslint-disable */"`) after the `Generated by ...` comment
* `optimize`— selects between optimizing the generated parser for parsing speed (`"speed"`) or code size (`"size"`) (default: `"speed"`)
* `output` — if set to `"parser"` (default), the method will return generated parser object;
if set to `"source"`, it will return parser source code as a string
* `plugins` — plugins to use
* `trace` — makes the parser trace its progress (default: `false`)
Also you can supply boolean option `extractComments` (default: `false`).
When set to `true`, parser will be collect all comments in the grammar to the object
in the `comments` property in the `grammar` AST node. This key contains mapping from
offset position of start location of the comment (i.e. `//` or `/*`) to comment object
itself. Comment object has following structure:
You can simply parse a grammar and get it's AST by using the parser:
```js
{
text: 'all text between /* or */, or // and end of line',
multiline: true|false,
location: location()
}
```
```js
var ast = peg.parser.parse("start = ('a' / 'b')+");
```
When set to `false`, `comments` will be set to `null`.
The following option's are used by the PEG.js parser:
* `extractComments` - If `true`, the parser will collect all comments in the grammar (default: `false`).
* `reservedWords` - An array of words that the parser wont allow as labels for rules (default: [ES5](http://es5.github.io/#x7.6.1)).
When `extractComments` is set to `true`, the parser will collect all comments
in the grammar and return them on the `comments` property (as an array) in the
`grammar` AST node (the AST directly returned by the parser). Each comment
object within the array has the following structure:
```js
{
text: 'all text between /* or */, or // and end of line',
multiline: true|false,
location: location()
}
```
When set to `false`, the `comments` property will be set to `null`.
For more information about `location()`, see the helper's description in
This option not impact to the generated parser but only to grammar AST, which
can be used by plugins.
#### peg.compiler.compile(ast, passes[, options])
This method will take a parsed grammar (the PEG.js AST), set default options,
execute each pass (passing the ast to each one), then return the result, which
depends on the value of the `output` option.
```js
var ast = peg.parser.parse("start = ('a' / 'b')+");
var parser = peg.compiler.compile(ast);
```
You can tweak the generated parser by passing a third parameter with an options
object. The following options are supported:
Option | default value | description
--- | --- | ---
allowedStartRules | first rule in the grammar | rules the generated parser is allowed to start parsing from
cache | `false` | makes the generated parser cache results, avoiding exponential parsing time in pathological cases but making the parser slower
dependencies | `{}` | parser dependencies, the value is an object which maps variables used to access the dependencies to module IDs used to load them; valid only when `format` is set to `"amd"`, `"commonjs"`, `"es"`, or `"umd"`
exportVar | `null` | name of an optional global variable into which the generated parser object is assigned to when no module loader is detected; valid only when `format` is set to `"globals"` or `"umd"`
format | `"bare"` | format of the generated parser (`"amd"`, `"bare"`, `"commonjs"`, `"es"`, `"globals"`, or `"umd"`); valid only when `output` is set to `"source"`
header | `null` | this option is only handled if it's an array or a string:
optimize | `"speed"` | selects between optimizing the generated parser for parsing speed (`"speed"`) or code size (`"size"`)
output | `"parser"` | if set to `"parser"`, the method will return generated parser object; if set to `"source"`, it will return generated parser source code as a string
trace | `false` | makes the generated parser trace its progress
The `header` options behavior will change depending on the option type:
* `[ string1, string2, ... ]` will add each element (all expected to be strings) as a separate line comment
* `string` will simply append the string (e.g. `"/* eslint-disable */"`) after the `Generated by ...` comment
#### peg.generate(grammar[, options])
Will generate a parser from the given grammar (the _input_ passed to `peg.parser.parse`):
```js
var parser = peg.generate("start = ('a' / 'b')+");
```
This method will return a generated parser object or its source code as a string
(depending on the value of the `output` option - see above). It will throw an
exception if the grammar is invalid. The exception will contain the usual `message`
property with more details about the error, along with a `location` property to
track the location of the error. You can easily tell if the exception was thrown
by PEG.js because it will always have the `name` property set to `GrammarError`.
You can tweak the generated parser by passing a second parameter with an options
object to `peg.generate`. The following options are supported:
* All options that you pass to `peg.compiler.compile`
* `parser` - an optional object with option's passed to the PEG.js parser (`peg.parser.parse`)
* `plugins` - plugins to use _(executed by `peg.generate`)_
Using the Parser
----------------
@ -216,7 +263,7 @@ value depends on the grammar used to generate the parser) or throw an exception
if the input is invalid. The exception will contain `location`, `expected`,
`found`, and `message` properties with more details about the error.
Futago-za Ryuu
6 years ago