Crate rustlr

rustlr is a parser generator that can create LALR(1) as well as full LR(1) parsers. It is also capable of recognizing operator precedence and associativity declarations that allows the use of some ambiguous grammars. Parsers also have optional access to external state information that allows them to recognize more than just context-free languages. Rustlr implements methods of error recovery similar to those found in other LR generators. For error reporting, however, rustlr parsers can run in training mode, in which, when a parse error is encountered, the human trainer can augment the parser’s state transition table with an appropriate error message. The augmented parser is automatically saved. See the RuntimeParser::parse_train function.

The parser can generate a full LR(1) parser given the ANSI C grammar in approximately 2-4 seconds on contemporary processors.

A detailed tutorial is being prepared that will explain the format of grammars and how to generate and use parsers for several sample languages.

Most of the items exported by this crate are only required by the parsers that are generated, and does not form an API. The user needs to provide a grammar and a lexical analyzer that implements the Lexer trait. Only a simple lexer that returns individual characters in a string (charlexer) is provided. The examples in the tutorial use basic_lexer, which was written by the same author but other tokenizers can be easily adopted as well, such as scanlex.

Example

Given this grammar, with file name “calculator.grammar”,

 rustlr calculator.grammar lr1

generates a LR(1) parser as a rust program. This program includes a make_parser function, which can be used as in

 let mut scanner = Exprscanner::new(&sourcefile);
 let mut parser1 = make_parser();
 let absyntree = parser1.parse(&mut scanner);

Here, Exprscanner is a structure that must implement the Lexer trait required by the generated parser.

A relatively self-contained example, containing both a grammar and code for using its generated parser, is found here.

Re-exports

pub use lexer_interface::*;

pub use generic_absyn::*;

pub use runtime_parser::RuntimeParser;

pub use runtime_parser::RProduction;

Modules

generic_absyn

Generic Abstract Syntax Support Module

lexer_interface

Rustlr allows the use of any lexical analyzer (tokenizer) that satisfies the Lexer trait. Only a simple charlexer tokenizer that separates non-whitespaces characters is provided as an example.

runtime_parser

Macros

lbox

macro for creating LBox structures, for use in grammar semantic actions: each semantic action associated with a grammar rule is a Rust lambda expression of the form |parser|{…} of type fn(&mut RuntimeParser) -> AT where AT is the type of the abstract syntax value defined for the grammar. lbox!(e) expands to parser.lb(e), calling the RuntimeParser::lb function. The macro can also form an ABox, which is an alias for 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.

Functions

decode_action

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

rustler

this is the only function that can invoke the parser generator externally, without running rustlr (rustlr::main) directly. It expects to find a file of the form grammarname.grammar. The option argument that can currently only be “lr1” or “lalr”. It generates a grammar in a file named grammarnameparser.rs.