Struct yap::types::WithContext

pub struct WithContext<T, C> { /* private fields */ }

Embed some context with your Tokens implementation to access at any time. Use Tokens::with_context to produce this.

Implementations

impl<T, C> WithContext<T, C>

pub fn into_parts(self) -> (T, C)

Return the original tokens and context

pub fn context(&self) -> &C

Access the context

pub fn context_mut(&mut self) -> &mut C

Mutably access the context

Trait Implementations

impl<T, C> Tokens for WithContext<T, C>where T: Tokens,

type Item = <T as Tokens>::Item

The item returned from Tokens::next().

type Location = <T as Tokens>::Location

An object which can be used to reset the token stream to some position.

fn next(&mut self) -> Option<Self::Item>

Return the next token. This is also the basis of the Iterator implementation that’s returned when you call Tokens::as_iter(). By implementing it here, we can keep all of the methods provided by Iterator in a separate “namespace” to avoid confusion and potential name collisions.

fn location(&self) -> Self::Location

Return a “location” pointer. This can be passed to Tokens::set_location to set the tokens location back to the state at the time it was handed out. If the crate::TokenLocation trait is in scope, you can also call the crate::TokenLocation::offset() method on it to obtain the current offset.

fn set_location(&mut self, location: Self::Location)

Set the tokens to the location provided. See Tokens::location.

fn is_at_location(&self, location: &Self::Location) -> bool

Return true if the current cursor location matches the location given, or false otherwise.

fn parse<Out, Buf>(&mut self) -> Result<Out, <Out as FromStr>::Err>where Out: FromStr, Buf: FromIterator<Self::Item> + Deref<Target = str>,

Attempt to parse the remaining tokens into the first Out generic using str::parse(). The second generic type may be used to buffer tokens, and can be any type that implements FromIterator<Self::Item> + Deref<Target = str>.

fn as_iter(&mut self) -> TokensAsIter<'_, Self>

Return an iterator over our tokens. The Tokens trait already mirrors the Iterator interface by providing Tokens::Item and Tokens::next(), but we keep the Iterator separate to avoid collisions, and because some iterator methods don’t consume tokens as you might expect, and so must be used with care when parsing input.

fn into_iter(self) -> TokensIntoIter<Self>

Like Tokens::as_iter(), except it consumes self, which can be useful in some situations.

fn with_context<C>(self, context: C) -> WithContext<Self, C>

Attach some context to your tokens. The returned struct, WithContext, also implements Tokens, and so has can be used in much the same way. Since this consumes your tokens, it’s better suited to permanent context that you’d like throughout the parsing.

fn with_context_mut<C>(&mut self, context: C) -> WithContextMut<&mut Self, C>

Unlike Tokens::with_context, which consumes the tokens, this borrows them mutably, allowing it to be used when you only have a mutable reference to tokens (which is a common function signature to use), and making it better suited to attaching temporary contexts.

fn slice(&mut self, from: Self::Location, to: Self::Location) -> Slice<'_, Self>

Return a slice of tokens starting at the to location provided and ending just prior to the from location provided (ie equivalent to the range to..from).

fn offset(&self) -> usize

Return the current offset into the tokens that we’ve parsed up to so far. The exact meaning of this can vary by implementation; when parsing slices, it is index of the slice item we’ve consumed up to, and when parsing &str’s it is the number of bytes (not characters) consumed so far.

fn peek(&mut self) -> Option<Self::Item>

Return the next item in the input without consuming it.

fn take(&mut self, n: usize) -> Take<'_, Self>

Return a Tokens impl that will take the next n tokens from the input (ending early if the input runs early).

fn take_while<F>(&mut self, f: F) -> TakeWhile<'_, Self, F>where F: FnMut(&Self::Item) -> bool,

Return a Tokens impl that will consume tokens until the provided function returns false.

fn skip_while<F>(&mut self, f: F) -> usizewhere F: FnMut(&Self::Item) -> bool,

Iterate over the tokens until the provided function returns false on one. Only consume the tokens that the function returned true for, returning the number of tokens that were consumed/skipped. Equivalent to toks.take_while(f).count().

