Trait nom_supreme::parser_ext::ParserExt

pub trait ParserExt<I, O, E>: Parser<I, O, E> + Sized {
#[must_use = "Parsers do nothing unless used"]    pub fn by_ref(&mut self) -> RefParser<'_, Self> { ... }
#[must_use = "Parsers do nothing unless used"]    pub fn all_consuming(self) -> AllConsuming<Self>
    where
        I: InputLength,
        E: ParseError<I>,
    { ... }
#[must_use = "Parsers do nothing unless used"]    pub fn complete(self) -> Complete<Self>
    where
        I: Clone,
        E: ParseError<I>,
    { ... }
#[must_use = "Parsers do nothing unless used"]    pub fn cut(self) -> Cut<Self> { ... }
#[must_use = "Parsers do nothing unless used"]    pub fn map_res<F, O2, E2>(self, func: F) -> MapRes<Self, F, O, E2>
    where
        F: FnMut(O) -> Result<O2, E2>,
        E: FromExternalError<I, E2>,
        I: Clone,
    { ... }
#[must_use = "Parsers do nothing unless used"]    pub fn opt(self) -> Optional<Self>
    where
        I: Clone,
    { ... }
#[must_use = "Parsers do nothing unless used"]    pub fn recognize(self) -> Recognize<Self, O>
    where
        I: Clone + Slice<RangeTo<usize>> + Offset,
    { ... }
#[must_use = "Parsers do nothing unless used"]    pub fn value<T: Clone>(self, value: T) -> Value<T, Self, O> { ... }
#[must_use = "Parsers do nothing unless used"]    pub fn verify<F>(self, verifier: F) -> Verify<Self, F>
    where
        F: Fn(&O) -> bool,
        I: Clone,
        E: ParseError<I>,
    { ... }
#[must_use = "Parsers do nothing unless used"]    pub fn context(self, context: &'static str) -> Context<Self>
    where
        E: ContextError<I>,
        I: Clone,
    { ... }
#[must_use = "Parsers do nothing unless used"]    pub fn terminated<F, O2>(self, terminator: F) -> Terminated<Self, F, O2>
    where
        F: Parser<I, O2, E>,
    { ... }
#[must_use = "Parsers do nothing unless used"]    pub fn precedes<F, O2>(self, successor: F) -> Preceded<F, Self, O>
    where
        F: Parser<I, O2, E>,
    { ... }
#[must_use = "Parsers do nothing unless used"]    pub fn preceded_by<F, O2>(self, prefix: F) -> Preceded<Self, F, O2>
    where
        F: Parser<I, O2, E>,
    { ... }
#[must_use = "Parsers do nothing unless used"]    pub fn delimited_by<D, O2>(self, delimiter: D) -> Delimited<Self, D, O2>
    where
        D: Parser<I, O2, E>,
    { ... }
#[must_use = "Parsers do nothing unless used"]    pub fn peek(self) -> Peek<Self>
    where
        I: Clone,
    { ... }
#[must_use = "Parsers do nothing unless used"]    pub fn not(self) -> Not<Self, O>
    where
        I: Clone,
        E: ParseError<I>,
    { ... }
#[must_use = "Parsers do nothing unless used"]    pub fn parse_from_str<'a, T>(self) -> FromStrParser<Self, T>
    where
        Self: Parser<&'a str, &'a str, E>,
        T: FromStr,
        E: FromExternalError<&'a str, T::Err>,
    { ... }
}

Additional postfix parser combinators, as a complement to Parser. Mostly these are postfix versions of the combinators in nom::combinator and nom::sequence, with some additional combinators original to nom-supreme.

Compatibility note: it is expected that eventually many of these postfix methods will eventually be added directly to the Parser trait. It will therefore not be considered a compatibility break to remove those methods from ParserExt, if they have the same name and signature.

Provided methods

#[must_use = "Parsers do nothing unless used"]pub fn by_ref(&mut self) -> RefParser<'_, Self>

Borrow a parser. This allows building parser combinators while still retaining ownership of the original parser. This is necessary because impl<T: Parser> Parser for &mut T is impossible due to conflicts with impl<T: FnMut> Parser for T.

Example

use nom_supreme::parser_ext::ParserExt;
use nom_supreme::tag::complete::tag;

let mut parser = tag("Hello");

let mut subparser = parser.by_ref().terminated(tag(", World"));

assert_eq!(subparser.parse("Hello, World!"), Ok(("!", "Hello")));
assert_eq!(
    subparser.parse("Hello"),
    Err(Err::Error(Error{input: "", code: ErrorKind::Tag}))
);

// We still have ownership of the original parser

