- 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
PEG.js is a simple parser generator for JavaScript that produces fast parsers
with excellent error reporting. You can use it to process complex data or
computer languages and build transformers, interpreters, compilers and other
tools easily.
* [Useful Links](#useful-links)
* [Contribution](#contribution)
Features
--------
@ -75,6 +80,20 @@ version) or install it using Bower:
$ bower install pegjs
```
### Latest
To use the latest features, fixes and changes of PEG.js, directly install from the repository:
```console
$ npm install pegjs/pegjs#master
```
Alternatively, you can use the most recently packaged version of the PEG.js code hosted on GitHub:
```console
$ npm install pegjs-dev
```
Generating a Parser
-------------------
@ -307,12 +326,46 @@ takes the match result of the expression [0-9]+, which is an array of strings
containing digits, as its parameter. It joins the digits together to form a
number and converts it to a JavaScript `number` object.
### Case-insensitivity
Appending `i` right after either [a literal](#literalliteral) or a [a character set](#characters) makes the match
case-insensitive. The rules shown in the following example all produce the same result:
```pegjs
a1 = "a" / "b" / "c" / "A" / "B" / "C"
a2 = "a"i / "b"i / "c"i
a3 = [a-cA-C]
a4 = [a-c]i
```
### Backtracking
Unlike in regular expressions, there is no backtracking in PEG.js expressions.
For example, using the input "hi!":
```pegjs
// This will fail
HI = "hi" / "hi!"
// This will pass
HI = "hi!" / "hi"
// This will also pass
HI = w:"hi" !"!" { return w } / "hi!"
```
For more information on backtracking in PEG, [checkout this excellent answer on Stack Overflow](https://stackoverflow.com/a/24809596/1518408).
### Parsing Expression Types
There are several types of parsing expressions, some of them containing
subexpressions and thus forming a recursive structure:
* ["literal"](#literalliteral)
* [. (dot character)](#--dot-character-)
* [[characters]](#characters)
* [rule](#rule)
* [( expression )](#-expression-)
@ -335,7 +388,7 @@ Match exact literal string and return it. The string syntax is the same as in
JavaScript. Appending `i` right after the literal makes the match
case-insensitive.
#### .
#### . *(dot character)*
Match exactly one character and return it as a string.
@ -583,20 +636,40 @@ environments:
Development
-----------
PEG.js is currently maintained by [Futago-za Ryuu](https://github.com/futagoza). Since it's [inception](https://www.google.com/search?q=inception+meaning) in 2010, PEG.js was maintained by [David Majda](https://majda.cz/) ([@dmajda](http://twitter.com/dmajda)), until [May 2017](https://github.com/pegjs/pegjs/issues/503).
The [Bower package](https://github.com/pegjs/bower) is maintained by [Michel Krämer](http://www.michel-kraemer.com/) ([@michelkraemer](https://twitter.com/michelkraemer)).
PEG.js is currently maintained by [Futago-za Ryuu](https://github.com/futagoza). Since it's [inception](https://www.google.com/search?q=inception+meaning) in 2010, PEG.js was maintained by [David Majda](https://majda.cz/) ([@dmajda](http://twitter.com/dmajda)), until [May 2017](https://github.com/pegjs/pegjs/issues/503).
### Contribution
The [Bower package](https://github.com/pegjs/bower) is maintained by [Michel Krämer](http://www.michel-kraemer.com/) ([@michelkraemer](https://twitter.com/michelkraemer)).
You are welcome to contribute code using [GitHub pull requests](https://github.com/pegjs/pegjs/pulls). Unless your contribution is really trivial you should get in touch with me first (preferably by creating a new issue on the [issue tracker](https://github.com/pegjs/pegjs/issues)) - this can prevent wasted effort on both sides.
> Before submitting a pull request, please make sure you've checked out the [Contribution Guidelines](https://github.com/pegjs/pegjs/blob/master/CONTRIBUTING.md).
1. Create a fork of https://github.com/pegjs/pegjs
2. Clone your fork, and optionally create a new branch
3. Run the command `npm install` from the root of your clone
4. Add and commit your changes
5. Validate your changes:
- Lint the JavaScript changes (command line only, run `gulp lint` or `npm run lint`)
- Run tests to ensure nothing's broken: [see separate documentation](https://github.com/pegjs/pegjs/blob/master/test/README.md)
- Optionally, check benchmark results: [see separate documentation](https://github.com/pegjs/pegjs/blob/master/benchmark/README.md)
- Optionally, check commit impact (this is a bash script, run `tools/impact`)
6. If validation fails: reverse your commit, fix the problem and then add/commit again
7. Push the commits from your clone to the fork
8. From your fork, start a new pull request
You are welcome to contribute code. Unless your contribution is really trivial
you should get in touch with me first — this can prevent wasted effort on both
sides. You can send code both as a patch or a GitHub pull request.
It's also a good idea to check out the [gulpfile.js](https://github.com/pegjs/pegjs/blob/master/gulpfile.js) that defines
various tasks that are commented with a description of each task.
Note that PEG.js is still very much work in progress. There are no compatibility
guarantees until version 1.0.
To see the list of contributors check out the [repository's contributors page](https://github.com/pegjs/pegjs/graphs/contributors).
Futago-za Ryuu
7 years ago