fn many<F, Output>(&mut self, parser: F) -> Many<'_, Self, F>where F: FnMut(&mut Self) -> Option<Output>,

Returns a Tokens impl that runs the provided parser again and again, returning an output from it each time until it returns None.

fn many_err<F, Output, E>(&mut self, parser: F) -> ManyErr<'_, Self, F>where F: FnMut(&mut Self) -> Result<Output, E>,

Returns a Tokens impl that runs the provided parser again and again, returning an output from it each time until it returns None. If the parser returns an error, no tokens will be consumed and the error will be returned as the final iteration.

fn skip_many<F>(&mut self, parser: F) -> usizewhere F: FnMut(&mut Self) -> bool,

Ignore 0 or more instances of some parser.

fn skip_many1<F, E, Ignored>(&mut self, parser: F) -> Result<usize, E>where F: FnMut(&mut Self) -> Result<Ignored, E>,

Ignore 1 or more instances of some parser. If the provided parser fails immediately, return the error that it produced.

fn sep_by<F, S, Output>( &mut self, parser: F, separator: S ) -> SepBy<'_, Self, F, S>where F: FnMut(&mut Self) -> Option<Output>, S: FnMut(&mut Self) -> bool,

Return a Tokens impl that parses anything matching the first parser function, and expects to parse something matching the second separator function between each of these.

fn sep_by_err<F, S, E, Output>( &mut self, parser: F, separator: S ) -> SepByErr<'_, Self, F, S>where F: FnMut(&mut Self) -> Result<Output, E>, S: FnMut(&mut Self) -> bool,

Return a Tokens impl that parses anything matching the parser function, and expects to parse something matching the separator function between each one. Unlike Tokens::sep_by, this accepts parsers that return Results, and returns the result on each iteration. Once an error is hit, None is returned thereafter.

fn sep_by_all<F, S, Output>( &mut self, parser: F, separator: S ) -> SepByAll<'_, Self, F, S, Output>where F: FnMut(&mut Self) -> Option<Output>, S: FnMut(&mut Self) -> Option<Output>,

Returns a Tokens impl that parses anything matching the parser function, and expects to parse something matching the separator function between each one. The Tokens impl hands back the output from both the parser and separator function, which means that they are both expected to return the same type.

fn sep_by_all_err<F, S, Output, E>( &mut self, parser: F, separator: S ) -> SepByAllErr<'_, Self, F, S, Output>where F: FnMut(&mut Self) -> Result<Output, E>, S: FnMut(&mut Self) -> Option<Output>,

Similar to Tokens::sep_by_all, except that the Tokens impl returned also hands back the first error encountered when attempting to run our parser.

fn surrounded_by<F, S, Output>(&mut self, parser: F, surrounding: S) -> Outputwhere F: FnOnce(&mut Self) -> Output, S: FnMut(&mut Self),

Parse some tokens that are optionally surrounded by the result of a surrounding parser.

fn optional<F, Output>(&mut self, f: F) -> Outputwhere F: FnOnce(&mut Self) -> Output, Output: IsMatch,

Attempt to parse some output from the tokens. Returning None or false signifies that no match was found, and no tokens will be consumed. Otherwise, we’ll return the match and consume the tokens.

fn optional_err<F, Output, Error>(&mut self, f: F) -> Result<Output, Error>where F: FnOnce(&mut Self) -> Result<Output, Error>,

Attempt to parse some output from the tokens, returning a Result. If the Result returned is Err, no tokens will be consumed.

fn eof(&mut self) -> bool

Checks next input is None and, if true, consumes the None.

fn consume(&mut self)

Consume all remaining tokens. This is expected to be used in conjunction with combinators likeTokens::take and Tokens::take_while. This is just a shorthand for toks.as_iter().for_each(drop).

fn collect<B: FromIterator<Self::Item>>(&mut self) -> B

Collect up all of the tokens into something that implements FromIterator. If you’d like to call str::parse on the subsequent collection, then prefer Tokens::parse, which can be more optimal in some cases.