Clarify parts of the documentation

master
Futago-za Ryuu 6 years ago
parent 213c70ced4
commit fe2237476f

@ -2,4 +2,9 @@
The [online editor](https://pegjs.org/online) is the easiest way to generate a parser. Just enter your grammar, try parsing some input, and download the generated parser code. The [online editor](https://pegjs.org/online) is the easiest way to generate a parser. Just enter your grammar, try parsing some input, and download the generated parser code.
If you want a more flexible way to generate a parser, check out the [installation guide](./installation.md). If you want a more flexible way to generate a parser, check out the following:
- [Installing PEG.js](./installation.md)
- [Generating a Parser](./generating-a-parser.md)
- [JavaScript API](./javascript-api.md)
- [Plugins](./plugins.md)

@ -16,13 +16,18 @@ After this there are 3 methods and 1 class that you will mainly use:
```js ```js
var grammar = "start = ('a' / 'b')+"; var grammar = "start = ('a' / 'b')+";
var passes = [ /* check, transform and generate passes */ ];
var parser, session, ast;
ast = peg.parser.parse(grammar); // Parse grammar, generating AST
session = new peg.Session( { grammar, passes } ); var ast = peg.parser.parse(grammar);
parser = peg.compiler.compile(ast, session);
parser = peg.generate(grammar); // Create a new compiler session
var session = new peg.Session( { warn: customLogger } );
// Generate parser from PEG.js AST using an exisiting session
var parserA = peg.compiler.compile(ast, session);
// Generate parser from the grammar source using a new session
var parserB = peg.generate(grammar);
``` ```
The most common method you will use is `peg.generate()`, which is the API alternative to the [PEG.js CLI](./generating-a-parser.md). More about each method is explained below, along with their respective options. The most common method you will use is `peg.generate()`, which is the API alternative to the [PEG.js CLI](./generating-a-parser.md). More about each method is explained below, along with their respective options.
@ -66,7 +71,7 @@ The following option's are used by the Session API, but are currently all option
* `parser` - A pre-generated PEG.js grammar parser that should return an instance of the PEG.js AST's Grammar class. Can be replaced to add additional syntax features, or allow an alternative syntax for the grammar. * `parser` - A pre-generated PEG.js grammar parser that should return an instance of the PEG.js AST's Grammar class. Can be replaced to add additional syntax features, or allow an alternative syntax for the grammar.
* `passes` - An object with each property being an array of methods that will check or alter the AST passed to them. * `passes` - An object with each property being an array of methods that will check or alter the AST passed to them.
* `visitor` - An object that should contain the `ASTVisitor` class for the PEG.js AST, as well as the `build()` helper. * `visitor` - An object that should contain the `ASTVisitor` class for the PEG.js AST, as well as the `build()` helper.
* `vm` - An object that should contain `runInContext()`, a wrapper for `eval` based on Node's `vm.runInContext()` method. * `vm` - An object that should contain `evalModule()`, a wrapper for `eval` based on Node's `vm.runInContext()` method.
* `warn` - A method called only when PEG.js encounters an error that doesn't stop the parser from being generated. * `warn` - A method called only when PEG.js encounters an error that doesn't stop the parser from being generated.
* `error` - A method that will be called when PEG.js encounters an error that will stop the parser from being generated. * `error` - A method that will be called when PEG.js encounters an error that will stop the parser from being generated.
@ -84,7 +89,7 @@ This method takes a parsed grammar (the PEG.js AST), sets default options, execu
var grammar = "start = ('a' / 'b')+"; var grammar = "start = ('a' / 'b')+";
var ast = peg.parser.parse(grammar); var ast = peg.parser.parse(grammar);
var passes = peg.util.convertPasses( peg.compiler.passes ); var passes = peg.util.convertPasses( peg.compiler.passes );
var session = new peg.Session( { grammar, passes } ); var session = new peg.Session( { passes } );
var parser = peg.compiler.compile(ast, session); var parser = peg.compiler.compile(ast, session);
``` ```
@ -94,19 +99,24 @@ Option | default value | description
--- | --- | --- --- | --- | ---
allowedStartRules | first rule | rules the generated parser is allowed to start parsing from allowedStartRules | first rule | 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 cache | `false` | makes the generated parser cache results, avoiding exponential parsing time in pathological cases but making the parser slower
context | `{}` | contains a map of variables used by `peg.util.vm.runInContext()` when the `output` option is set to `"parser"` context | `{}` | contains a map of variables used by `peg.util.vm.evalModule()` when the `output` option is set to `"parser"`
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"` dependencies<sub>1</sub> | `{}` | parser dependencies, the value is an object which maps variables used to access the dependencies to module IDs used to load them
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"` exportVar<sub>2</sub> | `null` | name of an optional global variable into which the generated parser object is assigned to when no module loader is detected
features | `null` | map of optional features that are set to `true` by default: `"text"`, `"offset"`, `"range"`, `"location"`, `"expected"`, `"error"`, `"filename"` and `"DefaultTracer"` features | `null` | map of optional features that are set to `true` by default: `"text"`, `"offset"`, `"range"`, `"location"`, `"expected"`, `"error"`, `"filename"` and `"DefaultTracer"`
format | `"bare"` | format of the generated parser (`"amd"`, `"bare"`, `"commonjs"`, `"es"`, `"globals"`, or `"umd"`); valid only when `output` is set to `"source"` format<sub>3</sub> | `"bare"` | format of the generated parser (`"amd"`, `"bare"`, `"commonjs"`, `"es"`, `"globals"`, or `"umd"`)
header | `null` | adds additional comments or content after the `Generated by ...` comment; this option is only handled if it's an array or a string: header | `null` | adds additional comments or content after the `Generated by ...` comment; 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"`) 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 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 trace | `false` | makes the generated parser trace its progress
1. The `dependencies` option is only used when `format` is set to `"amd"`, `"commonjs"`, `"es"`, or `"umd"`
2. The `exportVar` option is only used when `format` is set to `"globals"` or `"umd"`
3. The `format` option is is always set to `"umd"` when `output` is set to `"parser"`
The `header` options behavior will change depending on the option type: 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 * `[ 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]) #### peg.generate(grammar[, options])

Loading…
Cancel
Save