Crate abortable_parser

Expand description

An opinionated parser combinator library with a focus on fully abortable parsing and easy error handling.

The approach to macro composition is heavily inspired by nom. It focuses on a simple API for combinators, and easy error handling.

We have a number of macros that assist in the gneration or handling of each type of error.

§Simple parsing of a url.

#[macro_use]
extern crate abortable_parser;
use abortable_parser::iter::StrIter;
use abortable_parser::{Result, eoi, ascii_ws};

make_fn!(proto<StrIter, &str>,
    do_each!(
        proto => until!(text_token!("://")),
        _ => must!(text_token!("://")),
        (proto)
    )
);

make_fn!(domain<StrIter, &str>,
    do_each!(
        // domains do not start with a slash
        _ => peek!(not!(text_token!("/"))),
        domain => until!(either!(
            discard!(text_token!("/")),
            discard!(ascii_ws),
            eoi)),
        (domain)
    )
);

make_fn!(path<StrIter, &str>,
     until!(either!(discard!(ascii_ws), eoi))
);

make_fn!(full_url<StrIter, (Option<&str>, Option<&str>, Option<&str>)>,
    do_each!(
        protocol => proto,
        // If we match the protocol then we must have a domain.
        // This is an example of an unrecoverable parsing error so we
        // abort with the must! macro if it doesn't match.
        domain => must!(domain),
        path => optional!(path),
        (Some(protocol), Some(domain), path)
    )
);

make_fn!(relative_url<StrIter, (Option<&str>, Option<&str>, Option<&str>)>,
    do_each!(
        _ => not!(either!(text_token!("//"), proto)),
        // we require a valid path for relative urls.
        path => path,
        (None, None, Some(path))
    )
);

make_fn!(url<StrIter, (Option<&str>, Option<&str>, Option<&str>)>,
    either!(
        full_url,
        relative_url,
    )
);

let iter = StrIter::new("http://example.com/some/path ");
let result = url(iter);
assert!(result.is_complete());
if let Result::Complete(_, (proto, domain, path)) = result {
    assert!(proto.is_some());
    assert!(domain.is_some());
    if let Some(domain) = domain {
        assert_eq!(domain, "example.com");
    }
    assert!(path.is_some());
    if let Some(path) = path {
        assert_eq!(path, "/some/path");
    }
}

let bad_input = StrIter::new("http:///some/path");
let bad_result = url(bad_input);
assert!(bad_result.is_abort());

Re-exports§

pub use iter::SliceIter;
pub use iter::StrIter;
pub use combinators::*;

Modules§

combinators: Contains combinators that can assemble other matchers or combinators into more complex grammars.
iter: Contains implementations of InputIter.

Macros§

complete: Turns Result::Incomplete into Result::Fail.
consume_all: Consumes the input until the $rule fails and then returns the consumed input as a slice.
discard: Discards the output of a combinator rule when it completes and just returns (). Leaves Failures, Aborts, and Incompletes untouched.
do_each: Captures a sequence of sub parsers output.
either: Returns the output of the first sub parser to succeed.
input: Helper macro that returns the input without consuming it.
make_fn: Constructs a function named $name that takes an input of type $i and produces an output of type $o.
must: Turns Result::Fail into Result::Abort.
must_complete: Turns Result::Fail and Result::Incomplete into Result::Abort.
not: Turns a matcher into it’s inverse, only succeeding if the the matcher returns a Fail. Does not consume it’s input and only returns ().
optional: Treats a sub parser as optional. It returns Some(output) for a successful match and None for failures.
peek: Checks the given matcher without consuming the input.
repeat: Runs a single matcher repeating 0 or more times and returns a possibly empty vector of the parsed results.
run: Converts a function indentifier into a macro call. Useful when writing your own macro combinator.
separated: Parses separated list of items.
text_token: Convenience macro for looking for a specific text token in a byte input stream.
trap: Turns Result::Abort into Result::Fail allowing you to trap and then convert any Result::Abort into a normal Fail.
until: Consumes an input until it reaches a term that the contained rule matches. It does not consume the subrule.
with_err: Replaces the the sub error in a Fail case with one of your own errors.
wrap_err: Wraps any Error return from a subparser in another error. Stores the position at this point in the parse tree allowing you to associate context with wrapped errors.

Structs§

Error: The custom error type for use in Result::{Fail, Abort}. Stores a wrapped err that must implement Display as well as an offset and an optional cause.

Enums§

Result: The result of a parsing attempt.
SpanRange: SpanRange encompasses the valid Ops::Range types for use with the Span trait.

Traits§

InputIter: A Cloneable Iterator that can report an offset as a count of processed Items.
Offsetable: A trait for types that can have an offset as a count of processed items.
Peekable
Positioned: Trait for Inputs that can report current lines and columns in a text input.
Seekable
Span: An input that can provide a span of a range of the input.

Crate abortable_parserCopy item path