assert_eq!(parser.parse("Hello, World!"), Ok((", World!", "Hello")));
assert_eq!(parser.parse("Hello"), Ok(("", "Hello")));

#[must_use = "Parsers do nothing unless used"]pub fn all_consuming(self) -> AllConsuming<Self> where
    I: InputLength,
    E: ParseError<I>, 

Create a parser that must consume all of the input, or else return an error.

Example

use nom_supreme::parser_ext::ParserExt;
use nom_supreme::tag::complete::tag;

let mut parser = tag("Hello").all_consuming();

assert_eq!(parser.parse("Hello"), Ok(("", "Hello")));
assert_eq!(
    parser.parse("World"),
    Err(Err::Error(Error{input: "World", code: ErrorKind::Tag}))
);
assert_eq!(
    parser.parse("Hello World"),
    Err(Err::Error(Error{input: " World", code: ErrorKind::Eof}))
);

#[must_use = "Parsers do nothing unless used"]pub fn complete(self) -> Complete<Self> where
    I: Clone,
    E: ParseError<I>, 

Create a parser that transforms Incomplete into Error.

Example

use nom_supreme::parser_ext::ParserExt;
use nom_supreme::tag::streaming::tag;

let mut parser = tag("Hello").complete();

assert_eq!(parser.parse("Hello"), Ok(("", "Hello")));
assert_eq!(
    parser.parse("World"),
    Err(Err::Error(Error{input: "World", code: ErrorKind::Tag}))
);
assert_eq!(
    parser.parse("Hel"),
    Err(Err::Error(Error{input: "Hel", code: ErrorKind::Complete}))
);

#[must_use = "Parsers do nothing unless used"]pub fn cut(self) -> Cut<Self>

Create a parser that transforms Error into Failure. This will end the parse immediately, even if there are other branches that could occur.

Example

use nom_supreme::parser_ext::ParserExt;
use nom_supreme::tag::complete::tag;

let mut parser = tag("Hello").cut();

assert_eq!(parser.parse("Hello"), Ok(("", "Hello")));
assert_eq!(
    parser.parse("World"),
    Err(Err::Failure(Error{input: "World", code: ErrorKind::Tag}))
);

#[must_use = "Parsers do nothing unless used"]pub fn map_res<F, O2, E2>(self, func: F) -> MapRes<Self, F, O, E2> where
    F: FnMut(O) -> Result<O2, E2>,
    E: FromExternalError<I, E2>,
    I: Clone, 

Create a parser that applies a mapping function func to the output of the subparser. Any errors from func will be transformed into parse errors via FromExternalError.

Example

use nom::character::complete::alphanumeric1;
use nom_supreme::parser_ext::ParserExt;

let mut parser = alphanumeric1.map_res(|s: &str| s.parse());

assert_eq!(parser.parse("10 abc"), Ok((" abc", 10)));
assert_eq!(
    parser.parse("<===>"),
    Err(Err::Error(Error{input: "<===>", code: ErrorKind::AlphaNumeric})),
);
assert_eq!(
    parser.parse("abc abc"),
    Err(Err::Error(Error{input: "abc abc", code: ErrorKind::MapRes})),
);

#[must_use = "Parsers do nothing unless used"]pub fn opt(self) -> Optional<Self> where
    I: Clone, 

Make this parser optional; if it fails to parse, instead it returns None with the input in the original position.

Example

use nom_supreme::parser_ext::ParserExt;
use nom_supreme::tag::complete::tag;

fn parser(input: &str) -> IResult<&str, Option<&str>> {
    tag("Hello").opt().parse(input)
}

assert_eq!(parser.parse("Hello, World"), Ok((", World", Some("Hello"))));
assert_eq!(parser.parse("World"), Ok(("World", None)));

let mut parser = tag("Hello").cut().opt();
assert_eq!(
    parser.parse("World"),
    Err(Err::Failure(Error{input: "World", code: ErrorKind::Tag}))
)

#[must_use = "Parsers do nothing unless used"]pub fn recognize(self) -> Recognize<Self, O> where
    I: Clone + Slice<RangeTo<usize>> + Offset, 

Replace this parser's output with the entire input that was consumed by the parser.

Example

use nom::character::complete::space1;
use nom_supreme::parser_ext::ParserExt;
use nom_supreme::tag::complete::tag;

let mut parser = tag("Hello").delimited_by(space1).recognize();

assert_eq!(parser.parse("   Hello   World!"), Ok(("World!", "   Hello   ")));
assert_eq!(
    parser.parse("Hello"),
    Err(Err::Error(Error{input: "Hello", code: ErrorKind::Space}))
)

