Struct rustlr::runtime_parser::RuntimeParser

pub struct RuntimeParser<AT: Default, ET: Default> {
    pub exstate: ET,
    pub RSM: Vec<HashMap<&'static str, Stateaction>>,
    pub Rules: Vec<RProduction<AT, ET>>,
    pub stack: Vec<Stackelement<AT>>,
    pub resynch: HashSet<&'static str>,
    pub Errsym: &'static str,
    pub linenum: usize,
    pub column: usize,
    pub src_id: usize,
    pub Symset: HashSet<&'static str>,
    /* private fields */
}

this is the structure created by the generated parser. The generated parser program will contain a make_parser function that returns this structure. Most of the pub items are, however, only exported to support the operation of the parser, and should not be accessed directly. Only the functions RuntimeParser::parse, RuntimeParser::report, RuntimeParser::abort and RuntimeParser::error_occurred should be called directly from user programs. Only the field RuntimeParser::exstate should be accessed by user programs.

Fields

exstate: ET

this is the “external state” structure, with type ET defined by the grammar. The semantic actions associated with each grammar rule, which are written in the grammar, have ref mut access to the RuntimeParser structure, which allows them to read and change the external state object. This gives the parsers greater flexibility and capability, including the ability to parse some non-context free languages. See this sample grammar. The exstate is initialized to ET::default().

RSM: Vec<HashMap<&'static str, Stateaction>>

used only by generated parser: do not reference

Rules: Vec<RProduction<AT, ET>>

do not reference

stack: Vec<Stackelement<AT>>

do not reference

resynch: HashSet<&'static str>

Errsym: &'static str

linenum: usize

column: usize

src_id: usize

Symset: HashSet<&'static str>

Hashset containing all grammar symbols (terminal and non-terminal). This is used for error reporting and training.

Implementations

impl<AT: Default, ET: Default> RuntimeParser<AT, ET>

pub fn new(rlen: usize, slen: usize) -> RuntimeParser<AT, ET>

this is only called by the make_parser function in the machine-generated parser program. Do not call this function in other places as it only generates a skeleton.

pub fn abort(&mut self, msg: &str)

this function can be called from with the “semantic” actions attached to grammar production rules that are executed for each “reduce” action of the parser.

pub fn report(&mut self, errmsg: &str)

may be called from grammar semantic actions to report error. this report function will print to stdout.

pub fn bad_pattern(&mut self, pattern: &str) -> AT

this function is only exported to support the generated code

pub fn set_src_id(&mut self, id: usize)

sets an index that index source information, such as the source file when compiling multiple sources. This information must be maintained externally. The source id will also be passed on to the LBox and LRc smartpointers by the RuntimeParser::lb function.

pub fn error_occurred(&self) -> bool

can be called to determine if an error occurred during parsing. The parser will not panic.

pub fn parse_train(
    &mut self,
    tokenizer: &mut dyn Lexer<AT>,
    parserfile: &str
) -> AT

this function is equivalent to RuntimeParser::parse_stdio_train.

pub fn lb<T>(&self, e: T) -> LBox<T>

creates a LBox smart pointer that includes line/column/src information; should be called from the semantic actions of a grammar rule, e.g.

   E --> E:a + E:b {PlusExpr(parser.lb(a),parser.lb(b))}

pub fn lba<T: 'static>(&self, e: T) -> LBox<dyn Any>

creates a LBox<dyn Any>, which allows attributes of different types to be associated with grammar symbols. Use in conjuction with LBox::downcast, LBox::upcast and the lbdown, lbup macros.

pub fn lrc<T>(&self, e: T) -> LRc<T>

similar to RuntimeParser::lb, but creates a LRc instead of LBox

pub fn lrca<T: 'static>(&self, e: T) -> LRc<dyn Any>

similar to RuntimeParser::lba but creates a LRc

impl<AT: Default, ET: Default> RuntimeParser<AT, ET>

