Trait Parser

pub trait Parser<In: Input, Out, Reason = Infallible>: Sized + FnMut(In) -> ParsingResult<In, Out, Reason> {
    // Provided methods
    fn parse(&mut self, input: In) -> ParsingResult<In, Out, Reason> { ... }
    fn filter(self, f: impl FnMut(&Out) -> bool) -> impl Parser<In, Out, Reason> { ... }
    fn filter_fatal(
        self,
        reason: Reason,
        f: impl FnMut(&Out) -> bool,
    ) -> impl Parser<In, Out, Reason>
       where Reason: Clone { ... }
    fn map_reason<NewReason>(
        self,
        f: impl FnMut(Reason) -> NewReason,
    ) -> impl Parser<In, Out, NewReason> { ... }
    fn map<NewOut>(
        self,
        f: impl FnMut(Out) -> NewOut,
    ) -> impl Parser<In, NewOut, Reason> { ... }
    fn map_until<NewOut>(
        self,
        f: impl FnMut(Out) -> Option<NewOut>,
    ) -> impl Parser<In, NewOut, Reason> { ... }
    fn call<F>(self, f: F) -> impl Parser<In, F::Output, Reason>
       where F: FnMut<Out>,
             Out: Tuple { ... }
    fn or(
        self,
        parser: impl Parser<In, Out, Reason>,
    ) -> impl Parser<In, Out, Reason> { ... }
    fn or_nonempty(
        self,
        parser: impl Parser<In, Out, Reason>,
    ) -> impl Parser<In, Out, Reason> { ... }
    fn or_map_rest(
        self,
        f: impl FnMut(In) -> Out,
    ) -> impl Parser<In, Out, Reason> { ... }
    fn or_value(self, value: Out) -> impl Parser<In, Out, Reason>
       where Out: Clone { ... }
    fn and<Other>(
        self,
        parser: impl Parser<In, Other, Reason>,
    ) -> impl Parser<In, (Out, Other), Reason> { ... }
    fn and_value<Other: Clone>(
        self,
        value: Other,
    ) -> impl Parser<In, (Out, Other), Reason> { ... }
    fn add<New>(
        self,
        parser: impl Parser<In, New, Reason>,
    ) -> impl Parser<In, Out::Appended<New>, Reason>
       where Out: Tuple { ... }
    fn add_value<Other: Clone>(
        self,
        value: Other,
    ) -> impl Parser<In, Out::Appended<Other>, Reason>
       where Out: Tuple { ... }
    fn then<NewOut>(
        self,
        parser: impl Parser<In, NewOut, Reason>,
    ) -> impl Parser<In, NewOut, Reason> { ... }
    fn skip<Skipped>(
        self,
        parser: impl Parser<In, Skipped, Reason>,
    ) -> impl Parser<In, Out, Reason> { ... }
    fn expect<NewReason: Clone>(
        self,
        expected: NewReason,
    ) -> impl Parser<In, Out, NewReason> { ... }
    fn or_reason(self, reason: Reason) -> impl Parser<In, Out, Reason>
       where Reason: Clone { ... }
    fn or_reason_if_nonempty(
        self,
        reason: Reason,
    ) -> impl Parser<In, Out, Reason>
       where Reason: Clone { ... }
    fn get_span(self) -> impl Parser<In, (Out, In), Reason>
       where In: Input { ... }
    fn add_span(self) -> impl Parser<In, Out::Appended<In>, Reason>
       where Out: Tuple { ... }
    fn get_rest(self) -> impl Parser<In, (Out, In), Reason> { ... }
    fn add_rest(self) -> impl Parser<In, Out::Appended<In>, Reason>
       where Out: Tuple { ... }
    fn maybe(self) -> impl Parser<In, Option<Out>, Reason> { ... }
    fn ok(self) -> impl Parser<In, bool, Reason> { ... }
    fn repeat(self) -> impl Parser<In, (), Reason> { ... }
    fn dbg(self, label: impl Display) -> impl Parser<In, Out, Reason>
       where In: Input,
             Out: Debug,
             Reason: Debug { ... }
    fn iter(self, input: In) -> Iter<In, Out, Reason, Self>  { ... }
    fn with_full_error<'path>(
        self,
        path: impl PathLike<'path>,
        full_src: &str,
    ) -> impl FnOnce(In) -> Result<(In, Out), FullParsingError<'path, Reason>>
       where In: Input { ... }
}

