- Notifications
You must be signed in to change notification settings - Fork1
Syntax-Dynamic Parser-Generator Library
License
jthulhu/beans
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
_ | |__ ___ __ _ _ __ ___ | '_ \ / _ \ / _` | | '_ \ / __|| |_) | | __/ | (_| | | | | | \__ \|_.__/ \___| \__,_| |_| |_| |___/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 havefixed grammars, and languages whose syntax may vary during their compilationphase.
Beans is not currently properly packaged, so unless you haveNix,the installation is manual.
Beans is written in pure Rust and, as such, its only dependencies are (lateststable) Rust and a few crates. This means that, to build Beans, you only need tohave on your machine the latest stable version of the Rust compiler, as well ascargo (and make if you don't want to do everything manually).
If you have git installed, then you can simply rungit clone https://github.com/jthulhu/beans.Otherwise, you can download thezip archive.
If you are using make to install Beans as well, you can skip this step, as it's adependency of theinstall rule.
$ make RELEASE=1 build
The binary can be found atout/beans.
$ cargo build --release
The binary can be found attarget/release/beans
$ make install
This will installbeans at/usr/local/bin/beans. If you want to change theinstallation directory, you can set the environment variablesDESTDIR andPREFIX.By default, it usesDESTDIR= andPREFIX=/usr/local.
$ install -D -m755 target/release/beans /usr/local/bin/beans
Make sure to replacetarget/release/beans with the directory where the binaryhas been produced, and/usr/local/bin/beans where you wishbeans to be installed.
No matter the installation method used, Beans is a single, self-contained binary, thatwill not create any configuration file whatsoever. Just remove the binary where youinstalled it.
Beans is provided asgithub:jthulhu/beans#${system}.defaultPackage as a package,and asgithub:jthulhu/beans#${system}.defaultApp as an application, where${system}can beaarch64-darwin,aarch64-linux,x86_64-darwin andx86_64-linux.
Beans can be used as a library, and as an application. The application is used ifyou want to compile lexer and parser grammars. The application can also do lexingand parsing, which might be helpful for debugging.
The first step to use Beans is to write a lexer grammar and a parser grammar, andto compile them, in this order. This is important because the parser grammardepends on the definition of terminals, which can be found in the lexer grammar.To do so, assuming you have two files nameslexer.lx andparser.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 tothe librarydocumentation for more details on how to uselexer andparser to parse input.
Note that the compilation step is, in fact,optional. It is possible to usenon-compiled grammars. This is useful when you want the user to be able to modifythe grammar during the compilation of a program.Currently, this feature may bebroken.
Beans can produce a stream of tokens in stdout, given the appropriate grammar.For instance, on a the fileinput.c shown
voidf() {intx;inty;y=x=0;}
and a lexer grammar corresponding to the C programming language, the lexing wouldshow the following result:
$ beans lex --lexer c.clx input.cVOID { }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 theforeseeable future.
Beans can produce an AST in stdout, given the appropriate grammars.For instance, on the sameinput.c shown before, the result would be
$ beans parse --lexer c.clx --parser c.cgr input.cAST└─ 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.
About
Syntax-Dynamic Parser-Generator Library