diff --git a/README.md b/README.md index 3f7c966..eb5e9f7 100644 --- a/README.md +++ b/README.md @@ -28,90 +28,17 @@ etc). ### Documentation -There is [documentation available here] that covers a fair bit of the -features of LALRPOP. For the more advanced things are not yet covered, -it also points to tests that may help give the idea. This will eventually -become a reference manual. +[The LALRPOP book] covers all things LALRPOP -- or at least it intends +to! Here are some tips: -[documentation available here]: https://lalrpop.github.io/lalrpop/README.html +- 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. -### Obligatory disclaimer - -LALRPOP is still in its relatively early days. Not all the features I -want are there, and the error messages are sometimes a bit opaque. But -it's quite powerful already. It's also [self-hosting], which is fun. - -[self-hosting]: https://github.com/nikomatsakis/lalrpop/blob/master/lalrpop/src/parser/lrgrammar.lalrpop - -### Using LALRPOP - -#### Configuring cargo - -There are two ways to use LALRPOP. The recommended way is to -configure Cargo to automatically change all `.lalrpop` files -into `.rs` files by adding a `build.rs` file. Here is a "cheat sheet" -for how to do that. - -This section is for if you already know what you're doing and just -want to copy-and-paste some code for adding LALRPOP to your Cargo -project. To enable LALRPOP, add the following lines to your -`Cargo.toml`: - -``` -[package] -... -build = "build.rs" # LALRPOP preprocessing - -# Add a dependency on the regex crate; this is not -# needed if you are writing your own tokenizer by -# hand (or if you are already using the regex crate) -[dependencies.regex] -version = "0.2.0" - -# Add a dependency on the LALRPOP runtime library: -[dependencies.lalrpop-util] -version = "0.14.0" - -[build-dependencies.lalrpop] -version = "0.14.0" -``` - -And create a `build.rs` file that looks like: - -```rust -extern crate lalrpop; - -fn main() { - lalrpop::process_root().unwrap(); -} -``` - -(If you already have a `build.rs` file, you should be able to just -call `process_root` in addition to whatever else that file is doing.) - -That's it! - -#### More advanced configuration - -The `process_root` applies the default configuration: so it will -transform `.lalrpop` files into `.rs` files *in-place* (in your `src` -directory), and it will only do so if the `.lalrpop` file has actually -changed. But you can also use the [`Configuration`][config] struct to -get more detailed control. - -[config]: https://github.com/nikomatsakis/lalrpop/blob/master/lalrpop/src/api/mod.rs - -#### Running manually - -If you prefer, you can also run the `lalrpop` crate as an -executable. Simply run `cargo install lalrpop` and then you will get a -`lalrpop` binary you can execute, like so: - -``` -lalrpop file.lalrpop -``` - -This will generate `file.rs` for you. Note that it only executes if -`file.lalrpop` is newer than `file.rs`; if you'd prefer to execute -unconditionally, pass `-f` (also try `--help` for other options). +[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 diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md index 8301f3b..5b12bac 100644 --- a/doc/src/SUMMARY.md +++ b/doc/src/SUMMARY.md @@ -2,6 +2,7 @@ - [LALRPOP](README.md) - [Crash course on parsers](crash_course.md) +- [Quick start guide](quick_start_guide.md) - [Tutorial](tutorial/index.md) - [Adding LALRPOP to your project](tutorial/001_adding_lalrpop.md) - [Parsing parenthesized numbers](tutorial/002_paren_numbers.md) @@ -12,5 +13,7 @@ - [Macros](tutorial/007_macros.md) - [Error recovery](tutorial/008_error_recovery.md) - [Writing a custom lexer](lexer_tutorial/index.md) +- [Advanced setup](advanced_setup.md) + - [Using the Cargo `OUT_DIR`](out_dir.md) ----------- [Contributors](misc/contributors.md) diff --git a/doc/src/advanced_setup.md b/doc/src/advanced_setup.md new file mode 100644 index 0000000..869e583 --- /dev/null +++ b/doc/src/advanced_setup.md @@ -0,0 +1,31 @@ +When you setup LALRPOP, you create a `build.rs` file that looks something +like this: + +```rust +extern crate lalrpop; + +fn main() { + lalrpop::process_root().unwrap(); +} +``` + +This `process_root()` call simply applies the default configuration: +so it will transform `.lalrpop` files into `.rs` files *in-place* (in +your `src` directory), and it will only do so if the `.lalrpop` file +has actually changed. But you can also use the +[`Configuration`][config] struct to get more detailed control. + +[config]: https://docs.rs/lalrpop/*/lalrpop/struct.Configuration.html + +For example, to **force** the use of colors in the output (ignoring +the TTY settings), you might make your `build.rs` file look like so: + +```rust +extern crate lalrpop; + +fn main() { + Configuration::new() + .always_use_colors() + .process_current_dir(); +} +``` diff --git a/doc/src/out_dir.md b/doc/src/out_dir.md new file mode 100644 index 0000000..fd8026b --- /dev/null +++ b/doc/src/out_dir.md @@ -0,0 +1,24 @@ +One common request is to have LALRPOP generate its files into Cargo's +**output directory**, rather than storing them 'in-place' within the +module tree. This can be done through the following configuration: + +```rust +extern crate lalrpop; + +fn main() { + Configuration::new() + .use_cargo_dir_conventions() + .process(); +} +``` + +In addition, because the modules are generated out of the `src` +directory, for each `foo.lalrpop` file you can't simply have `mod +foo;` in your source. Instead, you must put the following in the +parent module: + +```rust +include!(concat!(env!("OUT_DIR"), "/path/to/foo.rs")); +``` + +Here the `path/to/foo.rs` should be relative to the `src` directory. diff --git a/doc/src/quick_start_guide.md b/doc/src/quick_start_guide.md new file mode 100644 index 0000000..ed19889 --- /dev/null +++ b/doc/src/quick_start_guide.md @@ -0,0 +1,59 @@ +For getting started with LALRPOP, it's probably best if you read +[the tutorial](tutorial/index.html), which will introduce you +to the syntax of LALRPOP files and so forth. + +But if you've done this before, or you're just the impatient sort, +here is a quick 'cheat sheet' for setting up your project. First, add +the following lines to your `Cargo.toml`: + +``` +[package] +... +build = "build.rs" # LALRPOP preprocessing + +# The generated code depends on lalrpop-util. +# +# The generated tokenizer depends on the regex crate. +# +# (If you write your own tokenizer, or already have the regex +# crate, you can skip this dependency.) +[dependencies] +lalrpop-util = "0.14.0" +regex = "0.2.0" + +# Add a build-time dependency on the lalrpop library: +[build-dependencies] +lalrpop = "0.14.0" +``` + +Next create a `build.rs` file that looks like: + +```rust +extern crate lalrpop; + +fn main() { + lalrpop::process_root().unwrap(); +} +``` + +(If you already have a `build.rs` file, you should be able to just +call `process_root` in addition to whatever else that file is doing.) + +That's it! Note that `process_root` simply uses the default settings. +If you want to configure how LALRPOP executes, see the +[advanced setup](advanced_setup.html) section. + +#### Running manually + +If you prefer, you can also run the `lalrpop` crate as an +executable. Simply run `cargo install lalrpop` and then you will get a +`lalrpop` binary you can execute, like so: + +``` +lalrpop file.lalrpop +``` + +This will generate `file.rs` for you. Note that it only executes if +`file.lalrpop` is newer than `file.rs`; if you'd prefer to execute +unconditionally, pass `-f` (also try `--help` for other options). + diff --git a/doc/src/tutorial/001_adding_lalrpop.md b/doc/src/tutorial/001_adding_lalrpop.md index 010b29c..7047737 100644 --- a/doc/src/tutorial/001_adding_lalrpop.md +++ b/doc/src/tutorial/001_adding_lalrpop.md @@ -17,7 +17,7 @@ To start, let's use `cargo new` to make a new project. We'll call it > cargo new --bin calculator ``` -We now have to edit the generated [`calculator/Cargo.toml`][cargotoml] +We now have to edit the generated [`calculator/Cargo.toml`](calculator/Cargo.toml) file to invoke the LALRPOP preprocessor. The resulting file should look something like: diff --git a/publish.sh b/publish.sh index 0d2cedb..87016c9 100755 --- a/publish.sh +++ b/publish.sh @@ -39,14 +39,25 @@ publish lalrpop-util publish lalrpop-snap publish lalrpop -printf "Updated version in README and tutorial..." +printf "Updated version in docs etc..." perl -p -i -e 's/^version = "[0-9.]+"$/version = "'$VERSION'"/' \ - README.md doc/tutorial.md doc/*/Cargo.toml >& $TMPDIR/publish-log || publish_fail + doc/*/Cargo.toml \ + >& $TMPDIR/publish-log || publish_fail perl -p -i -e 's/^lalrpop = "[0-9.]+"$/lalrpop = "'$VERSION'"/' \ - doc/tutorial.md doc/*/Cargo.toml >& $TMPDIR/publish-log || publish_fail + doc/src/*.md \ + doc/src/tutorial/*.md \ + doc/*/Cargo.toml \ + >& $TMPDIR/publish-log || publish_fail perl -p -i -e 's/^lalrpop-util = "[0-9.]+"$/lalrpop-util = "'$VERSION'"/' \ - doc/tutorial.md doc/*/Cargo.toml >& $TMPDIR/publish-log || publish_fail -git add -f README.md doc/tutorial.md doc/*/Cargo.toml >& $TMPDIR/publish-log || publish_fail + doc/src/*.md \ + doc/src/tutorial/*.md \ + doc/*/Cargo.toml \ + >& $TMPDIR/publish-log || publish_fail +git add -f \ + doc/src/*.md \ + doc/src/tutorial/*.md \ + doc/*/Cargo.toml \ + >& $TMPDIR/publish-log || publish_fail printf "OK\n" -printf "\nAll set. Do not forget to commit new README.md et al.\n" +printf "\nAll set. **Do not forget to commit new changes.**\n"