Struct ParserState 

pub struct ParserState<'a, L> { /* private fields */ }

The inner state of a parser.

ParserState is a cursor over the lexer and keeps track of the current position in the source code. It is used to drive the parsing process.

Writing a Parser

A parser is a function Fn(&ParserState) -> Result<T, Error>, that takes a &ParserState as input and returns the parsed result or an error.

The common use case is to call the parse method to read a token from the lexer and advance the state by one token.

fn parse_abc(state: &mut ParserState<CharLexer>) -> Result<char, Error> {
    state.parse_char('a')?;
    state.parse_char('b')?;
    state.parse_char('c')?;
    Ok('c')
}

let mut state = ParserState::new("abc");
parse_abc(&mut state).unwrap();
assert!(state.is_empty());

Please note that ParserState uses interior mutability to share its state between parsers. This means that even if a parser takes a &ParserState, the state can still be mutated.

Speculative Parsing

ParserState allows you to create a fork of the current state via the fork method, and join it back to the original state later via the advance_to method. This is useful for speculative parsing.

It’s important to note that ParserState can only move forward and not backward. When joining a fork back to the original state, it must be ensured that the fork is at a position beyond or equal to the original state.

fn parse_option(
    state: &mut ParserState<CharLexer>,
    parser: impl Fn(&mut ParserState<CharLexer>) -> Result<char, Error>
) -> Result<Option<char>, Error> {
    let fork = &mut state.fork();
    match parser(fork) {
        Ok(c) => {
            state.advance_to(fork);
            Ok(Some(c))
        }
        Err(_) => Ok(None),
    }
}

let mut state = ParserState::new("aaa");
assert_eq!(parse_option(&mut state, |state| state.parse_char('a')).unwrap(), Some('a'));
assert_eq!(parse_option(&mut state, |state| state.parse_char('b')).unwrap(), None);

Implementations

impl<'a, L: LexIt + Clone> ParserState<'a, L>

pub fn new(input: &'a str) -> Self

Create a new parser state from the given lexer.

pub fn cursor(&self) -> Cursor

Get the current parsing position.

pub fn parse_with<T>( &mut self, matches: impl FnOnce(L::Token<'a>) -> Option<T>, ) -> Result<T, Error>

Consume the next token if it matches the given token.

pub fn parse_type<T>(&mut self) -> Result<T, Error>

where L::Token<'a>: TryConvert<T>, T: PartialEq,

Parse a token that can be converted to the given type.

pub fn parse_char(&mut self, c: char) -> Result<char, Error>

Parse a token that exactly matches the given character.

pub fn parse_str(&mut self, literal: &'a str) -> Result<&str, Error>

Parse a token that exactly matches the given string.

pub fn error(&self) -> Error

Report an error at the current position.

pub fn is_empty(&self) -> bool

Whether the parser is at the end of the input.

pub fn advance_to(&mut self, other: &Self)

Advance the state to the given state.

Panics

Panics if the given state is before the current state.

pub fn advance_to_cursor(&mut self, cursor: Cursor)

Advance the state to the given position.

Panics

Panics if the given position is before the current position.

pub fn fork(&self) -> Self

Create a fork of the current state for speculative parsing.

pub fn push(&self, name: &'static str)

Push the given name onto the stack (for debugging purposes).

pub fn pop(&self)

Pop the last name from the stack (for debugging purposes).

pub fn debug(&self) -> String

Get the current stack (for debugging purposes).