Expand description

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. The types generated do not necessarily reflect the format of the grammar.
  2. Recognizes regex-style operators *, + and ?, which simplify the writing of grammars and allow better ASTs to be created.
  3. Experimental features include the ability to signal delayed reduction transformations on a grammar. This extends the class of grammars usable with Rustlr beyond traditional LR and LALR grammars.
  4. The ability to train the parser interactively for better error reporting
  5. External state access allows parsers go to beyond CFGs

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

As a simplified, self-contained example of how to use rustlr, given this grammar with file name “brackets.grammar”,

 rustlr brackets.grammar

generates a LALR parser as a rust program. This program includes a ‘make_parser’ function and a ‘bracketslexer’ structure which represents the lexical scanner. The program also contains a ‘load_extras’ function, which can be modified by interactive training to give more helpful error messages other than the generic “unexpected symbol..”.

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 Abstract Syntax Support Module

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.

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

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

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

similar to lbdown, but also extracts the boxed expression

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.

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.

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

just extract value from LBox

Enums

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

Constants

Functions

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