```text
_
| |_) | | __/ | (_| | | | | | \__ \
|_.__/ \___| \__,_| |_| |_| |___/
```
Beans is a lexing and parsing library. It allows both compiling the grammars,
and loading them at runtime, making it usable both for languages that have
fixed grammars, and languages whose syntax may vary during their compilation
phase.
Installation
============
Beans is not currently properly packaged, so unless you have [Nix](https://nixos.org),
the installation is manual.
Manual Installation
-------------------
### Dependencies
Beans is written in pure Rust and, as such, its only dependencies are (latest
stable) Rust and a few crates. This means that, to build Beans, you only need to
have on your machine the latest stable version of the Rust compiler, as well as
cargo (and make if you don't want to do everything manually).
### Downloading Beans sources
If you have git installed, then you can simply run `git clone https://github.com/jthulhu/beans`.
Otherwise, you can download the [zip archive](https://github.com/jthulhu/beans/archive/release.zip).
### Building Beans
#### Building Beans with make
If you are using make to install Beans as well, you can skip this step, as it's a
dependency of the `install` rule.
```shell
$ make RELEASE=1 build
```
The binary can be found at `out/beans`.
#### Building Beans manually
```shell
$ cargo build --release
```
The binary can be found at `target/release/beans`
### Installing Beans
#### Installing Beans with make
```shell
$ make install
```
This will install `beans` at `/usr/local/bin/beans`. If you want to change the
installation directory, you can set the environment variables `DESTDIR` and `PREFIX`.
By default, it uses `DESTDIR=` and `PREFIX=/usr/local`.
#### Install Beans manually
```shell
$ install -D -m755 target/release/beans /usr/local/bin/beans
```
Make sure to replace `target/release/beans` with the directory where the binary
has been produced, and `/usr/local/bin/beans` where you wish `beans` to be installed.
### Uninstalling Beans
No matter the installation method used, Beans is a single, self-contained binary, that
will not create any configuration file whatsoever. Just remove the binary where you
installed it.
Nix Flake installation
----------------------
Beans is provided as `github:jthulhu/beans#${system}.defaultPackage` as a package,
and as `github:jthulhu/beans#${system}.defaultApp` as an application, where `${system}`
can be `aarch64-darwin`, `aarch64-linux`, `x86_64-darwin` and `x86_64-linux`.
Usage
=====
Beans can be used as a library, and as an application. The application is used if
you want to compile lexer and parser grammars. The application can also do lexing
and parsing, which might be helpful for debugging.
Compilation
-----------
The first step to use Beans is to write a lexer grammar and a parser grammar, and
to compile them, in this order. This is important because the parser grammar
depends on the definition of terminals, which can be found in the lexer grammar.
To do so, assuming you have two files names `lexer.lx` and `parser.gr`, run
```shell
$ beans compile lexer lexer.lx
# Will produce a file `lexer.clx`
$ beans compile parser --lexer lexer.clx parser.gr
# Will produce a file `lexer.cgr`
$
```
These two files can now be used within Rust code, as follows
```rust
use beans::include_parser;
let (lexer, parser) = include_parser!(
lexer => compiled "path/to/lexer.clx",
parser => compiled "path/to/parser.cgr",
).unwrap();
```
This will ship in the final binary the two blobs. Refer to [the library
documentation](https://docs.rs/beans/latest/beans) for more details on how to use
`lexer` and `parser` to parse input.
Note that the compilation step is, in fact, *optional*. It is possible to use
non-compiled grammars. This is useful when you want the user to be able to modify
the grammar during the compilation of a program. **Currently, this feature may be
broken.**
Lexing
------
Beans can produce a stream of tokens in stdout, given the appropriate grammar.
For instance, on a the file `input.c` shown
```c
void f() {
int x;
int y;
y = x = 0;
}
```
and a lexer grammar corresponding to the C programming language, the lexing would
show the following result:
```shell
$ beans lex --lexer c.clx input.c
VOID { }
IDENT { 0: f, }
LPAR { }
RPAR { }
LBRACE { }
INTTY { }
IDENT { 0: x, }
SEMICOLON { }
INTTY { }
IDENT { 0: y, }
SEMICOLON { }
IDENT { 0: y, }
EQUAL { }
IDENT { 0: x, }
EQUAL { }
INT { 0: 0, }
SEMICOLON { }
RBRACE { }
```
Since the output is currently quite ugly, it will most likely be changed in the
foreseeable future.
Parsing
-------
Beans can produce an AST in stdout, given the appropriate grammars.
For instance, on the same `input.c` shown before, the result would be
```shell
$ beans parse --lexer c.clx --parser c.cgr input.c
AST
└─ decls
└─ value
├─ value
│ ├─ variant
│ │ └─ Nil
│ └─ head
│ ├─ name
│ │ └─ f
│ ├─ block
│ │ └─ stmts
│ │ └─ value
│ │ ├─ value
│ │ │ ├─ variant
│ │ │ │ └─ Cons
│ │ │ ├─ head
│ │ │ │ ├─ declaration
│ │ │ │ │ ├─ type
│ │ │ │ │ │ └─ variant
│ │ │ │ │ │ └─ Int
│ │ │ │ │ ├─ value
│ │ │ │ │ │ └─ variant
│ │ │ │ │ │ └─ None
│ │ │ │ │ └─ name
│ │ │ │ │ └─ x
│ │ │ │ └─ variant
│ │ │ │ └─ Declaration
│ │ │ └─ tail
│ │ │ ├─ variant
│ │ │ │ └─ Cons
│ │ │ ├─ head
│ │ │ │ ├─ variant
│ │ │ │ │ └─ Declaration
│ │ │ │ └─ declaration
│ │ │ │ ├─ name
│ │ │ │ │ └─ y
│ │ │ │ ├─ value
│ │ │ │ │ └─ variant
│ │ │ │ │ └─ None
│ │ │ │ └─ type
│ │ │ │ └─ variant
│ │ │ │ └─ Int
│ │ │ └─ tail
│ │ │ ├─ head
│ │ │ │ ├─ stmt
│ │ │ │ │ ├─ stmt
│ │ │ │ │ │ ├─ key
│ │ │ │ │ │ │ ├─ value
│ │ │ │ │ │ │ │ └─ y
│ │ │ │ │ │ │ └─ variant
│ │ │ │ │ │ │ └─ Ident
│ │ │ │ │ │ ├─ value
│ │ │ │ │ │ │ ├─ value
│ │ │ │ │ │ │ │ ├─ variant
│ │ │ │ │ │ │ │ │ └─ Int
│ │ │ │ │ │ │ │ └─ value
│ │ │ │ │ │ │ │ ├─ variant
│ │ │ │ │ │ │ │ │ └─ Int
│ │ │ │ │ │ │ │ └─ value
│ │ │ │ │ │ │ │ └─ 0
│ │ │ │ │ │ │ ├─ key
│ │ │ │ │ │ │ │ ├─ variant
│ │ │ │ │ │ │ │ │ └─ Ident
│ │ │ │ │ │ │ │ └─ value
│ │ │ │ │ │ │ │ └─ x
│ │ │ │ │ │ │ └─ variant
│ │ │ │ │ │ │ └─ Assign
│ │ │ │ │ │ └─ variant
│ │ │ │ │ │ └─ Assign
│ │ │ │ │ └─ variant
│ │ │ │ │ └─ Regular
│ │ │ │ └─ variant
│ │ │ │ └─ Statement
│ │ │ └─ variant
│ │ │ └─ Nil
│ │ └─ variant
│ │ └─ Some
│ ├─ rettype
│ │ └─ variant
│ │ └─ Void
│ └─ args
│ └─ value
│ └─ variant
│ └─ None
└─ variant
└─ Some
$
```
The result is very verbose, so this will likely change in the foreseeable future.