Macro get_expectation_for

macro_rules! get_expectation_for {
    ( $actual: expr, panics ) => { ... };
    ( $actual: expr, does not panic ) => { ... };
    ( $actual: expr) => { ... };
    ( $actual: expr , otherwise $reason: expr ) => { ... };
    ( $actual: expr, $matcher: expr ) => { ... };
}

States that the asserted values satisfies the required properties of the supplied Matcher and returns an Expectation object to inspect the results at a later time.

The postulated assertion is verfied immediately, but the returned Expectation defers a potential panic either until Expectation::verify is called or the Expectation object is dropped. It is safe for multiple expectations to fail the assertion code will prevent nested panics.

The macro comes in three different forms:

1. Expect that some expression is true, supplied with an optional error message.

   let e1 = get_expectation_for!(EXPRESSION);
   let e2 = get_expectation_for!(EXPRESSION, otherwise "some error message");

2. Expect that some expression satifies the properties of some Matcher. Expressions used with Matchers must return a reference to a value. The Matcher is either predefined, a user defined type with a Matcher implementation, or a closure returning a MatchResult.

   let e1 = get_expectation_for!(&1, eq(1));
   let e2 = get_expectation_for!(&1, |x| {
       let builder = MatchResultBuilder::for_("my_matcher");
       if x == 1 { builder.matched } else { builder.failed_because("some reason") }
   })

3. Expect that some expression is expected to panic/not panic.

   let e1 = get_expectation_for!(panic!("panic"), panics);
   let e2 = get_expectation_for!(&1+1, does not panic);

An expectation can be verfied manually

let e1 = get_expectation_for!(&1+1, equal_to(0));
let e2 = get_expectation_for!(&1+1, less_than(4)); // is executed
e1.verify();
let e3 = get_expectation_for!(&1+1, panics); // is never executed as e1 panics

or is automatically verfied on drop.

{
    let e1 = get_expectation_for!(&1+1, equal_to(0));
    let e2 = get_expectation_for!(&1+1, less_than(4)); // is executed
}
let e3 = get_expectation_for!(1+1, panics); // is never executed as e1 panics