From 184b25ba3b0bc2590193e57a54dd028161bf2169 Mon Sep 17 00:00:00 2001 From: Mingun Date: Tue, 4 May 2021 21:00:58 +0500 Subject: [PATCH] Reserved: Improve error when reserved word used as a label name and add documentation for plugins API Before this commit error looks like (for input `start = break:'a'`) > Expected "!", "$", "&", "(", "*", "+", ".", "/", "/*", "//", ";", "?", character class, code block, comment, end of line, identifier, literal, or whitespace but ":" found. After this error looks like > Expected identifier but reserved word "break" found. --- CHANGELOG.md | 8 +++++ README.md | 38 ++++++++++++++++++++++- docs/documentation.html | 62 ++++++++++++++++++++++++++++++++++--- test/api/plugin-api.spec.js | 20 ++++++++++++ 4 files changed, 123 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1ac5de3c..32fa67f4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -63,6 +63,14 @@ Released: TBD especially if your plugin replaces both `generateBytecode` as `generateJs` passes. [@Mingun](https://github.com/peggyjs/peggy/pull/117) +- Add a new option `config.reservedWords: Iterable`, avalible for plugins in their + `use()` method. Using this option plugin can change a list of words that wouldn't be used + as label names. + + By default this new option contains an array with [reserved JavaScript words][reserved] + [@Mingun](https://github.com/peggyjs/peggy/pull/150) + +[reserved]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#reserved_keywords_as_of_ecmascript_2015 ### Bug fixes diff --git a/README.md b/README.md index 8dea5666..4f42de8d 100644 --- a/README.md +++ b/README.md @@ -165,7 +165,7 @@ object to `peg.generate`. The following options are supported: - `output` — if set to `"parser"`, the method will return generated parser object; if set to `"source"`, it will return parser source code as a string (default: `"parser"`) -- `plugins` — plugins to use +- `plugins` — plugins to use. See the [Plugins API](#plugins-api) section - `trace` — makes the parser trace its progress (default: `false`) - `grammarSource` — this object will be passed to any `location()` objects as the `source` property (default: `undefined`). This object will be used even if @@ -640,6 +640,42 @@ note: Step 3: call itself without input consumption - left recursion | ^^^^^ ``` +## Plugins API + +Plugin is an object with the `use(config, options)` method. That method will be +called for all plugins in the `options.plugins` array, supplied to the `generate()` +method. + +Plugin accepts the following parameters: +- `config` — object with the following properties: + - `parser` — `Parser` object, by default the `peg.parser` instance. That object + will be used to parse the grammar. Plugin can replace this object + - `passes` — mapping `{ [stage: string]: Pass[] }` that represents compilation + stages that would applied to the AST, returned by the `parser` object. That + mapping will contain at least the following keys: + - `check` — passes that check AST for correctness. They shouldn't change the AST + - `transform` — passes that performs various optimizations. They can change + the AST, add or remove nodes or their properties + - `generate` — passes used for actual code generating + + Plugin that implement a pass usually should push it to the end of one of that + arrays. Pass is a simple function with signature `pass(ast, options)`: + - `ast` — the AST created by the `config.parser.parse()` method + - `options` — compilation options passed to the `peg.compiler.compile()` method. + If parser generation is started because `generate()` function was called that + is also an options, passed to the `generate()` method + - `reservedWords` — [iterable] with a list of words that shouldn't be used as + label names. This list can be modified by plugins. That property is not required + to be sorted or not contain duplicates. + + Default list contains [JavaScript reserved words][reserved], and can be found + in the `peg.RESERVED_WORDS` property. +- `options` — build options passed to the `generate()` method. A good tone for + a plugin would look for its own options under a `` key. + +[iterable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol +[reserved]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#reserved_keywords_as_of_ecmascript_2015 + ## Compatibility Both the parser generator and generated parsers should run well in the following diff --git a/docs/documentation.html b/docs/documentation.html index eea1d973..e7d7d423 100644 --- a/docs/documentation.html +++ b/docs/documentation.html @@ -7,9 +7,9 @@ Documentation » Peggy – Parser Generator for JavaScript - - - + + +