lalrpop/README.md

# LALRPOP

[![Join the chat at https://gitter.im/lalrpop/Lobby](https://badges.gitter.im/lalrpop/Lobby.svg)](https://gitter.im/lalrpop/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

[![Build status](https://travis-ci.org/lalrpop/lalrpop.svg?branch=master)](https://travis-ci.org/lalrpop/lalrpop)

LALRPOP is a Rust parser generator framework with *usability* as its
primary goal. You should be able to write compact, DRY, readable
grammars. To this end, LALRPOP offers a number of nifty features:

0. Nice error messages in case parser constructor fails.
1. Macros that let you extract common parts of your grammar. This
   means you can go beyond simple repetition like `Id*` and define
   things like `Comma<Id>` for a comma-separated list of identifiers.
2. Macros can also create subsets, so that you easily do something
   like `Expr<"all">` to represent the full range of expressions, but
   `Expr<"if">` to represent the subset of expressions that can appear
   in an `if` expression.
3. Builtin support for operators like `*` and `?`.
4. Compact defaults so that you can avoid writing action code much of the
   time.
5. Type inference so you can often omit the types of nonterminals.

Despite its name, LALRPOP in fact uses LR(1) by default (though you
can opt for LALR(1)), and really I hope to eventually move to
something general that can handle all CFGs (like GLL, GLR, LL(\*),
etc).

### Documentation

[The LALRPOP book] covers all things LALRPOP -- or at least it intends
to! Here are some tips:

- The [tutorial] covers the basics of setting up a LALRPOP parser.
- For the impatient, you may prefer the [quick start guide] section, which describes
  how to add LALRPOP to your `Cargo.toml`.
- The [advanced setup] chapter shows how to configure other aspects of LALRPOP's
  preprocessing.
- If you have any questions join our [gitter lobby].

### Example Uses

- [LALRPOP] is itself implemented in LALRPOP.
- [Gluon] is a statically typed functional programming language.
- [Gleam](https://github.com/gleam-lang/gleam/blob/master/src/grammar.lalrpop) is a statically typed functional programming language for the Erlang VM.
- [RustPython] is Python 3.5+ rewritten in Rust
- [Solang] is Ethereum Solidity rewritten in Rust

[The LALRPOP book]: http://lalrpop.github.io/lalrpop/
[quick start guide]: http://lalrpop.github.io/lalrpop/quick_start_guide.html
[advanced setup]: http://lalrpop.github.io/lalrpop/advanced_setup.html
[tutorial]: http://lalrpop.github.io/lalrpop/tutorial/index.html
[LALRPOP]: https://github.com/lalrpop/lalrpop/blob/8034f3dacc4b20581bd10c5cb0b4f9faae778bb5/lalrpop/src/parser/lrgrammar.lalrpop
[Gluon]: https://github.com/gluon-lang/gluon/blob/d7ce3e81c1fcfdf25cdd6d1abde2b6e376b4bf50/parser/src/grammar.lalrpop
[RustPython]: https://github.com/RustPython/RustPython/blob/master/parser/src/python.lalrpop
[Solang]: https://github.com/hyperledger-labs/solang/blob/master/src/parser/solidity.lalrpop
[gitter lobby]: https://gitter.im/lalrpop/Lobby

### Contributing

You **really** should read `CONTRIBUTING.md` if you intend to change LALRPOP's own grammar.
update tutorial and readme 2015-09-11 06:50:39 -04:00			`# LALRPOP`
Update README 2015-06-24 06:03:57 -07:00
Add gitter badge 2016-11-08 06:33:40 -05:00			`[![Join the chat at https://gitter.im/lalrpop/Lobby](https://badges.gitter.im/lalrpop/Lobby.svg)](https://gitter.im/lalrpop/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)`

docs: Fix the link to travis Before it would link to the image itself 2018-03-17 09:34:52 +01:00			`[![Build status](https://travis-ci.org/lalrpop/lalrpop.svg?branch=master)](https://travis-ci.org/lalrpop/lalrpop)`
add build status image 2015-09-16 06:03:36 -04:00
update tutorial and readme 2015-09-11 06:50:39 -04:00			`LALRPOP is a Rust parser generator framework with usability as its`
			`primary goal. You should be able to write compact, DRY, readable`
			`grammars. To this end, LALRPOP offers a number of nifty features:`
Move lalrpop code into a subdirectory 2015-06-24 05:53:24 -07:00
Document the contributing process 2019-07-14 20:56:41 +03:00			`0. Nice error messages in case parser constructor fails.`
Move lalrpop code into a subdirectory 2015-06-24 05:53:24 -07:00			`1. Macros that let you extract common parts of your grammar. This`
			means you can go beyond simple repetition like `Id*` and define
			things like `Comma<Id>` for a comma-separated list of identifiers.
			`2. Macros can also create subsets, so that you easily do something`
			like `Expr<"all">` to represent the full range of expressions, but
			`Expr<"if">` to represent the subset of expressions that can appear
			in an `if` expression.
update tutorial and readme 2015-09-11 06:50:39 -04:00			3. Builtin support for operators like `*` and `?`.
			`4. Compact defaults so that you can avoid writing action code much of the`
Move lalrpop code into a subdirectory 2015-06-24 05:53:24 -07:00			`time.`
Document the contributing process 2019-07-14 20:56:41 +03:00			`5. Type inference so you can often omit the types of nonterminals.`
update tutorial and readme 2015-09-11 06:50:39 -04:00
			`Despite its name, LALRPOP in fact uses LR(1) by default (though you`
			`can opt for LALR(1)), and really I hope to eventually move to`
			`something general that can handle all CFGs (like GLL, GLR, LL(\*),`
			`etc).`

			`### Documentation`

move the setup instrutions out of README and into the book 2018-02-04 08:00:53 -05:00			`[The LALRPOP book] covers all things LALRPOP -- or at least it intends`
			`to! Here are some tips:`

			`- The [tutorial] covers the basics of setting up a LALRPOP parser.`
			`- For the impatient, you may prefer the [quick start guide] section, which describes`
			how to add LALRPOP to your `Cargo.toml`.
			`- The [advanced setup] chapter shows how to configure other aspects of LALRPOP's`
			`preprocessing.`
Add a link to gitter lobby It's surprisingly hard to google it when you don't know about it at all. 2019-07-09 18:16:38 +03:00			`- If you have any questions join our [gitter lobby].`
chore: Don't try to infer whether we are building in the lalrpop workspace Instead we use --all-features to enable a special `test` feature to run tests with a freshly generated lrgrammar.rs. Since we also have a test to check that the saved lrgrammar.rs is identical to what lalrpop generates we should be ok with this approach. Closes #436 2019-01-10 21:30:26 +01:00
Add real-life examples to README 2018-03-13 22:59:47 +03:00			`### Example Uses`

			`- [LALRPOP] is itself implemented in LALRPOP.`
			`- [Gluon] is a statically typed functional programming language.`
fix Gleam grammar link 2019-11-20 10:13:56 +08:00			`- [Gleam](https://github.com/gleam-lang/gleam/blob/master/src/grammar.lalrpop) is a statically typed functional programming language for the Erlang VM.`
Added RustPython to README in Example Uses section 2019-06-12 13:41:04 +03:00			`- [RustPython] is Python 3.5+ rewritten in Rust`
Add Solang to the list of examples Solang uses lalrpop for parsing Solidity. Signed-off-by: Sean Young <sean@mess.org> 2020-01-13 15:47:51 +00:00			`- [Solang] is Ethereum Solidity rewritten in Rust`
move the setup instrutions out of README and into the book 2018-02-04 08:00:53 -05:00
			`[The LALRPOP book]: http://lalrpop.github.io/lalrpop/`
			`[quick start guide]: http://lalrpop.github.io/lalrpop/quick_start_guide.html`
			`[advanced setup]: http://lalrpop.github.io/lalrpop/advanced_setup.html`
			`[tutorial]: http://lalrpop.github.io/lalrpop/tutorial/index.html`
Add real-life examples to README 2018-03-13 22:59:47 +03:00			`[LALRPOP]: https://github.com/lalrpop/lalrpop/blob/8034f3dacc4b20581bd10c5cb0b4f9faae778bb5/lalrpop/src/parser/lrgrammar.lalrpop`
			`[Gluon]: https://github.com/gluon-lang/gluon/blob/d7ce3e81c1fcfdf25cdd6d1abde2b6e376b4bf50/parser/src/grammar.lalrpop`
Added RustPython to README in Example Uses section 2019-06-12 13:41:04 +03:00			`[RustPython]: https://github.com/RustPython/RustPython/blob/master/parser/src/python.lalrpop`
Add Solang to the list of examples Solang uses lalrpop for parsing Solidity. Signed-off-by: Sean Young <sean@mess.org> 2020-01-13 15:47:51 +00:00			`[Solang]: https://github.com/hyperledger-labs/solang/blob/master/src/parser/solidity.lalrpop`
Add a link to gitter lobby It's surprisingly hard to google it when you don't know about it at all. 2019-07-09 18:16:38 +03:00			`[gitter lobby]: https://gitter.im/lalrpop/Lobby`
chore: Don't try to infer whether we are building in the lalrpop workspace Instead we use --all-features to enable a special `test` feature to run tests with a freshly generated lrgrammar.rs. Since we also have a test to check that the saved lrgrammar.rs is identical to what lalrpop generates we should be ok with this approach. Closes #436 2019-01-10 21:30:26 +01:00
			`### Contributing`

Document the contributing process 2019-07-14 20:56:41 +03:00			You really should read `CONTRIBUTING.md` if you intend to change LALRPOP's own grammar.