Crate abortable_parser

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 combinators::*;

pub use iter::SliceIter;

pub use iter::StrIter;

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.