Struct Parser

pub struct Parser<'source> { /* private fields */ }

A high-level parser for the language. This is the type to use to parse an arbitrary piece of code into an abstract syntax tree.

The parser contains an Arc to the tokens representing the source code to be parsed, and thus is relatively cheap to clone.

Implementations

impl<'source> Parser<'source>

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

Create a new parser for the given source.

pub fn state(&self) -> &ParserState

Returns an immutable reference to the parser’s state.

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

Sets the parser to point to the same token as the given parser. It is assumed that both parsers point to the same source code.

pub fn error(&self, kind: impl ErrorKind + 'static) -> Error

Creates an error that points at the current token, or the end of the source code if the cursor is at the end of the stream.

pub fn eof_span(&self) -> Range<usize>

Returns a span pointing at the end of the source code.

pub fn span(&self) -> Range<usize>

Returns the span of the current token, or the end of the source code if the cursor is at the end of the stream.

pub fn prev(&mut self)

Move the cursor to the previous token. This function is a no-op if the cursor is at the beginning of the stream.

pub fn prev_token(&self) -> Option<&Token<'source>>

Returns the previous token. The cursor is not moved. Returns None if the cursor is at the beginning of the stream.

pub fn current_token(&self) -> Option<&Token<'source>>

Returns the current token. The cursor is not moved. Returns None if the cursor is at the end of the stream.

pub fn advance_past_whitespace(&mut self)

Advances the cursor past whitespace tokens to the next non-whitespace token. The cursor is not guaranteed to point to a valid token (might be out of bounds), but if the token is valid, it is guaranteed to be non-whitespace.

pub fn advance_past_non_significant_whitespace(&mut self)

Advances the cursor past non-significant whitespace tokens to the next token. This next token can be a newline.

The cursor is not guaranteed to point to a valid token (might be out of bounds), but if the token is valid, it is guaranteed to be a newline, or otherwise, non-whitespace.

Newlines are significant in the context of implicit multiplication. Allowing implicit multiplication to span multiple lines has shown to be confusing and error-prone; for example, consider how this reasonably-looking file would be parsed (before implicit multiplication was restricted to the same line):

fact(n) = {
    out = n;
    while n > 1 {
        n -= 1;
        out *= n;
    };
    out
}

fact(14) == 14!

You would expect this code to behave like so:

1. Define the fact function.
2. Call the fact function with the argument 14 and compare the result to 14!.

It certainly seems that way. However, in the past, parsing this example would actually insert timplicit multiplication between the “end” of the function definition }, and fact(14), resulting in:

fact(n) = {
    out = n;
    while n > 1 {
        n -= 1;
        out *= n;
    };
    out
}
* // <-- implicit multiplication!!
fact(14) == 14!

The comparison fact(14) == 14! actually ends up being a part of the fact function definition, and no comparison is made! This function is used to prevent such confusion during parsing.

pub fn next_token(&mut self) -> Result<Token<'source>, Error>

Returns the current token, then advances the cursor. Whitespace tokens are skipped.

Returns an EOF error if there are no more tokens.

pub fn next_token_raw(&mut self) -> Result<Token<'source>, Error>

Returns the current token, then advances the cursor. Whitespace tokens are not skipped.

Returns an EOF error if there are no more tokens.

pub fn try_parse<T: Parse<'source>>(&mut self) -> ParseResult<T>

Speculatively parses a value from the given stream of tokens. This function can be used in the Parse::parse implementation of a type with the given Parser, as it will automatically backtrack the cursor position if parsing fails.

If parsing is successful, the stream is advanced past the consumed tokens and the parsed value is returned. Otherwise, the stream is left unchanged and an error is returned.

pub fn try_parse_with_state<F, T>(&mut self, modify_state: F) -> ParseResult<T>

where F: FnOnce(&mut ParserState), T: Parse<'source>,

Speculatively parses a value from the given stream of tokens. Before parsing, a copy of the parser is created with the state mutated using the given function. The original parser’s state will not change, but the cursor position can be advanced if the new parser was successful.

This function can be used in the Parse::parse implementation of a type with the given Parser, as it will automatically backtrack the cursor position if parsing fails.

If parsing is successful, the stream is advanced past the consumed tokens and the parsed value is returned. Otherwise, the stream is left unchanged and an error is returned.

pub fn try_parse_with_fn<T, F>(&mut self, f: F) -> ParseResult<T>

where F: FnOnce(&mut Parser<'source>) -> ParseResult<T>,

Speculatively parses a value from the given stream of tokens, using a custom parsing function to parse the value. This function can be used in the Parse::parse implementation of a type with the given Parser, as it will automatically backtrack the cursor position if parsing fails.

If parsing is successful, the stream is advanced past the consumed tokens and the parsed value is returned. Otherwise, the stream is left unchanged and an error is returned.

pub fn try_parse_then<T: Parse<'source>, F>( &mut self, predicate: F, ) -> ParseResult<T>

where F: FnOnce(&T, &Parser<'_>) -> ParseResult<()>,

Speculatively parses a value from the given stream of tokens, with a validation predicate. The value must parse successfully, and the predicate must return Ok for this function to return successfully.

If parsing is successful, the stream is advanced past the consumed tokens and the parsed value is returned. Otherwise, the stream is left unchanged and an error is returned.

pub fn try_parse_full<T: Parse<'source>>(&mut self) -> Result<T, Vec<Error>>

Attempts to parse a value from the given stream of tokens. All the tokens must be consumed by the parser; if not, an error is returned.

pub fn try_parse_full_many<T: Debug + Parse<'source>>( &mut self, ) -> Result<Vec<T>, Vec<Error>>

Attempts to parse multiple values from the given stream of tokens. All the tokens must be consumed by the parser; if not, an error is returned.

Trait Implementations

impl<'source> Clone for Parser<'source>

fn clone(&self) -> Parser<'source>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'source> Debug for Parser<'source>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.