Struct Recursive

pub struct Recursive<'a, I, O, E: Error<I>>(/* private fields */);

A parser that can be defined in terms of itself by separating its declaration from its definition.

Prefer to use recursive(), which exists as a convenient wrapper around both operations, if possible.

Implementations

impl<'a, I: Clone, O, E: Error<I>> Recursive<'a, I, O, E>

pub fn declare() -> Self

Declare the existence of a recursive parser, allowing it to be used to construct parser combinators before being fulled defined.

Declaring a parser before defining it is required for a parser to reference itself.

This should be followed by exactly one call to the Recursive::define method prior to using the parser for parsing (i.e: via the Parser::parse method or similar).

Prefer to use recursive(), which is a convenient wrapper around this method and Recursive::define, if possible.

Examples

#[derive(Debug, PartialEq)]
enum Chain {
    End,
    Link(char, Box<Chain>),
}

// Declare the existence of the parser before defining it so that it can reference itself
let mut chain = Recursive::<_, _, Simple<char>>::declare();

// Define the parser in terms of itself.
// In this case, the parser parses a right-recursive list of '+' into a singly linked list
chain.define(just('+')
    .then(chain.clone())
    .map(|(c, chain)| Chain::Link(c, Box::new(chain)))
    .or_not()
    .map(|chain| chain.unwrap_or(Chain::End)));

assert_eq!(chain.parse(""), Ok(Chain::End));
assert_eq!(
    chain.parse("++"),
    Ok(Chain::Link('+', Box::new(Chain::Link('+', Box::new(Chain::End))))),
);

pub fn define<P: Parser<I, O, Error = E> + 'a>(&mut self, parser: P)

Defines the parser after declaring it, allowing it to be used for parsing.

Trait Implementations

impl<'a, I: Clone, O, E: Error<I>> Clone for Recursive<'a, I, O, E>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a, I: Clone, O, E: Error<I>> Parser<I, O> for Recursive<'a, I, O, E>

type Error = E

The type of errors emitted by this parser.

fn parse_recovery<'a, Iter, S>( &self, stream: S, ) -> (Option<O>, Vec<Self::Error>)

where Self: Sized, Iter: Iterator<Item = (I, <Self::Error as Error<I>>::Span)> + 'a, S: Into<Stream<'a, I, <Self::Error as Error<I>>::Span, Iter>>,

Parse a stream of tokens, yielding an output if possible, and any errors encountered along the way.

fn parse_recovery_verbose<'a, Iter, S>( &self, stream: S, ) -> (Option<O>, Vec<Self::Error>)

where Self: Sized, Iter: Iterator<Item = (I, <Self::Error as Error<I>>::Span)> + 'a, S: Into<Stream<'a, I, <Self::Error as Error<I>>::Span, Iter>>,

Parse a stream of tokens, yielding an output if possible, and any errors encountered along the way. Unlike Parser::parse_recovery, this function will produce verbose debugging output as it executes.

fn parse<'a, Iter, S>(&self, stream: S) -> Result<O, Vec<Self::Error>>

where Self: Sized, Iter: Iterator<Item = (I, <Self::Error as Error<I>>::Span)> + 'a, S: Into<Stream<'a, I, <Self::Error as Error<I>>::Span, Iter>>,

Parse a stream of tokens, yielding an output or any errors that were encountered along the way.

fn debug<T>(self, x: T) -> Debug<Self>

where Self: Sized, T: Display + 'static,

Include this parser in the debugging output produced by Parser::parse_recovery_verbose.

fn map<U, F>(self, f: F) -> Map<Self, F, O>

where Self: Sized, F: Fn(O) -> U,

Map the output of this parser to another value.

fn map_with_span<U, F>(self, f: F) -> MapWithSpan<Self, F, O>

where Self: Sized, F: Fn(O, <Self::Error as Error<I>>::Span) -> U,

Map the output of this parser to another value, making use of the pattern’s span when doing so.

fn map_err<F>(self, f: F) -> MapErr<Self, F>

where Self: Sized, F: Fn(Self::Error) -> Self::Error,

Map the primary error of this parser to another value.

fn or_else<F>(self, f: F) -> OrElse<Self, F>

where Self: Sized, F: Fn(Self::Error) -> Result<O, Self::Error>,

Map the primary error of this parser to a result. If the result is Ok, the parser succeeds with that value.

fn map_err_with_span<F>(self, f: F) -> MapErrWithSpan<Self, F>

where Self: Sized, F: Fn(Self::Error, <Self::Error as Error<I>>::Span) -> Self::Error,

Map the primary error of this parser to another value, making use of the span from the start of the attempted to the point at which the error was encountered.

fn try_map<U, F>(self, f: F) -> TryMap<Self, F, O>

where Self: Sized, F: Fn(O, <Self::Error as Error<I>>::Span) -> Result<U, Self::Error>,

After a successful parse, apply a fallible function to the output. If the function produces an error, treat it as a parsing error.

fn validate<F, U>(self, f: F) -> Validate<Self, O, F>

where Self: Sized, F: Fn(O, <Self::Error as Error<I>>::Span, &mut dyn FnMut(Self::Error)) -> U,

Validate an output, producing non-terminal errors if it does not fulfil certain criteria.

