Merge pull request #163 from Mingun/source-map

Source map support

.github/workflows/node.js.yml

@@ -26,6 +26,7 @@ jobs:
       - name: Install dependencies
         run: npm install
       - name: Check coding standards
+        if: matrix.node-version == '16.x' && matrix.os == 'ubuntu-latest'
         run: npm run lint
       - name: Static analysis - check types
         run: npm run ts

CHANGELOG.md

@@ -8,6 +8,11 @@ This file documents all notable changes to Peggy.
 
 Released: TBD
 
+### Major Changes
+
+- Add support for generating source maps.
+  [@Mingun](https://github.com/peggyjs/peggy/pull/163)
+
 ### Minor Changes
 
 - New CLI [@hildjj](https://github.com/peggyjs/peggy/pull/167)

README.md

@@ -31,6 +31,7 @@ Follow these steps to upgrade:
   — more powerful than traditional LL(_k_) and LR(_k_) parsers
 - Usable [from your browser](https://peggyjs.org/online), from the command line,
   or via JavaScript API
+- [Source map](https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Use_a_source_map) support
 
 ## Getting Started
 
@@ -120,13 +121,16 @@ You can tweak the generated parser with several options:
   name with extension changed to `.js`, or stdout if no input file is given.
 - `--plugin <module>` — makes Peggy use a specified plugin (can be specified
   multiple times)
-- `-t`, `--test <text>` - Test the parser with the given text, outputting the
-  result of running the parser against this input
-- `-T`, `--test-file <filename>` - Test the parser with the contents of the
-  given file, outputting the result of running the parser against this input
+- `-t`, `--test <text>` — Test the parser with the given text, outputting the
+  result of running the parser against this input.
+  If the input to be tested is not parsed, the CLI will exit with code 2
+- `-T`, `--test-file <filename>` — Test the parser with the contents of the
+  given file, outputting the result of running the parser against this input.
+  If the input to be tested is not parsed, the CLI will exit with code 2
+- `--source-map` — generate a source map file with an optionally specified name
 - `--trace` — makes the parser trace its progress
-- `-v`, `--version` - output the version number
-- `-h`, `--help` - display help for command
+- `-v`, `--version` — output the version number
+- `-h`, `--help` — display help for command
 
 If you specify options using `-c <file>` or `--extra-options-file <file>`, you
 will need to ensure you are using the correct types.  In particular, you may
@@ -150,6 +154,50 @@ module.exports = {
 };
 ```
 
+You can test generated parser immediately if you specify the `-t/--test` or `-T/--test-file`
+option. This option conflicts with the option `-m/--source-map` unless `-o/--output` is
+also specified.
+
+The CLI will exit with the code:
+- `0` if all was success
+- `1` if you supply incorrect or conflicting parameters
+- `2` if all parameters is correct, you specify the `-t/--test` or `-T/--test-file` option
+  and specified input does not parsed with the specified grammar
+
+Examples:
+
+```console
+# - write test results to stdout (42)
+# - exit with the code 0
+echo "foo = '1' { return 42 }" | peggy --test 1
+
+# - write a parser error to stdout (Expected "1" but "2" found)
+# - exit with the code 2
+echo "foo = '1' { return 42 }" | peggy --test 2
+
+# - write an error to stdout (Generation of the source map is useless if you don't
+#   store a generated parser code, perhaps you forgot to add an `-o/--output` option?)
+# - exit with the code 1
+echo "foo = '1' { return 42 }" | peggy --source-map --test 1
+
+# - write an error to stdout (Generation of the source map is useless if you don't
+#   store a generated parser code, perhaps you forgot to add an `-o/--output` option?)
+# - exit with the code 1
+echo "foo = '1' { return 42 }" | peggy --source-map --test 2
+
+# - write an output to `parser.js`,
+# - write a source map to `parser.js.map`
+# - write test results to stdout (42)
+# - exit with the code 0
+echo "foo = '1' { return 42 }" | peggy --output parser.js --source-map --test 1
+
+# - write an output to `parser.js`,
+# - write a source map to `parser.js.map`
+# - write a parser error to stdout (Expected "1" but "2" found)
+# - exit with the code 2
+echo "foo = '1' { return 42 }" | peggy --output parser.js --source-map --test 2
+```
+
 ### JavaScript API
 
 In Node.js, require the Peggy parser generator module:
@@ -207,11 +255,20 @@ object to `peg.generate`. The following options are supported:
   `options.grammarSource` is redefined in the grammar. It is useful to attach
   the file information to the errors, for example
 - `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
+  object; if set to `"source"`, it will return parser source code as a string.
+  If set to `"source-and-map"`, it will return a [`SourceNode`] object; you can
+  get source code by calling `toString()` method or source code and mapping by
+  calling `toStringWithSourceMap()` method, see the [`SourceNode`] documentation
   (default: `"parser"`)
+
+  > **Note**: because of bug [source-map/444] you should also set `grammarSource` to
+  > a not-empty string if you set this value to `"source-and-map"`
 - `plugins` — plugins to use. See the [Plugins API](#plugins-api) section
 - `trace` — makes the parser trace its progress (default: `false`)
 
+[`SourceNode`]: https://github.com/mozilla/source-map#sourcenode
+[source-map/444]: https://github.com/mozilla/source-map/issues/444
+
 ## Using the Parser
 
 To use the generated parser, call its `parse` method and pass an input string