Struct Parser

pub struct Parser<F, I>(/* private fields */);

This type is the one all functionality is built on.

The F type argument is the parser implementation, which is usually a function or a combinator from combinators.

The I type argument is the expected input. If you write parsers, it is advised to make your parser generic over the input, to allow different levels of tracking it, unless the parser makes use of the type directly.

Notes

All repeating combinators simply stop consuming the input if the given range is exceeded (should one be given). The behaviour, should that range be empty or from high to low, is, while not undefined, implementation defined and should not be relied upon.

Those repeating combinators are (note that the syntactic sugar variant always uses Vec:

combinator	has separator	has range	returns outputs	returns count	syntactic sugar
counted_separated	yes	yes	yes	yes	none
separated	yes	yes	yes	no	/ sep * new_collection * range
const_separated	yes	one number	yes	no	none
count_separated_within	yes	yes	no	yes	none
count_separated	yes	no	no	yes	none
counted_repeat	no	yes	yes	yes	none
repeat	no	yes	yes	no	* new_collection * range
const_repeat	no	one number	yes	no	none
count_within	no	yes	no	yes	none
count	no	no	no	yes	none

Combinators not found as methods:

• epsilon or ε. Matches nothing, always succeeds.
• tag. Requires the input to start with the given subsequence/substring.
• fail_with. Always fails, generating the error using a closure.
• fail_with_const. Always fails, generating the error using Clone on the given argument.
• eof. Fails if the input isn’t empty.
• not. Fails if the given parser succeeds, and succeeds if the given parser fails.
• consume_one_where. Consumes the first element/character of the input, if it matches a given condition.
• consume_while. Consumes elements/characters of the input that match the given condition. Its given a range, which acts like the range given to other repeating combinators.
• record_while. Like consume_while, but returns the matched substring.
• take. Consumes the rest of the input, and returns the matched string.
• lookahead. Outputs the result of the given parser without consuming it.
• output. Outputs the output of the given function, or fails if the function returns Err.

Implementations

impl<F, I, O, E> Parser<F, I>

where F: Fn(I) -> Result<(I, O), E>,

pub fn new(func: F) -> Self

This function allows you to create a new parser. If you wrote your own type which implements ParserImpl, use Parser::new_generic.

impl<F, I, O, E> Parser<F, I>

where F: ParserImpl<I, Output = O, Error = E>,

pub fn new_generic(implementation: F) -> Self

This function allows you to create a new parser. It will not work with type inference for closures though, so use Parser::new for those.

This function only exists to make the type inference for closures work in new.

pub fn then<O2, F2>( self, next: Parser<F2, I>, ) -> Parser<impl ParserImpl<I, Output = (O, O2), Error = E>, I>

where F2: ParserImpl<I, Output = O2, Error = E>,

This returns a new parser, which applies this parser and the given one on the input in that order, returning a pair of outputs. The syntactic sugar is >>.

pub fn before<O2, F2>( self, main: Parser<F2, I>, ) -> Parser<impl ParserImpl<I, Output = O2, Error = E>, I>

where F2: ParserImpl<I, Output = O2, Error = E>,

See Parser::then, this parser returns only the result of the parser which was given as an argument. The syntactic sugar is >> together with -, see the top level documentation.

pub fn followed_by<F2>( self, next: Parser<F2, I>, ) -> Parser<impl ParserImpl<I, Output = O, Error = E>, I>

where F2: ParserImpl<I, Error = E>,

See Parser::then, this parser returns only the result of this parser. The syntactic sugar is >> together with -, see the top level documentation.

pub fn or<F2>( self, alt: Parser<F2, I>, ) -> Parser<impl ParserImpl<I, Output = O, Error = E>, I>

where F2: ParserImpl<I, Output = O, Error = E>, I: Clone, E: AltError<I>,

This returns a new parser, which tries to apply this parser, and, should this fail, attempts to apply the one given as an argument. Should that also fail, it’ll return an error. The syntactic sugar is |.

pub fn map_result<O2, F2>( self, f: F2, ) -> Parser<impl ParserImpl<I, Output = O2, Error = E>, I>

where F2: Fn(O) -> Result<O2, E>,

This returns a new parser, which maps the given function to the result of this parser. This function returns a Result, so it can lead to the returned parser failing even if this one didn’t. The syntactic sugar is >> together with the wrapper type MapResult.

If your function never fails, use map.

pub fn map<O2, F2>( self, f: F2, ) -> Parser<impl ParserImpl<I, Output = O2, Error = E>, I>

where F2: Fn(O) -> O2,

This returns a new parser, which maps the given function to the result of this parser. The returned parser fails if this one does, and doesn’t fail if this one doesn’t. The syntactic sugar is >>.

If you want to be able to induce failure, use map_result.

pub fn map_err<E2, F2>( self, f: F2, ) -> Parser<impl ParserImpl<I, Output = O, Error = E2>, I>

where F2: Fn(E) -> E2,

This returns a new parser, which maps the given function to the error of this parser, should it fail.

pub fn counted_separated<C, F2, R: RangeLike, CG>( self, range: R, by: Parser<F2, I>, collection_generator: CG, ) -> Parser<impl ParserImpl<I, Output = (C, usize), Error = E>, I>

where F2: ParserImpl<I, Error = E>, C: Collection<Item = O>, I: Clone, CG: Fn() -> C,

This returns a new parser, which collects a number of occurences which is in the given range in the Collection C, and returns this collection and the number of seen occurences in a pair.

Should this be impossible, it fails.

Please read the notes in the documentation for this type.

pub fn separated<C, F2, R: RangeLike, CG>( self, range: R, by: Parser<F2, I>, collection_generator: CG, ) -> Parser<impl ParserImpl<I, Output = C, Error = E>, I>

where F2: ParserImpl<I, Error = E>, C: Collection<Item = O>, I: Clone, CG: Fn() -> C,

This returns a new parser, which collects a number of occurences which is in the given range in the Collection C, and returns this collection.

Should this be impossible, it fails.

Please read the notes in the documentation for this type.

pub fn const_separated<C, F2, CG>( self, n: usize, by: Parser<F2, I>, collection_generator: CG, ) -> Parser<impl ParserImpl<I, Output = C, Error = E>, I>

where F2: ParserImpl<I, Error = E>, C: Collection<Item = O>, I: Clone, CG: Fn() -> C,

This returns a new parser, which collects a number of occurences which is equal to the given argument in the Collection C, and returns this collection.

Should this be impossible, it fails.

Please read the notes in the documentation for this type.

pub fn count_separated_within<R: RangeLike, F2>( self, range: R, by: Parser<F2, I>, ) -> Parser<impl ParserImpl<I, Output = usize, Error = E>, I>

where F2: ParserImpl<I, Error = E>, I: Clone,

This returns a new parser, which counts the number of occurences which has to be within the given range, and returns that number.

It only consumes the minimum of the amount of occurences there are and the upper bound, if there are less occurences than the lower bound, the returned parser fails.

Please read the notes in the documentation for this type.

pub fn count_separated<F2>( self, by: Parser<F2, I>, ) -> Parser<impl ParserImpl<I, Output = usize, Error = E>, I>

where F2: ParserImpl<I, Error = E>, I: Clone,

This returns a new parser, which counts the number of occurences, and returns that number.

Please read the notes in the documentation for this type.

pub fn counted_repeat<C, R: RangeLike, CG>( self, range: R, collection_generator: CG, ) -> Parser<impl ParserImpl<I, Output = (C, usize), Error = E>, I>

where C: Collection<Item = O>, I: Clone, CG: Fn() -> C,

counted_separated without a separator.

Please read the notes in the documentation for this type.

pub fn repeat<C, R: RangeLike, CG>( self, range: R, collection_generator: CG, ) -> Parser<impl ParserImpl<I, Output = C, Error = E>, I>

where C: Collection<Item = O>, I: Clone, CG: Fn() -> C,

separated without a separator.

Please read the notes in the documentation for this type.

pub fn const_repeat<C, CG>( self, n: usize, collection_generator: CG, ) -> Parser<impl ParserImpl<I, Output = C, Error = E>, I>

where C: Collection<Item = O>, I: Clone, CG: Fn() -> C,

const_separated without a separator.

Please read the notes in the documentation for this type.

pub fn count_within<R: RangeLike>( self, range: R, ) -> Parser<impl ParserImpl<I, Output = usize, Error = E>, I>

where I: Clone,

count_separated_within without a separator.

Please read the notes in the documentation for this type.

pub fn count(self) -> Parser<impl ParserImpl<I, Output = usize, Error = E>, I>

where I: Clone,

count_separated without a separator.

Please read the notes in the documentation for this type.

pub fn maybe( self, ) -> Parser<impl ParserImpl<I, Output = Option<O>, Error = E>, I>

where I: Clone,

This returns a parser which attempts using this parser, wrapping the result in Some. If this parser fails, None is returned and no input is consumed.

pub fn record( self, ) -> Parser<impl ParserImpl<I, Output = I::Output, Error = E>, I>

where I: Clone + Recordable,

This returns a parser which runs this parser, yielding the range of input that this parser consumed. It returns error should the inner parser fail.

Examples found in repository

examples/lisp.rs (line 86)

    fn float(i: ParserInput) -> ParserResult<f32> {
        (
            (
                -(cf::tag("-") | ())
                >> (
                    -cf::tag(".") >> -consume_digits(1..) >> cf::epsilon()
                    |
                    -consume_digits(1..) >> (
                        -cf::tag(".") >> -consume_digits(0..) >> -(cf::f(float_e) | ()) >> cf::epsilon()
                        |
                        -cf::f(float_e) >> cf::epsilon()
                    )
                )
            ).record()
            >> (|s: &str| s.parse::<f32>().unwrap())
        ).parse_partial(i)
    }

    fn int(i: ParserInput) -> ParserResult<i32> {
        (
            (
                -(cf::tag("-") | ())
                >> cf::consume_while(|&c: &char| c.is_digit(10), 1..)
            ).record()
            >> (|s: &str| s.parse::<i32>().unwrap())
        ).parse_partial(i)
    }

pub fn convert_err<E2>( self, ) -> Parser<impl ParserImpl<I, Output = O, Error = E2>, I>

where E2: From<E>,

This converts the error to another one using .into, should this parser fail.

pub fn map_range_and_out<O2, F2>( self, f: F2, ) -> Parser<impl ParserImpl<I, Output = O2, Error = E>, I>

where F2: Fn((&I, &I), O) -> O2, I: Clone,

This calls the given function with the input left before and after this parser was run, together with the result of running it. The output of the resulting parser is the output of that function.

pub fn map_parser<O2, F2, F3>( self, f: F2, ) -> Parser<impl ParserImpl<I, Output = O2, Error = E>, I>

where F2: Fn(O) -> Parser<F3, I>, F3: ParserImpl<I, Output = O2, Error = E>,

This runs a parser based on the output of this parser.

Note that the returned parser has to have a one type, you can achieve this (if your parser doesn’t just use the output for ranges or in closures) by defining those parsers as standalone functions.

pub fn borrowed<'a>( &'a self, ) -> Parser<impl ParserImpl<I, Output = O, Error = E> + 'a, I>