#[must_use = "Parsers do nothing unless used"]pub fn value<T: Clone>(self, value: T) -> Value<T, Self, O>

Replace this parser's output with a clone of value every time it finishes successfully.

Example

use nom::branch::alt;
use nom_supreme::parser_ext::ParserExt;
use nom_supreme::tag::complete::tag;
use nom_supreme::error::{ErrorTree, BaseErrorKind, Expectation};


let mut parser = alt((
    tag("true").value(true),
    tag("false").value(false),
));

assert_eq!(parser.parse("true abc").unwrap(), (" abc", true));
assert_eq!(parser.parse("false abc").unwrap(), (" abc", false));

// ErrorTree gives much better error reports for alt and tag.
let err = parser.parse("null").unwrap_err();
let choices = match err {
    Err::Error(ErrorTree::Alt(choices)) => choices,
    _ => panic!("Unexpected error {:?}", err)
};
assert!(matches!(
    choices.as_slice(),
    [
        ErrorTree::Base {
            kind: BaseErrorKind::Expected(Expectation::Tag("true")),
            location: "null",
        },
        ErrorTree::Base {
            kind: BaseErrorKind::Expected(Expectation::Tag("false")),
            location: "null",
        },
    ]
))

#[must_use = "Parsers do nothing unless used"]pub fn verify<F>(self, verifier: F) -> Verify<Self, F> where
    F: Fn(&O) -> bool,
    I: Clone,
    E: ParseError<I>, 

Require the output of this parser to pass a verifier function, or else return a parse error.

use nom::character::complete::alpha1;
use nom_supreme::parser_ext::ParserExt;

let mut parser = alpha1.verify(|s: &&str| s.len() == 5);

assert_eq!(parser.parse("Hello"), Ok(("", "Hello")));
assert_eq!(parser.parse("Hello, World"), Ok((", World", "Hello")));
assert_eq!(
    parser.parse("abc"),
    Err(Err::Error(Error{input: "abc", code: ErrorKind::Verify}))
);
assert_eq!(
    parser.parse("abcabcabc"),
    Err(Err::Error(Error{input: "abcabcabc", code: ErrorKind::Verify}))
);
assert_eq!(
    parser.parse("123"),
    Err(Err::Error(Error{input: "123", code: ErrorKind::Alpha}))
);

#[must_use = "Parsers do nothing unless used"]pub fn context(self, context: &'static str) -> Context<Self> where
    E: ContextError<I>,
    I: Clone, 

Add some context to the parser. This context will be added to any errors that are returned from the parser via ContextError.

Example

use nom::sequence::separated_pair;
use nom::character::complete::space1;
use nom_supreme::parser_ext::ParserExt;
use nom_supreme::tag::complete::tag;

let mut parser = separated_pair(
    tag("Hello").context("hello"),
    space1,
    tag("World").context("world"),
)
.context("hello world");

assert_eq!(parser.parse("Hello World"), Ok(("", ("Hello", "World"))));
assert_eq!(
    parser.parse("Hel"),
    Err(Err::Error(VerboseError {errors: vec![
        ("Hel", VerboseErrorKind::Nom(ErrorKind::Tag)),
        ("Hel", VerboseErrorKind::Context("hello")),
        ("Hel", VerboseErrorKind::Context("hello world")),
    ]}))
);
assert_eq!(
    parser.parse("Hello"),
    Err(Err::Error(VerboseError {errors: vec![
        ("", VerboseErrorKind::Nom(ErrorKind::Space)),
        ("Hello", VerboseErrorKind::Context("hello world")),
    ]}))
);
assert_eq!(
    parser.parse("Hello Wor"),
    Err(Err::Error(VerboseError {errors: vec![
        ("Wor", VerboseErrorKind::Nom(ErrorKind::Tag)),
        ("Wor", VerboseErrorKind::Context("world")),
        ("Hello Wor", VerboseErrorKind::Context("hello world")),
    ]}))
);

#[must_use = "Parsers do nothing unless used"]pub fn terminated<F, O2>(self, terminator: F) -> Terminated<Self, F, O2> where
    F: Parser<I, O2, E>, 

Add a terminator parser. The terminator will run after this parser, returning any errors, but its output will otherwise be discarded.

Example

use nom_supreme::parser_ext::ParserExt;
use nom_supreme::tag::complete::tag;

let mut parser = tag("Hello").terminated(tag(" World"));

assert_eq!(parser.parse("Hello World!"), Ok(("!", "Hello")));
assert_eq!(
    parser.parse("Hello"),
    Err(Err::Error(Error{input: "", code: ErrorKind::Tag}))
);

