_                                  
| |__     ___    __ _   _ __    ___ 
| '_ \   / _ \  / _` | | '_ \  / __|
| |_) | |  __/ | (_| | | | | | \__ \
|_.__/   \___|  \__,_| |_| |_| |___/
                                    

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, 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.

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.

$ make RELEASE=1 build

The binary can be found at out/beans.

Building Beans manually

$ cargo build --release

The binary can be found at target/release/beans

Installing Beans

Installing Beans with make

$ 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

$ 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

$ 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.

Lexing

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.

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

$ 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.