Crate rustlr

Rustlr is an LR-style parser generator for Rust. Advanced features include:

1. Option to automatically generate the AST datatypes and semantic actions, with manual overrides possible. Rustlr’s grammar format contains a sublanguage that controls how ASTS are created, so that the generated types do not necessarily reflect the format of the grammar.

2. Option to use bumpalo to create ASTS types that enable nested pattern matching against recursive types.

3. Recognizes regex-style operators *, + and ?, which simplify the writing of grammars and allow better ASTs to be created.

4. An experimental feature that recognizes Selective Marcus-Leermakers grammars. This is a class of unambiguous grammars that’s larger than traditional LR grammars. They are especially helpful in avoiding conflicts when new production rules are added to a grammar.

5. The ability to train the parser interactively for better error reporting

6. Also generates parsers for F# and other .Net languages

A tutorial is separately available that will explain the format of grammars and how to generate and deploy parsers for several examples. The documentation found here should be used as a technical reference.

Rustlr should be installed as an executable (cargo install rustlr), although parser generation can also be invoked with the rustle function. Many of the items exported by this crate are only required by the parsers that are generated, and are not intended to be used in other programs. However, rustlr uses traits and trait objects to loosely couple the various components of the runtime parser so that custom interfaces, such as those for graphical IDEs, can built around a basic ZCParser::parse_core function.

Re-exports

pub use runtime_parser::RuntimeParser;

pub use runtime_parser::RProduction;

pub use zc_parser::ZCParser;

pub use zc_parser::ZCRProduction;

pub use lexer_interface::*;

pub use generic_absyn::*;

Modules

generic_absyn

Generic Abstract Syntax Support Module

lexer_interface

Rustlr allows the use of any lexical analyzer (tokenizer) that satisfies the Tokenizer trait. However, a basic tokenizer, StrTokenizer is provided that suffices for many examples. This tokenizer is not maximally efficient (not single-pass) as it uses regex.

runtime_parser

This module is deprecated by the crate::zc_parser module and is only kept for compatibility with existing parsers.

zc_parser

This module implements a zero-copy version of the runtime parser that uses the LR statemachine generated by rustlr. It will (for now), live side along with the original parser implemented as crate::RuntimeParser. Since Version 0.2.3, this module can now generate a basic lexical scanner based on crate::RawToken and crate::StrTokenizer.

Macros

lbdown

macro for downcasting LBox<dyn Any> to LBox<A> for some concrete type A. Must be called from within the semantic actions of grammar productions. Warning: unwrap is called within the macro

lbget

similar to lbdown, but also extracts the boxed expression

lbup

macro for creating LBox<dyn Any> structures that can encapsulate any type as abstract syntax. Must be called from within the semantic actions of a grammar production rule.

makelbox

macro for creating an LBox from a crate::StackedItem ($si) popped from the parse stack; should be called from within the semantics actions of a grammar to accurately encode lexical information.

makelrc

similar to makelbox but creates an LRc from lexical information inside stack item $si

unbox

just extract value from LBox

Enums

Stateaction

this enum is only exported because it’s used by the generated parsers. There is no reason to use it in other programs.

Constants

VERSION

Functions

decode_action

this function is only exported because it’s used by the generated parsers.

rustle

This is the function called from main in the rustlr executable once rustlr has been installed with cargo install rustlr. This function can also be called from another rust program to generate a parser: add `rustlr = “0.4” to Cargo dependencies. It accepts the same command-line arguments as the executable in a vector of strings. See the documentation and tutorial on how to use rustlr as an executable.