Borrows this parser, allowing it to be combined with other parsers without being moved.

pub fn parse_partial(&self, input: I) -> Result<(I, O), E>

Parses as far as it can parse. This is just a wrapper around ParserImpl::apply.

See that function for more documentation.

Examples found in repository

examples/lisp.rs (line 53)

fn parse_partial(i: ParserInput) -> ParserResult<Value> {
    fn string(i: ParserInput) -> ParserResult<String> {
        (
            -cf::tag("\"")
            >> cf::record_while(|&c: &char| c != '"', ..)
            >> -cf::tag("\"")
            >> ToOwned::to_owned
        ).parse_partial(i)
    }

    fn consume_digits<'a, R: cf::RangeLike>(range: R) -> cf::parser!(<ParserInput<'a>, (), ParserError<'a>>) {
        cf::consume_while(|&c: &char| c.is_digit(10), range)
    }

    fn float_e(i: ParserInput) -> ParserResult<()> {
        (
            -cf::tag("e")
            >> -(cf::tag("-") | ())
            >> -consume_digits(1..)
            >> cf::epsilon()
        ).parse_partial(i)
    }

    // NOTE: You could combine `float` and `int` to one parser that may return either, by capturing
    // wether or not an "e" or a dot occured, and choosing the right method based on that.
    // Actually, we already have the handy `Number` type below anyways.

    fn float(i: ParserInput) -> ParserResult<f32> {
        (
            (
                -(cf::tag("-") | ())
                >> (
                    -cf::tag(".") >> -consume_digits(1..) >> cf::epsilon()
                    |
                    -consume_digits(1..) >> (
                        -cf::tag(".") >> -consume_digits(0..) >> -(cf::f(float_e) | ()) >> cf::epsilon()
                        |
                        -cf::f(float_e) >> cf::epsilon()
                    )
                )
            ).record()
            >> (|s: &str| s.parse::<f32>().unwrap())
        ).parse_partial(i)
    }

    fn int(i: ParserInput) -> ParserResult<i32> {
        (
            (
                -(cf::tag("-") | ())
                >> cf::consume_while(|&c: &char| c.is_digit(10), 1..)
            ).record()
            >> (|s: &str| s.parse::<i32>().unwrap())
        ).parse_partial(i)
    }

    fn list(i: ParserInput) -> ParserResult<Vec<Value>> {
        (
            -cf::tag("(")
            >> cf::f(parse_partial) / sp::ws(1..) * Vec::new * ..
            >> -sp::ws(..)
            >> -cf::tag(")")
        ).parse_partial(i)
    }

    (
        -sp::ws(..)
        >> (
            cf::f(string) >> Value::Str
            | cf::f(float) >> Value::Float
            | cf::f(int) >> Value::Int
            | cf::f(list) >> Value::List
        )
    ).parse_partial(i)
}

