A set of macros for design by contact in Rust. The design of this library was inspired by D's contract programming facilities. Here's a quick example:
```rust,skt-main use std::i32;
contract! { fn addoneto_odd(x: i32) -> i32 { post(y) { assert!(y - 1 == x, "reverse operation did not produce input"); } body { x + 1 } pre { assert!(x != i32::MAX, "cannot add one to input at max of number range"); assert!(x % 2 != 0, "evens ain't appropriate here"); } } }
assert!(addonetoodd(3) == 4); assert!(addonetoodd(5) == 6); assertthat!(addonetoodd(2), panics); assertthat!(addonetoodd(i32::MAX), panics); ```
In the above example, pre runs before body, and post, which has the return value of this function bound to y, runs after. We can also define invariants with the invariant block, which will be checked before and after body has run:
```rust,should_panic,skt-main struct Counter { count: u32, max: u32 }
contract! { fn increment_counter(c: &mut Counter) -> () { // Unfortunately, the () return type is necessary for now (see issue #12) invariant { assert!(c.count <= c.max, "counter max has been exceeded"); } body { c.count += 1; } } }
let mut counter = Counter { count: 0, max: 3 };
macrorules! assertincrementedeq { ($e: expr) => ({ incrementcounter(&mut counter); assert!(counter.count == $e, format!("expected counter to be {}, got {}", $e, counter.count)); }) }
assertincrementedeq!(1); assertincrementedeq!(2); assertincrementedeq!(3); assertincrementedeq!(4); // panics! ```
When every contract block is being utilized, the order of the checks inserted into the contract definition are as follows:
preinvariantbodyinvariantpostMore examples can be found in: * The examples directory * The test suite for this library
There are only two known limitations at the time of writing, both of which are planned to be lifted:
contract! block (issue here)This library is called "Adhesion" in reference to a particular type of contract called a "contract of adhesion", also known as a "take-it-or-leave-it" contract. Assertions in programming are definitely "take it or leave it" -- if an assertion is failing, you either have to fix the conditions of the assertion, or change the assertion itself. It sounded appropriate!