Macro nom::return_error

macro_rules! return_error {
    ($i:expr, $code:expr, $submac:ident!( $($args:tt)* )) => { ... };
    ($i:expr, $code:expr, $f:expr) => { ... };
    ($i:expr, $submac:ident!( $($args:tt)* )) => { ... };
    ($i:expr, $f:expr) => { ... };
}

Prevents backtracking if the child parser fails

This parser will do an early return instead of sending its result to the parent parser.

If another return_error! combinator is present in the parent chain, the error will be wrapped and another early return will be made.

This makes it easy to build report on which parser failed, where it failed in the input, and the chain of parsers that led it there.

Additionally, the error chain contains number identifiers that can be matched to provide useful error messages.

    named!(err_test<&[u8],&[u8],u32>, alt!(
      tag!("abcd") |
      preceded!(tag!("efgh"), return_error!(ErrorKind::Custom(42u32),
          do_parse!(
                 tag!("ijkl")                                        >>
            res: return_error!(ErrorKind::Custom(128), tag!("mnop")) >>
            (res)
          )
        )
      )
    ));
    let a = &b"efghblah"[..];
    let b = &b"efghijklblah"[..];
    let c = &b"efghijklmnop"[..];

    let blah = &b"blah"[..];

    let res_a = err_test(a);
    let res_b = err_test(b);
    let res_c = err_test(c);
    assert_eq!(res_a, Err(Err::Failure(error_node_position!(blah, ErrorKind::Custom(42), error_position!(blah, ErrorKind::Tag)))));
    assert_eq!(res_b, Err(Err::Failure(error_node_position!(&b"ijklblah"[..], ErrorKind::Custom(42),
      error_node_position!(blah, ErrorKind::Custom(128), error_position!(blah, ErrorKind::Tag))))
    ));