pub fn parse(&self, input: I) -> Result<O, E>

where I: HasEof, E: EofError<I>,

Parses the whole input. Should this parser not consume it, an approriate error is returned.

Examples found in repository

examples/lisp.rs (line 122)

pub fn parse(i: &str) -> Result<Value, ParserError> {
    (cf::f(parse_partial) >> -sp::ws(..)).parse(ParserInput::new(i))
}

Trait Implementations

impl<F, I> BitOr<()> for Parser<F, I>

where F: ParserImpl<I>, I: Clone,

type Output = Parser<MapLeft<CountedSeparated<fn() -> Option<<F as ParserImpl<I>>::Output>, RangeInclusive<usize>, F, Epsilon<<F as ParserImpl<I>>::Error>>>, I>

The resulting type after applying the | operator.

fn bitor(self, _: ()) -> Self::Output

Performs the | operation.

impl<F1, F2, I> BitOr<Parser<F2, I>> for Parser<F1, I>

where F1: ParserImpl<I>, F2: ParserImpl<I, Output = F1::Output, Error = F1::Error>, I: Clone, F1::Error: AltError<I>,

type Output = Parser<Or<F1, F2>, I>

The resulting type after applying the | operator.

fn bitor(self, or: Parser<F2, I>) -> Self::Output

