Trait Utils 

pub trait Utils<Stream, Context>: Sized + Parse<Stream, Context>
where
    Stream: Streaming,
{
    // Provided methods
    fn and_then<OtherParser, F>(self, f: F) -> AndThen<Self, F>
       where OtherParser: Parse<Stream, Context>,
             F: Fn(Self::Token) -> OtherParser { ... }
    fn and<OtherParser, OtherToken>(
        self,
        other: OtherParser,
    ) -> And<Self, OtherParser>
       where OtherParser: Parse<Stream, Context, Token = OtherToken> { ... }
    fn and_drop<OtherParser, OtherToken>(
        self,
        other: OtherParser,
    ) -> AndDrop<Self, OtherParser>
       where OtherParser: Parse<Stream, Context, Token = OtherToken> { ... }
    fn drop_and<OtherParser, OtherToken>(
        self,
        other: OtherParser,
    ) -> DropAnd<Self, OtherParser>
       where OtherParser: Parse<Stream, Context, Token = OtherToken> { ... }
    fn drop(self) -> Drop<Self> { ... }
    fn fill<const N: usize>(self) -> Fill<Self, N>
       where Context: Contexting<UtilsAtom<Stream>> { ... }
    fn try_fold_iter<IntoIter, Init, Acc, Ret, F>(
        self,
        iter: IntoIter,
        init: Init,
        f: F,
    ) -> TryFoldIter<Self, IntoIter, Init, F>
       where Context: Contexting<UtilsAtom<Stream>>,
             IntoIter: IntoIterator + Clone,
             Init: Fn() -> Ret,
             F: Fn(Acc, Self::Token, IntoIter::Item) -> Ret,
             Ret: Try<Output = Acc>,
             Parsed<Acc, Stream, Context>: FromResidual<Ret::Residual> { ... }
    fn fold_until<TokenUntil, Acc, Until, Init, F>(
        self,
        until: Until,
        init: Init,
        f: F,
    ) -> FoldUntil<Self, Until, Init, F>
       where Context: Contexting<UtilsAtom<Stream>>,
             Until: Parse<Stream, Context, Token = TokenUntil>,
             Init: FnMut() -> Acc,
             F: FnMut(Acc, Self::Token) -> Acc { ... }
    fn try_fold_until<TokenUntil, Acc, Parser, Until, Init, Ret, F>(
        self,
        until: Until,
        init: Init,
        f: F,
    ) -> TryFoldUntil<Self, Until, Init, F>
       where Context: Contexting<UtilsAtom<Stream>>,
             Until: Parse<Stream, Context, Token = TokenUntil>,
             Init: Fn() -> Ret,
             F: Fn(Acc, Self::Token) -> Ret,
             Ret: Try<Output = Acc>,
             Parsed<(Acc, Until::Token), Stream, Context>: FromResidual<Ret::Residual> { ... }
    fn fold_bounds<Bounds, Acc, Init, F>(
        self,
        bounds: Bounds,
        init: Init,
        f: F,
    ) -> FoldBounds<Self, Bounds, Init, F>
       where Context: Contexting<UtilsAtom<Stream>>,
             Init: FnMut() -> Acc,
             F: FnMut(Acc, Self::Token) -> Acc,
             Bounds: FoldBoundsParse,
             Acc: Debug { ... }
    fn try_fold_bounds<Bounds, Acc, Init, Ret, F>(
        self,
        bounds: Bounds,
        init: Init,
        f: F,
    ) -> TryFoldBounds<Self, Bounds, Init, F>
       where Context: Contexting<UtilsAtom<Stream>>,
             Init: Fn() -> Ret,
             F: Fn(Acc, Self::Token) -> Ret,
             Ret: Try<Output = Acc>,
             Parsed<Acc, Stream, Context>: FromResidual<Ret::Residual>,
             Bounds: TryFoldBoundsParse,
             Acc: Debug { ... }
    fn add_atom<F, Atom>(self, f: F) -> AddAtom<Self, F>
       where F: Fn() -> Atom,
             Context: Contexting<Atom> { ... }
    fn map<F, OtherToken>(self, f: F) -> Map<Self, F>
       where F: Fn(Self::Token) -> OtherToken { ... }
    fn filter<F>(self, f: F) -> Filter<Self, F>
       where F: Fn(&Self::Token) -> bool,
             Context: Contexting<UtilsAtom<Stream>> { ... }
    fn filter_map<F, OtherToken>(self, f: F) -> FilterMap<Self, F>
       where F: Fn(Self::Token) -> Option<OtherToken>,
             OtherToken: Clone,
             Context: Contexting<UtilsAtom<Stream>> { ... }
    fn to<OtherToken>(self, t: OtherToken) -> To<Self, OtherToken>
       where OtherToken: Clone { ... }
    fn not(self) -> Not<Self>
       where Stream: Clone,
             Context: Contexting<NotAtom<Self::Token, Stream>> { ... }
    fn opt(self) -> Optional<Self>
       where Stream: Clone { ... }
    fn enumerate(self) -> Enumerate<Self> { ... }
    fn limit(self, n: usize) -> Limit<Self>
       where Context: Contexting<UtilsAtom<Stream>> { ... }
    fn or<OtherParser>(self, b: OtherParser) -> Or<Self, OtherParser>
       where Stream: Clone,
             OtherParser: Parse<Stream, Context>,
             Context: BitOr { ... }
    fn peek(self) -> Peek<Self>
       where Stream: Clone { ... }
    fn span(self) -> Span<Self>
       where Context: Contexting<UtilsAtom<Stream>> { ... }
    fn try_map<OtherToken, F, Ret>(self, f: F) -> TryMap<Self, F>
       where F: Fn(Self::Token) -> Ret,
             Ret: Try<Output = OtherToken>,
             Parsed<OtherToken, Stream, Context>: FromResidual<Ret::Residual> { ... }
}