The core of the crate, a trait representing a function that takes some input and returns either a tuple of (the rest of the input, the output) or a ParsingError.

Provided Methods

fn parse(&mut self, input: In) -> ParsingResult<In, Out, Reason>

Use the parser to produce the output.

fn filter(self, f: impl FnMut(&Out) -> bool) -> impl Parser<In, Out, Reason>

Turns output into a recoverable error if the output doesn’t meet a condition.

fn filter_fatal( self, reason: Reason, f: impl FnMut(&Out) -> bool, ) -> impl Parser<In, Out, Reason>

where Reason: Clone,

Like Parser::filter, but the possible error is instead fatal, with reason

fn map_reason<NewReason>( self, f: impl FnMut(Reason) -> NewReason, ) -> impl Parser<In, Out, NewReason>

Changes the error reason by passing it through f.

fn map<NewOut>( self, f: impl FnMut(Out) -> NewOut, ) -> impl Parser<In, NewOut, Reason>

Transforms the output of the parser, if present.

fn map_until<NewOut>( self, f: impl FnMut(Out) -> Option<NewOut>, ) -> impl Parser<In, NewOut, Reason>

Tranforms the output of the parser, if present, or try parsing the next value.

fn call<F>(self, f: F) -> impl Parser<In, F::Output, Reason>

where F: FnMut<Out>, Out: Tuple,

Available on crate feature nightly only.

Like Parser::map, but calls the provdied function using the Nightly FnMut::call_mut method, effectively spreading the output as the arguments of the function.

The following nIghtly Rust code:

use shrimple_parser::Parser;
parser.call(u32::pow)

is equivalent to the following stable Rust code:

use shrimple_parser::Parser;
parser.map(|(x, y)| u32::pow(x, y))

T for this method is constrained not by the crate::Tuple trait, but by the unstable standard trait core::marker::Tuple, which means that T can be a tuple of absolutely any length.

See also: crate::call, a macro for a stable alternative to this method.

fn or( self, parser: impl Parser<In, Out, Reason>, ) -> impl Parser<In, Out, Reason>

Replaces a recoverable error with the result of parser.

The input fed into the second parser is the rest of the input returned by the first parser.

Warning

Do not use this in combination with Parser::iter; Use Parser::or_nonempty

fn or_nonempty( self, parser: impl Parser<In, Out, Reason>, ) -> impl Parser<In, Out, Reason>

Like Parser::or, but keeps the error if the rest of the input is empty.

This allows to avoid slipping into an infinite loop, e.g. when using Parser::iter somewhere down the line.

fn or_map_rest(self, f: impl FnMut(In) -> Out) -> impl Parser<In, Out, Reason>

Replaces a recoverable error with the transformed remains of the input. If the rest of the input in the recoverable error is already empty, does nothing. The returned remains of the input are an empty string.

fn or_value(self, value: Out) -> impl Parser<In, Out, Reason>

where Out: Clone,

Replaces a recoverable error with value & the rest of the input in the recoverable error.

Be aware that value will be cloned every time it’s to be returned.

See Parser::or, Parser::or_nonempty, Parser::or_map_rest.

fn and<Other>( self, parser: impl Parser<In, Other, Reason>, ) -> impl Parser<In, (Out, Other), Reason>

Parses the rest of the input after the first parser, returning both outputs & short-circuiting on an error.

The reason for the errors of the first parser is adapted to the one of the second parser.

See also Parser::add, Parser::and_value.

fn and_value<Other: Clone>( self, value: Other, ) -> impl Parser<In, (Out, Other), Reason>

