Trait parser_compose::Parser

pub trait Parser<In> {
    type Out;

    // Required method
    fn try_parse(&self, ctx: ParserContext<In>) -> Res<In, Self::Out>;

    // Provided methods
    fn map<F, Mapped>(self, f: F) -> Map<Self, F>
       where Self: Sized,
             F: Fn(Self::Out) -> Mapped { ... }
    fn or<P>(self, next: P) -> Or<Self, P>
       where Self: Sized { ... }
    fn when<F>(self, predicate: F) -> Predicate<Self, F>
       where Self: Sized,
             F: Fn(Self::Out) -> bool { ... }
    fn fold<R, Op, Init, IV>(
        self,
        count: R,
        op: Op,
        init: Init
    ) -> Fold<Self, Op, Init>
       where R: RepetitionArgument,
             Init: Fn() -> IV,
             Op: Fn(IV, Self::Out) -> IV,
             Self: Sized { ... }
    fn repeats<R>(
        self,
        count: R
    ) -> Fold<Self, RepeatsOperation<Self::Out>, RepeatsInit>
       where Self: Sized,
             R: RepetitionArgument { ... }
    fn accumulate<R>(
        self,
        count: R
    ) -> Fold<Self, AccumulateOperation<Self::Out>, AccumulateInit<Self::Out>>
       where R: RepetitionArgument,
             Self: Sized { ... }
    fn input(self) -> Input<Self>
       where Self: Sized { ... }
    fn optional(self) -> Optional<Self>
       where Self: Sized { ... }
    fn peek(self) -> Peek<Self>
       where Self: Sized { ... }
    fn not(self) -> Not<Self>
       where Self: Sized { ... }
    fn and_then<F, U, E>(self, f: F) -> AndThen<Self, F>
       where Self: Sized,
             F: Fn(Self::Out) -> Result<U, E>,
             E: Error { ... }
    fn label(self, label: &'static str) -> Label<Self>
       where Self: Sized { ... }
}

A trait for parsers

A Parser accepts some input, tries to match/recognize it and either fails with a FailureLog or succeeds with a value.

Given a thing that implements Parser, calling one of the associated methods returns a new Parser that augments its functionality.

Required Associated Types

type Out

The type this parser outputs if successfull

Required Methods

fn try_parse(&self, ctx: ParserContext<In>) -> Res<In, Self::Out>

Recognizes a value from the input and returns the result

Reports an error if the input could not be matched.

Provided Methods

fn map<F, Mapped>(self, f: F) -> Map<Self, F>where Self: Sized, F: Fn(Self::Out) -> Mapped,

Returns a parser that applies the the function f to its output

use parser_compose::Parser;

let msg = "a";

let (value, _) = "a".map(|s| s.to_ascii_uppercase()).try_parse(msg.into()).unwrap();

assert_eq!(value, "A");

fn or<P>(self, next: P) -> Or<Self, P>where Self: Sized,

Returns a parser that calls the next parser if it failed to match its input.

If both parsers fail, the longest of the two FailureLogs is kept, the other is discarded.

use  parser_compose::Parser;

let msg = "a";

let (value, _) = "1".or("a").try_parse(msg.into()).unwrap();

assert_eq!(value, "a");

fn when<F>(self, predicate: F) -> Predicate<Self, F>where Self: Sized, F: Fn(Self::Out) -> bool,

Returns a parser that only succeeds if pred returns true when given the parser’s output

use parser_compose::{any_utf8_str,Parser};

let msg = "boo";

let (value, _) = any_utf8_str.when(|s| s == "b").try_parse(msg.into()).unwrap();

assert_eq!(value, "b");

fn fold<R, Op, Init, IV>( self, count: R, op: Op, init: Init ) -> Fold<Self, Op, Init>where R: RepetitionArgument, Init: Fn() -> IV, Op: Fn(IV, Self::Out) -> IV, Self: Sized,

Returns a parser that succeeds if it is able to match its input count times.

The funcion op is executed for each successful repetition. Its return value is used as an argument for its next invocation.

The function init determines what the argument to op will be the first time it is called.

.fold() is useful whenever you want invoke a parser multiple times and do something with the result of each invocation.

Here is a contrived example:

use parser_compose::{Parser, ParserContext, Res, utf8_str};
use std::str::FromStr;

fn digit(ctx: ParserContext<&str>) -> Res<&str, u8> {
    utf8_str(0x30..=0x39)
    .and_then(u8::from_str)
    .try_parse(ctx)
}

// We want to sum the digits in this string
let input = "8.8.2.4";

let sum_parser = (digit, ".".optional()).fold(4, |accum, curr| accum + curr.0, || 0u8);

let (sum, rest) = sum_parser.try_parse(input.into()).unwrap();

assert_eq!(sum , 22);
assert!(rest.input().is_empty());

fn repeats<R>( self, count: R ) -> Fold<Self, RepeatsOperation<Self::Out>, RepeatsInit>where Self: Sized, R: RepetitionArgument,

Returns a parser that succeeds if it is able to match its input count times, discarding any output along the way

use parser_compose::{Parser, utf8_str};

let valid_number = "123-456-7899";
let invalid_number = "123-3454-34";

let digit = utf8_str(0x30..=0x39);
let validator = (digit.repeats(3), "-", digit.repeats(3), "-", digit.repeats(4));

let (value, rest) = validator.try_parse(valid_number.into()).unwrap();
assert_eq!(value, ((), "-", (), "-", ()));
assert_eq!(rest.input(), "");

let res = validator.try_parse(invalid_number.into());
assert!(res.is_err());

fn accumulate<R>( self, count: R ) -> Fold<Self, AccumulateOperation<Self::Out>, AccumulateInit<Self::Out>>where R: RepetitionArgument, Self: Sized,

Returns a parser that succeeds if it is able to match its input count times, accumulating output into a Vec along the way.

use parser_compose::Parser;

let msg = "AAAA";
let (value, rest) = "A".accumulate(2..=3).try_parse(msg.into()).unwrap();

assert_eq!(value, vec!["A", "A", "A"]);
assert_eq!(rest.input(), "A");

fn input(self) -> Input<Self>where Self: Sized,

Returns a parser that outputs the slice of the input that was recognized.

Works very well with the .repeats() combinator as an alternative to .accumulate() if you want to avoid allocating a Vec.

Here is the same example from .accumulate(), this time using .input():

use parser_compose::Parser;

let msg = "AAAA";
let (value, rest) = "A".repeats(2..=3).input().try_parse(msg.into()).unwrap();

assert_eq!(value, "AAA");
assert_eq!(rest.input(), "A");

fn optional(self) -> Optional<Self>where Self: Sized,

Returns a parser always succeeds but wraps the output in an Option. If the original parser would have failed, the parser outputs a None.

use parser_compose::Parser;

let msg = "a";

let ((b, a), _) = ("b".optional(), "a").try_parse(msg.into()).unwrap();

assert_eq!(b, None);
assert_eq!(a, "a");

fn peek(self) -> Peek<Self>where Self: Sized,

Returns a parser that never consumes any input regardless of its outcome. It can be used to look ahead.

use parser_compose::Parser;

// Recognize the sequence "a" followed by "b", but only if it is followed by a "c"
let a_then_b = ("a", "b", "c".peek());

let (value, rest) = a_then_b.try_parse("abc".into()).unwrap();
// The peeked output is still returned, but is not consumed
assert_eq!(value, ("a", "b", "c"));
assert_eq!(rest.input(), "c");

let result = a_then_b.try_parse("abb".into());
assert!(result.is_err());

fn not(self) -> Not<Self>where Self: Sized,

Returns a parser that succeeds if it was not able to recognize its input and fails if it was able to. It never consumes any input

use parser_compose::Parser;

// This parser matches "foo", but only if it is not followed by  "bar"
let parser = ("foo", "bar".not());

let msg = "foobar";

let result = parser.try_parse(msg.into());

assert!(result.is_err());

let (value, rest) = parser.try_parse("foobaz".into()).unwrap();

assert_eq!(value, ("foo", ()));
assert_eq!(rest.input(), "baz");

fn and_then<F, U, E>(self, f: F) -> AndThen<Self, F>where Self: Sized, F: Fn(Self::Out) -> Result<U, E>, E: Error,

Returns a parser that applies a falible function f to its output. The parser will report whatever error f fails with.

use parser_compose::{Parser};

let msg = [98].as_slice();

let (value, _) = [98].and_then(|b| {
    // converting to utf8 can fail
    std::str::from_utf8(b)
}).try_parse(msg.into()).unwrap();

assert_eq!("b", value);

fn label(self, label: &'static str) -> Label<Self>where Self: Sized,

Returns an identical parser that uses label when reporting errors to the FailureLog

use parser_compose::{Parser, utf8_str};

let digit = utf8_str(0x30..=0x39).label("digit");

let msg = "1234.";

let result = digit.repeats(5).try_parse(msg.into());
assert!(result.is_err());

let mut failure_log = result.unwrap_err();
let failure = failure_log.pop().unwrap();
assert_eq!(failure.to_string(), "expected digit at position 4");

Implementations on Foreign Types

impl<'input, 'pat> Parser<&'input str> for &'pat str

The Parser trait is implemented for string slices, which means all &strs will have the try_parse() method. Calling it will try to do a prefix match of the input with the &str used as the pattern.

use parser_compose::Parser;

let msg = "HELLO";

let (value, rest) = "HE".try_parse(msg.into()).unwrap();

assert_eq!(value, "HE");
assert_eq!(rest.input(), "LLO");

type Out = &'pat str

fn try_parse( &self, ctx: ParserContext<&'input str> ) -> Res<&'input str, Self::Out>

impl<'p, 'i, T> Parser<&'i [T]> for &'p [T]where T: PartialEq + Debug,

The Parser trait is implemented for all slices, which means all &[T] will have the try_parse() method. Calling it will try to do a prefix match of the input with the slice used as the pattern.

use parser_compose::Parser;

let msg = &['H', 'E', 'L', 'L', 'O'][..];

let (res, rest) = ['H', 'E'].as_slice().try_parse(msg.into()).unwrap();


assert_eq!(res, &['H', 'E'][..]);
assert_eq!(rest.input(), &['L', 'L', 'O'][..]);

type Out = &'p [T]

fn try_parse(&self, ctx: ParserContext<&'i [T]>) -> Res<&'i [T], Self::Out>

impl<In, P0, O0> Parser<In> for (P0,)where P0: Parser<In, Out = O0>,

A tuple of parsers is treated as a parser that tries its inner parsers in turn, feeding the leftover input from the first as the input to the other and so on

Calling the .try_parse() on the tuple returns a new tuple containing the extracted values.

This is implemented for tuples up to 12 items long

type Out = (O0,)

fn try_parse(&self, ctx: ParserContext<In>) -> Res<In, (O0,)>

impl<In, P0, O0, P1, O1> Parser<In> for (P0, P1)where P0: Parser<In, Out = O0>, P1: Parser<In, Out = O1>,

A tuple of parsers is treated as a parser that tries its inner parsers in turn, feeding the leftover input from the first as the input to the other and so on

Calling the .try_parse() on the tuple returns a new tuple containing the extracted values.

This is implemented for tuples up to 12 items long

type Out = (O0, O1)

fn try_parse(&self, ctx: ParserContext<In>) -> Res<In, (O0, O1)>

impl<In, P0, O0, P1, O1, P2, O2> Parser<In> for (P0, P1, P2)where P0: Parser<In, Out = O0>, P1: Parser<In, Out = O1>, P2: Parser<In, Out = O2>,

A tuple of parsers is treated as a parser that tries its inner parsers in turn, feeding the leftover input from the first as the input to the other and so on

Calling the .try_parse() on the tuple returns a new tuple containing the extracted values.

This is implemented for tuples up to 12 items long

type Out = (O0, O1, O2)

fn try_parse(&self, ctx: ParserContext<In>) -> Res<In, (O0, O1, O2)>

impl<In, P0, O0, P1, O1, P2, O2, P3, O3> Parser<In> for (P0, P1, P2, P3)where P0: Parser<In, Out = O0>, P1: Parser<In, Out = O1>, P2: Parser<In, Out = O2>, P3: Parser<In, Out = O3>,

A tuple of parsers is treated as a parser that tries its inner parsers in turn, feeding the leftover input from the first as the input to the other and so on

Calling the .try_parse() on the tuple returns a new tuple containing the extracted values.

This is implemented for tuples up to 12 items long

type Out = (O0, O1, O2, O3)

fn try_parse(&self, ctx: ParserContext<In>) -> Res<In, (O0, O1, O2, O3)>

impl<In, P0, O0, P1, O1, P2, O2, P3, O3, P4, O4> Parser<In> for (P0, P1, P2, P3, P4)where P0: Parser<In, Out = O0>, P1: Parser<In, Out = O1>, P2: Parser<In, Out = O2>, P3: Parser<In, Out = O3>, P4: Parser<In, Out = O4>,

A tuple of parsers is treated as a parser that tries its inner parsers in turn, feeding the leftover input from the first as the input to the other and so on

Calling the .try_parse() on the tuple returns a new tuple containing the extracted values.

This is implemented for tuples up to 12 items long

type Out = (O0, O1, O2, O3, O4)

fn try_parse(&self, ctx: ParserContext<In>) -> Res<In, (O0, O1, O2, O3, O4)>

impl<In, P0, O0, P1, O1, P2, O2, P3, O3, P4, O4, P5, O5> Parser<In> for (P0, P1, P2, P3, P4, P5)where P0: Parser<In, Out = O0>, P1: Parser<In, Out = O1>, P2: Parser<In, Out = O2>, P3: Parser<In, Out = O3>, P4: Parser<In, Out = O4>, P5: Parser<In, Out = O5>,

A tuple of parsers is treated as a parser that tries its inner parsers in turn, feeding the leftover input from the first as the input to the other and so on

Calling the .try_parse() on the tuple returns a new tuple containing the extracted values.

This is implemented for tuples up to 12 items long

type Out = (O0, O1, O2, O3, O4, O5)

fn try_parse(&self, ctx: ParserContext<In>) -> Res<In, (O0, O1, O2, O3, O4, O5)>

impl<In, P0, O0, P1, O1, P2, O2, P3, O3, P4, O4, P5, O5, P6, O6> Parser<In> for (P0, P1, P2, P3, P4, P5, P6)where P0: Parser<In, Out = O0>, P1: Parser<In, Out = O1>, P2: Parser<In, Out = O2>, P3: Parser<In, Out = O3>, P4: Parser<In, Out = O4>, P5: Parser<In, Out = O5>, P6: Parser<In, Out = O6>,

A tuple of parsers is treated as a parser that tries its inner parsers in turn, feeding the leftover input from the first as the input to the other and so on

Calling the .try_parse() on the tuple returns a new tuple containing the extracted values.

This is implemented for tuples up to 12 items long

type Out = (O0, O1, O2, O3, O4, O5, O6)

fn try_parse( &self, ctx: ParserContext<In> ) -> Res<In, (O0, O1, O2, O3, O4, O5, O6)>

impl<In, P0, O0, P1, O1, P2, O2, P3, O3, P4, O4, P5, O5, P6, O6, P7, O7> Parser<In> for (P0, P1, P2, P3, P4, P5, P6, P7)where P0: Parser<In, Out = O0>, P1: Parser<In, Out = O1>, P2: Parser<In, Out = O2>, P3: Parser<In, Out = O3>, P4: Parser<In, Out = O4>, P5: Parser<In, Out = O5>, P6: Parser<In, Out = O6>, P7: Parser<In, Out = O7>,

A tuple of parsers is treated as a parser that tries its inner parsers in turn, feeding the leftover input from the first as the input to the other and so on

Calling the .try_parse() on the tuple returns a new tuple containing the extracted values.

This is implemented for tuples up to 12 items long

type Out = (O0, O1, O2, O3, O4, O5, O6, O7)

fn try_parse( &self, ctx: ParserContext<In> ) -> Res<In, (O0, O1, O2, O3, O4, O5, O6, O7)>

impl<In, P0, O0, P1, O1, P2, O2, P3, O3, P4, O4, P5, O5, P6, O6, P7, O7, P8, O8> Parser<In> for (P0, P1, P2, P3, P4, P5, P6, P7, P8)where P0: Parser<In, Out = O0>, P1: Parser<In, Out = O1>, P2: Parser<In, Out = O2>, P3: Parser<In, Out = O3>, P4: Parser<In, Out = O4>, P5: Parser<In, Out = O5>, P6: Parser<In, Out = O6>, P7: Parser<In, Out = O7>, P8: Parser<In, Out = O8>,

A tuple of parsers is treated as a parser that tries its inner parsers in turn, feeding the leftover input from the first as the input to the other and so on

Calling the .try_parse() on the tuple returns a new tuple containing the extracted values.

This is implemented for tuples up to 12 items long

type Out = (O0, O1, O2, O3, O4, O5, O6, O7, O8)

fn try_parse( &self, ctx: ParserContext<In> ) -> Res<In, (O0, O1, O2, O3, O4, O5, O6, O7, O8)>

impl<In, P0, O0, P1, O1, P2, O2, P3, O3, P4, O4, P5, O5, P6, O6, P7, O7, P8, O8, P9, O9> Parser<In> for (P0, P1, P2, P3, P4, P5, P6, P7, P8, P9)where P0: Parser<In, Out = O0>, P1: Parser<In, Out = O1>, P2: Parser<In, Out = O2>, P3: Parser<In, Out = O3>, P4: Parser<In, Out = O4>, P5: Parser<In, Out = O5>, P6: Parser<In, Out = O6>, P7: Parser<In, Out = O7>, P8: Parser<In, Out = O8>, P9: Parser<In, Out = O9>,

A tuple of parsers is treated as a parser that tries its inner parsers in turn, feeding the leftover input from the first as the input to the other and so on

Calling the .try_parse() on the tuple returns a new tuple containing the extracted values.

This is implemented for tuples up to 12 items long

type Out = (O0, O1, O2, O3, O4, O5, O6, O7, O8, O9)

fn try_parse( &self, ctx: ParserContext<In> ) -> Res<In, (O0, O1, O2, O3, O4, O5, O6, O7, O8, O9)>

impl<In, P0, O0, P1, O1, P2, O2, P3, O3, P4, O4, P5, O5, P6, O6, P7, O7, P8, O8, P9, O9, P10, O10> Parser<In> for (P0, P1, P2, P3, P4, P5, P6, P7, P8, P9, P10)where P0: Parser<In, Out = O0>, P1: Parser<In, Out = O1>, P2: Parser<In, Out = O2>, P3: Parser<In, Out = O3>, P4: Parser<In, Out = O4>, P5: Parser<In, Out = O5>, P6: Parser<In, Out = O6>, P7: Parser<In, Out = O7>, P8: Parser<In, Out = O8>, P9: Parser<In, Out = O9>, P10: Parser<In, Out = O10>,

A tuple of parsers is treated as a parser that tries its inner parsers in turn, feeding the leftover input from the first as the input to the other and so on

Calling the .try_parse() on the tuple returns a new tuple containing the extracted values.

This is implemented for tuples up to 12 items long

type Out = (O0, O1, O2, O3, O4, O5, O6, O7, O8, O9, O10)

fn try_parse( &self, ctx: ParserContext<In> ) -> Res<In, (O0, O1, O2, O3, O4, O5, O6, O7, O8, O9, O10)>

impl<In, P0, O0, P1, O1, P2, O2, P3, O3, P4, O4, P5, O5, P6, O6, P7, O7, P8, O8, P9, O9, P10, O10, P11, O11> Parser<In> for (P0, P1, P2, P3, P4, P5, P6, P7, P8, P9, P10, P11)where P0: Parser<In, Out = O0>, P1: Parser<In, Out = O1>, P2: Parser<In, Out = O2>, P3: Parser<In, Out = O3>, P4: Parser<In, Out = O4>, P5: Parser<In, Out = O5>, P6: Parser<In, Out = O6>, P7: Parser<In, Out = O7>, P8: Parser<In, Out = O8>, P9: Parser<In, Out = O9>, P10: Parser<In, Out = O10>, P11: Parser<In, Out = O11>,

A tuple of parsers is treated as a parser that tries its inner parsers in turn, feeding the leftover input from the first as the input to the other and so on

Calling the .try_parse() on the tuple returns a new tuple containing the extracted values.

This is implemented for tuples up to 12 items long

type Out = (O0, O1, O2, O3, O4, O5, O6, O7, O8, O9, O10, O11)

fn try_parse( &self, ctx: ParserContext<In> ) -> Res<In, (O0, O1, O2, O3, O4, O5, O6, O7, O8, O9, O10, O11)>

Implementors

impl<'i> Parser<&'i str> for Utf8Str

type Out = &'i str

impl<In, Out, E, P, F, U> Parser<In> for AndThen<P, F>where P: Parser<In, Out = Out>, F: Fn(P::Out) -> Result<U, E>, for<'a> E: Error + 'a,

type Out = U

impl<In, Out, F> Parser<In> for Fwhere F: Fn(ParserContext<In>) -> Res<In, Out>,

The Parser trait is automatically implemented for any function with the following signature:

Fn(ParserContext<In>) -> parser_compose::Res<In, Out>

See the trait documentation for more info about the type parameters.

type Out = Out

impl<In, Out, P1, P2> Parser<In> for Or<P1, P2>where P1: Parser<In, Out = Out>, P2: Parser<In, Out = Out>, In: Clone,

type Out = Out

impl<In, Out, P> Parser<In> for Optional<P>where In: Clone, P: Parser<In, Out = Out>,

type Out = Option<Out>

impl<In, Out, P> Parser<In> for Peek<P>where In: Clone, P: Parser<In, Out = Out>,

type Out = Out

impl<In, Out, P, F> Parser<In> for Predicate<P, F>where P: Parser<In, Out = Out>, F: Fn(Out) -> bool, Out: Clone,

type Out = Out

impl<In, Out, P, F, M> Parser<In> for Map<P, F>where P: Parser<In, Out = Out>, F: Fn(P::Out) -> M,

type Out = M

impl<In, Out, P, Operation, Init, Accum> Parser<In> for Fold<P, Operation, Init>where P: Parser<In, Out = Out>, Init: Fn() -> Accum, Operation: Fn(Accum, Out) -> Accum, In: Clone,

type Out = Accum