From 11bc94f4c35fe0b2cefe78cc0b31101dad496681 Mon Sep 17 00:00:00 2001
From: Futago-za Ryuu <futagoza.ryuu@gmail.com>
Date: Mon, 29 Jan 2018 02:08:12 +0000
Subject: [PATCH] Updated docs for JavaScript API [ci skip]

This includes detials about the 3 main methods a developer will use along with their respective options.

Closes #553
---
 README.md | 137 ++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 92 insertions(+), 45 deletions(-)

diff --git a/README.md b/README.md
index 7226154..e6d7000 100644
--- a/README.md
+++ b/README.md
@@ -148,7 +148,7 @@ before or it's counter part:
 
 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
+[Action Execution Environment](#action-execution-environment).
 
-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.
 
-```javascript
+```js
 parser.parse("abba"); // returns ["a", "b", "b", "a"]
 
 parser.parse("abcd"); // throws an exception
@@ -555,7 +602,7 @@ available to them.
 
 * `location()` returns an object like this:
 
-  ```javascript
+  ```js
   {
     start: { offset: 23, line: 5, column: 6 },
     end: { offset: 25, line: 5, column: 8 }