errors_with_context 1.2.0

Application-ending Errors with context
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
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

use crate::ErrorMessage;

/// This trait allows one to turn [bools](bool) into [ErrorMessages](ErrorMessage),
/// when they have a certain value.
///
/// This allows for cool code like this:
/// ```rust
/// # use std::path::Path;
/// use errors_with_context::{BooleanErrors, ErrorMessage};
/// # fn func() -> Result<(), ErrorMessage> {
/// let path = Path::new("test.file");
/// path.exists()
///     .error_if_false("Expected file to exist!")?;
/// #   Ok(())
/// # }
/// # fn main() {
/// #     let  string = func().unwrap_err().to_string();
/// #     assert_eq!(string, "Expected file to exist!");
/// # }
/// ```
/// or with more dynamic context:
/// ```rust
/// # use std::path::Path;
/// use errors_with_context::prelude::*;
/// # fn func() -> Result<(), ErrorMessage> {
/// let path = Path::new("test.file");
/// path.exists()
///     .error_dyn_if_false(|| format!("Expected file '{}' to exist!", path.display()))?;
/// #   Ok(())
/// # }
/// # fn main() {
/// #     let  string = func().unwrap_err().to_string();
/// #     assert_eq!(string, "Expected file 'test.file' to exist!");
/// # }
/// ```
///
/// Very useful, when doing lots of checks that aren't immediately errors.
pub trait BooleanErrors {
    /// If the [bool] is true, return it `Ok(bool)`.  
    /// If the [bool] is false, return an `Err(ErrorMessage)` with the provided context string..
    ///
    /// ```rust
    /// # use std::path::Path;
    /// use errors_with_context::prelude::*;
    /// # fn func() -> Result<(), ErrorMessage> {
    /// let path = Path::new("test.file");
    /// path.exists()
    ///     .error_if_false("Expected file to exist!")?;
    /// #   Ok(())
    /// # }
    /// # fn main() {
    /// #     let  string = func().unwrap_err().to_string();
    /// #     assert_eq!(string, "Expected file to exist!");
    /// # }
    /// ```
    fn error_if_false(self, context: impl AsRef<str>) -> Result<bool, ErrorMessage>;

    /// If the [bool] is false, return it wrapped in a `Ok(bool)`.  
    /// If the [bool] is true, return an `Err(ErrorMessage)` with the provided context string.
    ///
    /// ```rust
    /// # use std::path::Path;
    /// # use std::ops::Not;
    /// use errors_with_context::prelude::*;
    /// # fn func() -> Result<(), ErrorMessage> {
    /// let path = Path::new("test.file");
    /// path.exists()
    ///     .not()
    ///     .error_if_true("Expected file to exist!")?;
    /// #   Ok(())
    /// # }
    /// # fn main() {
    /// #     let  string = func().unwrap_err().to_string();
    /// #     assert_eq!(string, "Expected file to exist!");
    /// # }
    /// ```
    fn error_if_true(self, context: impl AsRef<str>) -> Result<bool, ErrorMessage>;

    /// If the [bool] is true, return it `Ok(bool)`.  
    /// If the [bool] is false, compute the context and return an `Err(ErrorMessage)`.
    ///
    /// ```rust
    /// # use std::path::Path;
    /// use errors_with_context::prelude::*;
    /// # fn func() -> Result<(), ErrorMessage> {
    /// let path = Path::new("test.file");
    /// path.exists()
    ///     .error_dyn_if_false(|| format!("Expected file '{}' to exist!", path.display()))?;
    /// #   Ok(())
    /// # }
    /// # fn main() {
    /// #     let  string = func().unwrap_err().to_string();
    /// #     assert_eq!(string, "Expected file 'test.file' to exist!");
    /// # }
    fn error_dyn_if_false(self, context: impl FnOnce() -> String) -> Result<bool, ErrorMessage>;

    /// If the [bool] is false, return it `Ok(bool)`.  
    /// If the [bool] is true, compute the context and return an `Err(ErrorMessage)`.
    ///
    /// ```rust
    /// # use std::path::Path;
    /// # use std::ops::Not;
    /// use errors_with_context::prelude::*;
    /// # fn func() -> Result<(), ErrorMessage> {
    /// let path = Path::new("test.file");
    /// path.exists()
    ///     .not()
    ///     .error_dyn_if_true(|| format!("Expected file '{}' to exist!", path.display()))?;
    /// #   Ok(())
    /// # }
    /// # fn main() {
    /// #     let  string = func().unwrap_err().to_string();
    /// #     assert_eq!(string, "Expected file 'test.file' to exist!");
    /// # }
    fn error_dyn_if_true(self, context: impl FnOnce() -> String) -> Result<bool, ErrorMessage>;
}

impl BooleanErrors for bool {
    fn error_if_false(self, context: impl AsRef<str>) -> Result<bool, ErrorMessage> {
        if self {
            Ok(self)
        } else {
            Err(ErrorMessage::new(context.as_ref()))
        }
    }

    fn error_if_true(self, context: impl AsRef<str>) -> Result<bool, ErrorMessage> {
        if self {
            Err(ErrorMessage::new(context.as_ref()))
        } else {
            Ok(self)
        }
    }

    fn error_dyn_if_false(self, context: impl FnOnce() -> String) -> Result<bool, ErrorMessage> {
        if self {
            Ok(self)
        } else {
            Err(ErrorMessage::new(context()))
        }
    }

    fn error_dyn_if_true(self, context: impl FnOnce() -> String) -> Result<bool, ErrorMessage> {
        if self {
            Err(ErrorMessage::new(context()))
        } else {
            Ok(self)
        }
    }
}