_
| |__ ___ __ _ _ __ ___
| '_ \ / _ \ / _` | | '_ \ / __|
| |_) | | __/ | (_| | | | | | \__ \
|_.__/ \___| \__,_| |_| |_| |___/
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.
Beans is not currently properly packaged, so unless you have Nix, the installation is manual.
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).
If you have git installed, then you can simply run git clone https://github.com/jthulhu/beans.
Otherwise, you can download the zip archive.
If you are using make to install Beans as well, you can skip this step, as it's a
dependency of the install rule.
$ make RELEASE=1 buildThe binary can be found at out/beans.
$ cargo build --releaseThe binary can be found at target/release/beans
$ make installThis 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 -D -m755 target/release/beans /usr/local/bin/beansMake 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.
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.
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.
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.
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
$ 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
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 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.
Beans can produce a stream of tokens in stdout, given the appropriate grammar.
For instance, on a the file input.c shown
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:
$ 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.
Beans can produce an AST in stdout, given the appropriate grammars.
For instance, on the same input.c shown before, the result would be
$ 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.