Struct rustlr::zc_parser::ZCParser

pub struct ZCParser<AT: Default, ET: Default> {

    pub exstate: ET,
    pub shared_state: Rc<RefCell<ET>>,
    pub RSM: Vec<HashMap<&'static str, Stateaction>>,
    pub Rules: Vec<ZCRProduction<AT, ET>>,
    pub stack: Vec<StackedItem<AT>>,
    pub resynch: HashSet<&'static str>,
    pub Errsym: &'static str,
    pub linenum: usize,
    pub column: usize,
    pub position: usize,
    pub prev_position: 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 ZCParser::parse, ZCParser::report, ZCParser::abort and ZCParser::error_occurred should be called directly from user programs. Only the field ZCParser::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 ZCParser 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().

shared_state: Rc<RefCell<ET>>

External state that can be shared

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

used only by generated parser: do not reference

Rules: Vec<ZCRProduction<AT, ET>>

do not reference

stack: Vec<StackedItem<AT>>

do not reference

resynch: HashSet<&'static str>

Errsym: &'static str

linenum: usize

axiom: linenum and column represents the starting position of the topmost StackedItem.

column: usize

position: usize

prev_position: 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> ZCParser<AT, ET>

pub fn new(rlen: usize, slen: usize) -> ZCParser<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 current_line(&self) -> usize

returns the current line number

pub fn current_column(&self) -> usize

returns the current column number

pub fn current_position(&self) -> usize

returns the current absolute byte position according to tokenizer

pub fn previous_position(&self) -> usize

returns the previous position (before shift) according to tokenizer

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 report_error(&mut self, errmsg: &str, showlc: bool)

same as ZCParser::report but with option to display line/column

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

this function is only exported to support the generated code

pub fn popstack(&mut self) -> StackedItem<AT>

this function is called from the generated semantic actions and should most definitely not be called from elsewhere as it would corrupt the base parser.

pub fn error_occurred(&self) -> bool

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

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

creates a LBox smart pointer that includes line/column 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 ZCParser::lb, but creates a LRc instead of LBox

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

similar to ZCParser::lba but creates a LRc

pub fn lbx<T>(&self, i: usize, e: T) -> LBox<T>

creates LBox enclosing e using line/column information associated with right-hand side symbols, numbered left-to-right starting at 0

pub fn lrcn<T>(&self, i: usize, e: T) -> LRc<T>

Like lbx but creates an LRc

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

pub fn error_recover<'t>(
    &mut self,
    lookahead: &mut TerminalToken<'t, AT>,
    tokenizer: &mut dyn Tokenizer<'t, 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> ZCParser<AT, ET>

pub fn parse_core<'u, 't: 'u>(
    &mut self,
    tokenizer: &'u mut dyn Tokenizer<'t, AT>,
    err_handler: &mut dyn ErrReporter<AT, ET>
) -> AT

This function provides a core parser that uses the LR state machine generated by rustlr. It takes as trait objects a tokenizer and an ErrReporter object that handles the display of error messages.

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

provided generic parsing function that reports errors on std::io.

pub fn parse_train<'t>(
    &mut self,
    tokenizer: &mut dyn Tokenizer<'t, 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.

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 ZCParser::train_from_script. This is useful after a grammar is modified with extensions to a language.

pub fn train_from_script<'t>(
    &mut self,
    tokenizer: &mut dyn Tokenizer<'t, 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 ZCParser::parse and ZCParser::parse_train.