Performs the | operation.

impl<F1, F2, I> Div<Parser<F2, I>> for Parser<F1, I>

type Output = ElementSeparator<F1, F2, I>

The resulting type after applying the / operator.

fn div(self, separator: Parser<F2, I>) -> Self::Output

Performs the / operation.

impl<F, I, CG> Mul<CG> for Parser<F, I>

type Output = WithCollectionGenerator<Parser<F, I>, CG>

The resulting type after applying the * operator.

fn mul(self, cg: CG) -> Self::Output

Performs the * operation.

impl<F, I> Neg for Parser<F, I>

type Output = Ignored<F, I>

The resulting type after applying the - operator.

fn neg(self) -> Ignored<F, I>

Performs the unary - operation.

impl<F1, F2, I, O> Shr<F2> for Parser<F1, I>

where F1: ParserImpl<I>, F2: Fn(F1::Output) -> O,

type Output = Parser<Map<F1, F2>, I>

The resulting type after applying the >> operator.

fn shr(self, map: F2) -> Self::Output

Performs the >> operation.

impl<F1, F2, I> Shr<Ignored<F2, I>> for Parser<F1, I>

where F1: ParserImpl<I>, F2: ParserImpl<I, Error = F1::Error>,

type Output = Parser<MapLeft<Then<F1, F2>>, I>

The resulting type after applying the >> operator.

fn shr(self, next: Ignored<F2, I>) -> Self::Output

Performs the >> operation.

impl<F1, F2, I, O> Shr<MapResult<F2>> for Parser<F1, I>

where F1: ParserImpl<I>, F2: Fn(F1::Output) -> Result<O, F1::Error>,

type Output = Parser<MapResult<F1, F2>, I>

The resulting type after applying the >> operator.

fn shr(self, map: MapResult<F2>) -> Self::Output

Performs the >> operation.

impl<F1, F2, I> Shr<Parser<F2, I>> for Ignored<F1, I>

where F1: ParserImpl<I>, F2: ParserImpl<I, Error = F1::Error>,

type Output = Parser<MapRight<Then<F1, F2>>, I>

The resulting type after applying the >> operator.

fn shr(self, next: Parser<F2, I>) -> Self::Output

Performs the >> operation.

impl<F1, F2, I> Shr<Parser<F2, I>> for Parser<F1, I>

where F1: ParserImpl<I>, F2: ParserImpl<I, Error = F1::Error>,

type Output = Parser<Then<F1, F2>, I>

The resulting type after applying the >> operator.

fn shr(self, next: Parser<F2, I>) -> Self::Output

Performs the >> operation.