#[must_use = "Parsers do nothing unless used"]pub fn precedes<F, O2>(self, successor: F) -> Preceded<F, Self, O> where
    F: Parser<I, O2, E>, 

Make this parser precede another one. The successor parser will run after this one succeeds, and the successor's output will be returned.

Example

use nom::character::complete::digit1;
use nom_supreme::parser_ext::ParserExt;
use nom_supreme::tag::complete::tag;

let mut parser = tag("Value: ").precedes(digit1);

assert_eq!(parser.parse("Value: 25;"), Ok((";", "25")));
assert_eq!(
    parser.parse("Value: "),
    Err(Err::Error(Error{input: "", code: ErrorKind::Digit}))
);
assert_eq!(
    parser.parse("25"),
    Err(Err::Error(Error{input: "25", code: ErrorKind::Tag}))
);

#[must_use = "Parsers do nothing unless used"]pub fn preceded_by<F, O2>(self, prefix: F) -> Preceded<Self, F, O2> where
    F: Parser<I, O2, E>, 

Make this parser preceded by another one. The prefix will run first, and if it succeeds, its output will be discard and this parser will be run.

Example

use nom::character::complete::digit1;
use nom_supreme::parser_ext::ParserExt;
use nom_supreme::tag::complete::tag;

let mut parser = digit1.preceded_by(tag("Value: "));

assert_eq!(parser.parse("Value: 25;"), Ok((";", "25")));
assert_eq!(
    parser.parse("Value: "),
    Err(Err::Error(Error{input: "", code: ErrorKind::Digit}))
);
assert_eq!(
    parser.parse("25"),
    Err(Err::Error(Error{input: "25", code: ErrorKind::Tag}))
);

#[must_use = "Parsers do nothing unless used"]pub fn delimited_by<D, O2>(self, delimiter: D) -> Delimited<Self, D, O2> where
    D: Parser<I, O2, E>, 

Make this parser delimited, requiring a delimiter as both a prefix and a suffix. The output of the delimiters is discarded.

Example

use nom::character::complete::{char, digit1};
use nom_supreme::parser_ext::ParserExt;

let mut parser = digit1.delimited_by(char('\''));

assert_eq!(parser.parse("'123' '456'"), Ok((" '456'", "123")));
assert_eq!(
    parser.parse("'' ''"),
    Err(Err::Error(Error{input: "' ''", code: ErrorKind::Digit}))
);
assert_eq!(
    parser.parse("'123 '"),
    Err(Err::Error(Error{input: " '", code: ErrorKind::Char}))
);

#[must_use = "Parsers do nothing unless used"]pub fn peek(self) -> Peek<Self> where
    I: Clone, 

Make this parser peeking: it runs normally but consumes no input.

Example

use nom_supreme::parser_ext::ParserExt;
use nom_supreme::tag::complete::tag;

let mut parser = tag("Hello").peek();

assert_eq!(parser.parse("Hello World"), Ok(("Hello World", "Hello")));
assert_eq!(
    parser.parse("World"),
    Err(Err::Error(Error{input: "World", code: ErrorKind::Tag}))
);

#[must_use = "Parsers do nothing unless used"]pub fn not(self) -> Not<Self, O> where
    I: Clone,
    E: ParseError<I>, 

Make this parser a negative lookahead: it will succeed if the subparser fails, and fail if the subparser succeeds.

Example

use nom_supreme::parser_ext::ParserExt;
use nom_supreme::tag::complete::tag;

let mut parser = tag("Hello").not();

assert_eq!(parser.parse("World"), Ok(("World", ())));
assert_eq!(
    parser.parse("Hello World"),
    Err(Err::Error(Error{input: "Hello World", code: ErrorKind::Not})),
);

#[must_use = "Parsers do nothing unless used"]pub fn parse_from_str<'a, T>(self) -> FromStrParser<Self, T> where
    Self: Parser<&'a str, &'a str, E>,
    T: FromStr,
    E: FromExternalError<&'a str, T::Err>, 

Create a parser that parses something via FromStr, using this parser as a recognizer for the string to pass to from_str.

Example

use nom::character::complete::digit1;
use nom_supreme::parser_ext::ParserExt;

let mut parser = digit1.parse_from_str();

assert_eq!(parser.parse("123 abc"), Ok((" abc", 123)));
assert_eq!(
    parser.parse("abc"),
    Err(Err::Error(Error{input: "abc", code: ErrorKind::Digit})),
);

Loading content...

Implementors

impl<I, O, E, P> ParserExt<I, O, E> for P where
    P: Parser<I, O, E>, 

Loading content...