fn labelled<L>(self, label: L) -> Label<Self, L>

where Self: Sized, L: Into<<Self::Error as Error<I>>::Label> + Clone,

Label the pattern parsed by this parser for more useful error messages.

fn to<U>(self, x: U) -> To<Self, O, U>

where Self: Sized, U: Clone,

Transform all outputs of this parser to a pretermined value.

fn foldl<A, B, F>(self, f: F) -> Foldl<Self, F, A, B>

where Self: Parser<I, (A, B)> + Sized, B: IntoIterator, F: Fn(A, B::Item) -> A,

Left-fold the output of the parser into a single value.

fn foldr<'a, A, B, F>(self, f: F) -> Foldr<Self, F, A, B>

where Self: Parser<I, (A, B)> + Sized, A: IntoIterator, A::IntoIter: DoubleEndedIterator, F: Fn(A::Item, B) -> B + 'a,

Right-fold the output of the parser into a single value.

fn ignored(self) -> Ignored<Self, O>

where Self: Sized,

Ignore the output of this parser, yielding () as an output instead.

fn collect<C>(self) -> Map<Self, fn(_: O) -> C, O>

where Self: Sized, O: IntoIterator, C: FromIterator<O::Item>,

Collect the output of this parser into a type implementing FromIterator.

fn then<U, P>(self, other: P) -> Then<Self, P>

where Self: Sized, P: Parser<I, U, Error = Self::Error>,

Parse one thing and then another thing, yielding a tuple of the two outputs.

fn then_with<U, P, F: Fn(O) -> P>( self, other: F, ) -> ThenWith<I, O, U, Self, P, F>

where Self: Sized, P: Parser<I, U, Error = Self::Error>,

Parse one thing and then another thing, creating the second parser from the result of the first. If you only have a couple cases to handle, prefer Parser::or.

fn chain<T, U, P>( self, other: P, ) -> Map<Then<Self, P>, fn(_: (O, U)) -> Vec<T>, (O, U)>

where Self: Sized, U: Chain<T>, O: Chain<T>, P: Parser<I, U, Error = Self::Error>,

Parse one thing and then another thing, attempting to chain the two outputs into a Vec.

fn flatten<T, Inner>(self) -> Map<Self, fn(_: O) -> Vec<T>, O>

where Self: Sized, O: IntoIterator<Item = Inner>, Inner: IntoIterator<Item = T>,

Flatten a nested collection.

fn ignore_then<U, P>(self, other: P) -> IgnoreThen<Self, P, O, U>

where Self: Sized, P: Parser<I, U, Error = Self::Error>,

Parse one thing and then another thing, yielding only the output of the latter.

fn then_ignore<U, P>(self, other: P) -> ThenIgnore<Self, P, O, U>

where Self: Sized, P: Parser<I, U, Error = Self::Error>,

Parse one thing and then another thing, yielding only the output of the former.

fn padded_by<U, P>( self, other: P, ) -> ThenIgnore<IgnoreThen<P, Self, U, O>, P, O, U>

where Self: Sized, P: Parser<I, U, Error = Self::Error> + Clone,

Parse a pattern, but with an instance of another pattern on either end, yielding the output of the inner.

fn delimited_by<U, V, L, R>( self, start: L, end: R, ) -> DelimitedBy<Self, L, R, U, V>

where Self: Sized, L: Parser<I, U, Error = Self::Error>, R: Parser<I, V, Error = Self::Error>,

Parse the pattern surrounded by the given delimiters.

fn or<P>(self, other: P) -> Or<Self, P>

where Self: Sized, P: Parser<I, O, Error = Self::Error>,

Parse one thing or, on failure, another thing.

fn recover_with<S>(self, strategy: S) -> Recovery<Self, S>

where Self: Sized, S: Strategy<I, O, Self::Error>,

Apply a fallback recovery strategy to this parser should it fail.

fn or_not(self) -> OrNot<Self>

where Self: Sized,

Attempt to parse something, but only if it exists.

fn not(self) -> Not<Self, O>

where Self: Sized,

Parses a single token if, and only if, the pattern fails to parse.

fn repeated(self) -> Repeated<Self>

where Self: Sized,

Parse a pattern any number of times (including zero times).

fn separated_by<U, P>(self, other: P) -> SeparatedBy<Self, P, U>

where Self: Sized, P: Parser<I, U, Error = Self::Error>,

Parse a pattern, separated by another, any number of times.

fn rewind(self) -> Rewind<Self>

where Self: Sized,

Parse a pattern. Afterwards, the input stream will be rewound to its original state, as if parsing had not occurred.

fn boxed<'a>(self) -> BoxedParser<'a, I, O, Self::Error>

where Self: Sized + 'a,

Box the parser, yielding a parser that performs parsing through dynamic dispatch.

fn from_str<U>(self) -> Map<Self, fn(_: O) -> Result<U, U::Err>, O>

where Self: Sized, U: FromStr, O: AsRef<str>,

Attempt to convert the output of this parser into something else using Rust’s FromStr trait.

fn unwrapped<U, E>(self) -> Unwrapped<Self, E, <Self as Parser<I, O>>::Error>

where Self: Sized + Parser<I, Result<U, E>>, E: Debug,

For parsers that produce a Result as their output, unwrap the result (panicking if an Err is encountered).