[][src]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.