Extend Parse trait with combinator

Combinator about branching: Utils::and, Utils::or.

Combinator about looping: Utils::fold_bounds (and rest of fold family), Utils::fill.

Combinator often used: Utils::opt, Utils::map, Utils::span.

Provided Methods

fn and_then<OtherParser, F>(self, f: F) -> AndThen<Self, F>

where OtherParser: Parse<Stream, Context>, F: Fn(Self::Token) -> OtherParser,

and_then will call the underline parser, if successful it will call the function in parameter and give it the produced Token. The function must return a new parser that will be called to producted the Token returned by and_then parser.

fn and<OtherParser, OtherToken>( self, other: OtherParser, ) -> And<Self, OtherParser>

where OtherParser: Parse<Stream, Context, Token = OtherToken>,

and combinator will call the underline parser, and if successful the parser given in parameter. If the second parser is also successful, and combinator will return a tuple that contain the two Token producted.

fn and_drop<OtherParser, OtherToken>( self, other: OtherParser, ) -> AndDrop<Self, OtherParser>

where OtherParser: Parse<Stream, Context, Token = OtherToken>,

Same than and combinator but it will drop the second Token instead, returning only the first Token from the inner parser.

fn drop_and<OtherParser, OtherToken>( self, other: OtherParser, ) -> DropAnd<Self, OtherParser>

where OtherParser: Parse<Stream, Context, Token = OtherToken>,

Same than and combinator but it will drop the underline Token instead, returning only the second Token from the parser in parameter.

fn drop(self) -> Drop<Self>

Call the underline parser but drop the Token if sucessful. This can be considered as a shortcut of the toilet closure: .map(|_| ()).

fn fill<const N: usize>(self) -> Fill<Self, N>

where Context: Contexting<UtilsAtom<Stream>>,

Will call the underline parser N times to fill an array of size N and return [Token; N] if successfull

fn try_fold_iter<IntoIter, Init, Acc, Ret, F>( self, iter: IntoIter, init: Init, f: F, ) -> TryFoldIter<Self, IntoIter, Init, F>

where Context: Contexting<UtilsAtom<Stream>>, IntoIter: IntoIterator + Clone, Init: Fn() -> Ret, F: Fn(Acc, Self::Token, IntoIter::Item) -> Ret, Ret: Try<Output = Acc>, Parsed<Acc, Stream, Context>: FromResidual<Ret::Residual>,

This combinator take a Iterator, it will call the inner parser as many time the iterator lenght. The Item produced and the Token produced will be given to the function F along with the accumulator produced by Init function. The Init and F function can use return any type that implement Try. The Token produced is the last accumulator value.

fn fold_until<TokenUntil, Acc, Until, Init, F>( self, until: Until, init: Init, f: F, ) -> FoldUntil<Self, Until, Init, F>

where Context: Contexting<UtilsAtom<Stream>>, Until: Parse<Stream, Context, Token = TokenUntil>, Init: FnMut() -> Acc, F: FnMut(Acc, Self::Token) -> Acc,

This Combinator will call the inner parser as long as the until parser is not successful, each Token produced will be feed to F function along with the accumulator.

The Token produced by fold_until is a tuple of the last value of the accumulator and the Token from until parser.

fn try_fold_until<TokenUntil, Acc, Parser, Until, Init, Ret, F>( self, until: Until, init: Init, f: F, ) -> TryFoldUntil<Self, Until, Init, F>

where Context: Contexting<UtilsAtom<Stream>>, Until: Parse<Stream, Context, Token = TokenUntil>, Init: Fn() -> Ret, F: Fn(Acc, Self::Token) -> Ret, Ret: Try<Output = Acc>, Parsed<(Acc, Until::Token), Stream, Context>: FromResidual<Ret::Residual>,

The same then fold_until but can be used with type that implement Try