pub fn parse(&mut self, tokenizer: &mut dyn Lexer<AT>) -> AT

this function is used to invoke the generated parser returned by the generated parser program’s make_parser function. This function is equivalent to RuntimeParser::parse_stdio.

pub fn error_recover<'t>(
    &mut self,
    lookahead: &mut Lextoken<AT>,
    tokenizer: &mut dyn Lexer<AT>
) -> Option<Stateaction>

Error recovery routine of rustlr, separate from error_reporter. This function will modify the parser and lookahead symbol and return either the next action the parser should take (if recovery succeeded) or None if recovery failed.

impl<AT: Default, ET: Default> RuntimeParser<AT, ET>

pub fn parse_base(
    &mut self,
    tokenizer: &mut dyn Lexer<AT>,
    err_handler: &mut dyn ErrHandler<AT, ET>
) -> AT

Core parser (temporarily lives side by side with parse_core) that takes dynamic trait objects for lexical scanning and err_reporting. This design makes it possible to create a custom error reporting interface.

pub fn parse_stdio(&mut self, tokenizer: &mut dyn Lexer<AT>) -> AT

provided generic parsing function that reports errors on std::io. This function is equivalent to RuntimeParser::parse.

pub fn parse_stdio_train(
    &mut self,
    tokenizer: &mut dyn Lexer<AT>,
    parserfile: &str
) -> AT

Parses in interactive training mode with provided path to parserfile. The parser file will be modified and a training script file will be created for future retraining after grammar is modified. This function is equivalent to RuntimeParser::parse_train.

When an error occurs, the parser will ask the human trainer for an appropriate error message: it will then insert an entry into its state transition table to give the same error message on future errors of the same type. If the error is caused by an unexpected token that is recognized as a terminal symbol of the grammar, the trainer can select to enter the entry under the reserved ANY_ERROR symbol. If the unexpected token is not recognized as a grammar symbol, then the entry will always be entered under ANY_ERROR. ANY_ERROR entries for a state will match all future unexpected symbols for that state: however, entries for valid grammar symbols will still override the generic entry.

Example: with the parser for this toy grammar, parse_train can run as follows:

  Write something in C+- : cout << x y ;   
  ERROR on line 1, column 0: unexpected symbol y ..
  >>>TRAINER: is this error message adequate? If not, enter a better one: need another <<                   
  >>>TRAINER: should this message be given for all unexpected symbols in the current state? (default yes) yes

(ignore the column number as the lexer for this toy language does not implement it)

parse_train will then produced a modified parser as specified by the filename (path) argument. When the augmented parser is used, it will give a more helpful error message:

 Write something in C+- : cout << x endl
 ERROR on line 1, column 0: unexpected symbol endl, ** need another << ** ..

parse_stdio_train calls parse_stdio, which uses stdin/stdout for user interface. Parsing in interactive training mode also produces a training script file which can be used to re-train a parser using RuntimeParser::train_from_script. This is useful after a grammar is modified with extensions to a language.

pub fn train_from_script(
    &mut self,
    tokenizer: &mut dyn Lexer<AT>,
    parserfile: &str,
    scriptfile: &str
)

trains parser from a training script created by interactive training. This is intended to be used after a grammar has been modified and the parser is regenerated with different state numbers. It is the user’s responsibility to keep consistent the parser file, script file, and sample input that was used when the script was created. The script contains the line and column numbers of each error encountered, along with either the unexpected symbol that caused the error, or the reserved ANY_ERROR symbol if the error message is to be applied to all unexpected symbols. These entries must match, in sequence, the errors encountered during retraining - it is therefore recommended that the same tokenizer be used during retraining so that the same line/column information are given. The trainer will augment the parser (parserfile) with new Error entries, overriding any previous ones. It is also recommended that the user examines the “load_extras” function that appears at the end of the augmented parser. The train_from_script function does not return a value, unlike RuntimeParser::parse_stdio and RuntimeParser::parse_stdio_train.