The README.md file in the root of the repository had become too large, and as a result the file became hard to maintain.
This commit extracts all the documentation and moves it to separate but managable files within the docs directory, a new folder also located in the root of the repository.
All comments stored in the `comments` property of the `grammar` node.
Comments extracted only if the `extractComments` options set to `true` when you generate parser.
This property is object with mapping start offset of comment to comment object, that looks like:
```js
{
text: 'text in the comment, just after // or /* and before */',
multiline: true|false,// true for /**/ comments, false for // comments
location: location()
}
```
This commit adds support for '.js' files to be passed to the '-c', '--config' or '--extra-options-file' options on the CLI, allowing the developer to do some extra work before the parser is generated (if they wish), or dynamically set options based on the enviroment.
* Clarify execution environment of actions and predicates
* Makes a new section for describing the common execution environment
* Add the new section to TOC
* Clarify start/end for predicates
* Clarify the scope of labels
- Split into 3 files: "peg.js", "options.js" and "usage.txt"
- Rewrote arguments parser and helpers to be more precise
- Any arguments after "--" will be passed to "options['--']" now
- Added negation options: "--no-cache" and "--no-trace"
- Added "bare" to accepted module formats
- Added 2 aliases for "--extra-options-file": "-c" and "--config"
- Added short options: "-a", "-f" and "-p"
- Reformatted help text in "usage.txt"
- Updated documentation related to command line options and normal options
- Changed "bin" field in "package.json" from "bin/pegjs" to "bin/peg"
- Added documentation note about command line options that are repeated
- Updated gulpfile.js, replacing "bin/pegjs" with "bin/*.js"
See #429, which was what I intended to fix/solve, but instead pushed back and did this instead.
- Updated Badges
- Moved the introduction back to the top
- Added a title for the TOC list
- Added "Latest" sub-section (closes#521)
- Added "Case-insensitivity" sub-section (see #518)
- Added "Backtracking" sub-section (closes#438)
- Fixed link for . (dot character)
- Added a title for the links in the development section
- Added "Contribution" sub-section (closses #457)
- Updated the TOC list
Parsers generated in this format use module.exports, so they are not
strictly CommonJS, but this is a common extension and the original name
would be confusing once Node.js implements ES2015 modules.
The "parser" variable allowed access to the parser object. Among other
things, this made it possible to invoke the parser recursively using
"parser.parse".
One problem with the "parser" variable is that it bakes in the idea that
the parser is an *object*, not a *module*. While this is true now, it
won't necessarily be in the future, when parsers may be exported as ES6
modules. Also, people tend to use parsers as modules even today, e.g.
like this:
var parse = require("parser").parse;
var result = parse(...);
Such usage broke the "parser" variable (as it was implemented).
For this reasons I decided to remove the "parser" variable. If someone
needs to do tricks like recursive invocation of the parser, he/she must
pass the parser or the "parse" function itself using options.
Related to #433.
This is more traditional compiler interface. Its main advantage against
specifying the output file as a second argument (which is what bin/pegjs
used until now) is that input and output files can't be mixed up.
Part of #370.
In most places, we talk about "generating a parser", not "building a
parser", which the function name should reflect. Also, mentioning a
parser in the name is not necessary as in case of a parser generator
it's pretty clear what is generated.
So far, PEG.js was exported in a "PEG" global variable when no module
loader was detected. The same variable name was also conventionally used
when requiring it in Node.js or otherwise referring to it. This was
reflected in various places in the code, documentation, examples, etc.
This commit changes the variable name to "peg" and fixes all relevant
occurrences. The main reason for the change is that in Node.js, modules
are generally referred to by lower-case variable names, so "PEG" was
sticking out when used in Node.js projects.
Introduce two ways of specifying parser dependencies: the "dependencies"
option of PEG.buildParser and the -d/--dependency CLI option. Specified
dependencies are translated into AMD dependencies and Node.js's
"require" calls when generating an UMD parser.
Part of work on #362.
