invariant-reference 0.1.0

Helps code authors define and use invariants
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

use std::fmt::Debug;

pub trait Invariant {
    const MESSAGE: &str;
}

#[diagnostic::on_unimplemented(
    message = "The invariant {Self} is not proven",
    note = "use `invariant_established!({Self}[{N}])` macro where the invariant is established."
)]
pub trait InvariantProof<const N: usize> {}

#[macro_export]
macro_rules! invariant_established {
    ($name:path [$n:literal], why = $lit:literal) => {
        #[allow(non_local_definitions)]
        impl $crate::InvariantProof<$n> for $name {}
    };
    ($name:path, why = $lit:literal) => {
        #[allow(non_local_definitions)]
        impl $crate::InvariantProof<0> for $name {}
    };
}

pub trait OptionExt<T> {
    fn unwrap_under_invariant<I: Invariant>(self) -> T;
}

impl<T> OptionExt<T> for Option<T> {
    fn unwrap_under_invariant<I: Invariant>(self) -> T {
        self.unwrap_or_else(|| {
            panic!(
                "unwrapping called on None value; violation of invariant: {}",
                I::MESSAGE
            )
        })
    }
}

pub trait ResultExt<T, E> {
    fn unwrap_under_invariant<I: Invariant>(self) -> T;
}

impl<T, E> ResultExt<T, E> for Result<T, E>
where
    E: Debug,
{
    fn unwrap_under_invariant<I: Invariant>(self) -> T {
        self.unwrap_or_else(|error| {
            panic!(
                "unwrapping called on Err value: {error:?}; violation of invariant: {}",
                I::MESSAGE
            )
        })
    }
}