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.

INSTALLING RUSTLR

Rustlr consists of two main components: the parser generation routines and the runtime parser routines that interpret the generated parsing tables. The default installation will install both. However, the runtime parser can be installed independently.

Rustlr should first be installed as a command-line application: cargo install rustlr. This will install both the generator and runtime parser.

Parser generation can also be invoked from within a rust program with the generate function of the rustlr crate.

Once a parser has been generated and included in another crate, rustlr should be installed with only the runtime parsing routines with cargo add rustlr --no-default-features. Alternatively, add the the following to your Cargo.toml:

  [dependencies]
  rustlr = { version = "0.5", default-features = false }

Compatibility Notice:

There is another optional feature, legacy-parser, that can be enabled with or without the parser generation routines, that is required for grammars and parsers for very old versions of rustlr (prior to version 0.2). This feature is not included by default and must be installed with the cargo install/add --features legacy-parser option.

Many of the items exported 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 be built around a basic ZCParser::parse_core function.

Re-exports

• pub use zc_parser::ZCParser;
• pub use zc_parser::ZCRProduction;
• pub use zc_parser::StackedItem;
• pub use runtime_parser::RuntimeParser;
• pub use runtime_parser::RProduction;
• pub use lexer_interface::*;
• pub use runtime_parser::*;
• 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.
• generate
  This function can be called from within Rust to generate a parser/lexer. It takes the same arguments as the rustlr command-line application. Furthermore, if given the -trace 0 option, no output will be sent to stdout or stderr. Instead, a log of events is recorded and is returned. An Ok(_) result indicates that some parser was created and an Err(_) result indicates failure. Example:
• iserror
  Determines if action is not valid
• rustle
  This function is retained for backwards compatiblity. It is recommended to call generate instead.