Crate abortable_parser[][src]

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 combinators::*;
pub use iter::SliceIter;
pub use iter::StrIter;

Modules

Contains combinators that can assemble other matchers or combinators into more complex grammars.

Contains implementations of InputIter.

Macros

Turns Result::Incomplete into Result::Fail.

Consumes the input until the $rule fails and then returns the consumed input as a slice.

Discards the output of a combinator rule when it completes and just returns (). Leaves Failures, Aborts, and Incompletes untouched.

Captures a sequence of sub parsers output.

Returns the output of the first sub parser to succeed.

Helper macro that returns the input without consuming it.

Constructs a function named $name that takes an input of type $i and produces an output of type $o.

Turns Result::Fail into Result::Abort.

Turns Result::Fail and Result::Incomplete into Result::Abort.

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 ().

Treats a sub parser as optional. It returns Some(output) for a successful match and None for failures.

Checks the given matcher without consuming the input.

Runs a single matcher repeating 0 or more times and returns a possibly empty vector of the parsed results.

Converts a function indentifier into a macro call. Useful when writing your own macro combinator.

Parses separated list of items.

Convenience macro for looking for a specific text token in a byte input stream.

Turns Result::Abort into Result::Fail allowing you to trap and then convert any Result::Abort into a normal Fail.

Consumes an input until it reaches a term that the contained rule matches. It does not consume the subrule.

Replaces the the sub error in a Fail case with one of your own errors.

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

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

The result of a parsing attempt.

SpanRange encompasses the valid Ops::Range types for use with the Span trait.

Traits

A Cloneable Iterator that can report an offset as a count of processed Items.

A trait for types that can have an offset as a count of processed items.

Trait for Inputs that can report current lines and columns in a text input.

An input that can provide a span of a range of the input.