Adds a value to the output of the parser

Be aware that value will be cloned every time it’s to be returned.

See Parser::and.

fn add<New>( self, parser: impl Parser<In, New, Reason>, ) -> impl Parser<In, Out::Appended<New>, Reason>

where Out: Tuple,

Like Parser::and, but specific to parsers that output a tuple: the new output is appended to the tuple of other tuples using the Tuple trait.

fn add_value<Other: Clone>( self, value: Other, ) -> impl Parser<In, Out::Appended<Other>, Reason>

where Out: Tuple,

Like Parser::and_value, but specific to parsers that output a tuple: the new output is appended to the tuple of other tuples using the Tuple trait.

fn then<NewOut>( self, parser: impl Parser<In, NewOut, Reason>, ) -> impl Parser<In, NewOut, Reason>

Like Parser::and, but discards the output of the first parser. The reason for the errors of the first parser is adapted to the one of the second parser.

fn skip<Skipped>( self, parser: impl Parser<In, Skipped, Reason>, ) -> impl Parser<In, Out, Reason>

Same as Parser::and but discards the output and the recoverable error of the second parser.

Effectively, all this function does is advance the input to right after the second parser, if it succeeds, otherwise the input stays as if only the first parser was called.

fn expect<NewReason: Clone>( self, expected: NewReason, ) -> impl Parser<In, Out, NewReason>

Sets the reason for errors returned from the parser, making all errors fatal.

fn or_reason(self, reason: Reason) -> impl Parser<In, Out, Reason>

where Reason: Clone,

Makes a recoverable error fatal by giving it a reason. If the error is already fatal, nothing is changed

fn or_reason_if_nonempty(self, reason: Reason) -> impl Parser<In, Out, Reason>

where Reason: Clone,

Like Parser::or_reason but does nothing if the rest of the input is empty.

Be aware that reason is cloned every time it’s to be returned.

fn get_span(self) -> impl Parser<In, (Out, In), Reason>

where In: Input,

Adds the part of the input that was consumed by the parser to the outputs.

If the input increased in length after the parser (which should not happen), an empty string is added. See also Parser::add_span, which adds the span to the tuple of other outputs.

fn add_span(self) -> impl Parser<In, Out::Appended<In>, Reason>

where Out: Tuple,

Like Parser::get_span, but adds the output to the tuple of other outputs using the Tuple trait.

fn get_rest(self) -> impl Parser<In, (Out, In), Reason>

Adds a copy of rest of the input to the output.

fn add_rest(self) -> impl Parser<In, Out::Appended<In>, Reason>

where Out: Tuple,

Like Parser::get_rest, but adds the input to the tuple of other outputs using the Tuple trait.

fn maybe(self) -> impl Parser<In, Option<Out>, Reason>

Replaces a recoverable error with None, making the output optional.

fn ok(self) -> impl Parser<In, bool, Reason>

Replaces the output with true and a recoverable error with false

fn repeat(self) -> impl Parser<In, (), Reason>

Repeats the parser until a recoverable error is met, discarding all the output.

fn dbg(self, label: impl Display) -> impl Parser<In, Out, Reason>

where In: Input, Out: Debug, Reason: Debug,

Prints the output using its Debug implementation & the first 16 bytes of the rest of the input, all along with a custom provided message.

fn iter(self, input: In) -> Iter<In, Out, Reason, Self>

Turns the parser into an iterator that yields output until the first recoverable error. If an error is yielded from the iterator, it’s guaranteed to be fatal.

fn with_full_error<'path>( self, path: impl PathLike<'path>, full_src: &str, ) -> impl FnOnce(In) -> Result<(In, Out), FullParsingError<'path, Reason>>

where In: Input,

Aaugments the parsing error, if present, with location in the input. path is the reported path to the file where the error occured. Note that the input passed here is only used for error reporting, not as the input to the parser.

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<In, Out, Reason, F> Parser<In, Out, Reason> for F

where In: Input, F: FnMut(In) -> ParsingResult<In, Out, Reason>,