fn fold_bounds<Bounds, Acc, Init, F>( self, bounds: Bounds, init: Init, f: F, ) -> FoldBounds<Self, Bounds, Init, F>

where Context: Contexting<UtilsAtom<Stream>>, Init: FnMut() -> Acc, F: FnMut(Acc, Self::Token) -> Acc, Bounds: FoldBoundsParse, Acc: Debug,

Main fold combinator, the bahavior depend on the Bounds argument. This combinator is implemented for Range and usize. The number of iteration depend of the type and the value used for the Bounds argument.

Type	Value	Min	Max
Range<usize>	2..4	2	4
RangeInclusive<usize>	2..=4	2	5
RangeFrom<usize>	4..	4	∞
RangeTo<usize>	..4	0	4
RangeToInclusive<usize>	..=4	0	5
RangeFull	..	0	∞
usize	4	4	4

If the minimun value is not respected, it will return an Failure. Then until the inner parser return a Failure or the maximun value is reach it will continue iterate. Then it will return a Success with the last value of the Accumulator This offer a great number of possibility for your parser with only one combinator.

fn try_fold_bounds<Bounds, Acc, Init, Ret, F>( self, bounds: Bounds, init: Init, f: F, ) -> TryFoldBounds<Self, Bounds, Init, F>

where Context: Contexting<UtilsAtom<Stream>>, Init: Fn() -> Ret, F: Fn(Acc, Self::Token) -> Ret, Ret: Try<Output = Acc>, Parsed<Acc, Stream, Context>: FromResidual<Ret::Residual>, Bounds: TryFoldBoundsParse, Acc: Debug,

Same than fold_bounds but F and Acc can return type that implement Try

fn add_atom<F, Atom>(self, f: F) -> AddAtom<Self, F>

where F: Fn() -> Atom, Context: Contexting<Atom>,

if the underline parser is not successful it will add call F and add the Atom provided to the Context

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

where F: Fn(Self::Token) -> OtherToken,

If the underline parser is successful it will call F with the Token produced and change return a new Success with the Token returned by F.

fn filter<F>(self, f: F) -> Filter<Self, F>

where F: Fn(&Self::Token) -> bool, Context: Contexting<UtilsAtom<Stream>>,

Only allow Success path if F return true

fn filter_map<F, OtherToken>(self, f: F) -> FilterMap<Self, F>

where F: Fn(Self::Token) -> Option<OtherToken>, OtherToken: Clone, Context: Contexting<UtilsAtom<Stream>>,

Merge of map and filter combinator, only return Success if F return Some.

fn to<OtherToken>(self, t: OtherToken) -> To<Self, OtherToken>

where OtherToken: Clone,

If underline parse is successful it will drop the Token and replace it with the token in argument. This is mostly a inconditional .map() usefull to avoid the closure. (Can be used in Slice parser where map is not)

fn not(self) -> Not<Self>

where Stream: Clone, Context: Contexting<NotAtom<Self::Token, Stream>>,

Evil Combinator, it will reverse Success in Failure and Failure in Success but will not touch Error. This Combinator should probably never be used.

fn opt(self) -> Optional<Self>

where Stream: Clone,

Make a parser optional allowing failure. Return Some(Token) in case of Success of underline parser and None in case of Failure. This parser can’t fail.

fn enumerate(self) -> Enumerate<Self>

Very much like Iterator .enumerate(). It will add a counter to every Token produced. Return a tuple (counter, Token).

fn limit(self, n: usize) -> Limit<Self>

where Context: Contexting<UtilsAtom<Stream>>,

Very much like Iterator .take(), it will only allow n call to inner parser before returning Failure. This parser use a state be aware that it must be recreate to be reset.

fn or<OtherParser>(self, b: OtherParser) -> Or<Self, OtherParser>

where Stream: Clone, OtherParser: Parse<Stream, Context>, Context: BitOr,

Allow branching, or will call the inner parser and if not sucessful it will call the second parser. or can be chained many time allowing multiple branch.

fn peek(self) -> Peek<Self>

where Stream: Clone,

peek allow to not consume the Stream but return the Token it would have produced. It should be used very often since you would parse more than once the same input.

fn span(self) -> Span<Self>

where Context: Contexting<UtilsAtom<Stream>>,

span allow to save the Stream consumed by the underline parser in a form of a Span. This is very usefull for error or to avoid fully tokenize an input. Be aware that Span can contains lifetime since it’s linked to Stream implementation. For example, an Stream of slice u8 will contains a lifetime.

fn try_map<OtherToken, F, Ret>(self, f: F) -> TryMap<Self, F>

where F: Fn(Self::Token) -> Ret, Ret: Try<Output = OtherToken>, Parsed<OtherToken, Stream, Context>: FromResidual<Ret::Residual>,

Same than .filter_map() but expect an Atom in case of Failure.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<T, Stream, Context> Utils<Stream, Context> for T

where Stream: Streaming, Self: Parse<Stream, Context>,