1/// Return early with an error.
2///
3/// This macro is equivalent to `return Err(`[`anyhow!($args...)`][anyhow!]`)`.
4///
5/// The surrounding function's or closure's return value is required to be
6/// `Result<_,`[`anyhow::Error`][crate::Error]`>`.
7///
8/// [anyhow!]: crate::anyhow
9///
10/// # Example
11///
12/// ```
13/// # use anyhow::{bail, Result};
14/// #
15/// # fn has_permission(user: usize, resource: usize) -> bool {
16/// # true
17/// # }
18/// #
19/// # fn main() -> Result<()> {
20/// # let user = 0;
21/// # let resource = 0;
22/// #
23/// if !has_permission(user, resource) {
24/// bail!("permission denied for accessing {}", resource);
25/// }
26/// # Ok(())
27/// # }
28/// ```
29///
30/// ```
31/// # use anyhow::{bail, Result};
32/// # use thiserror::Error;
33/// #
34/// # const MAX_DEPTH: usize = 1;
35/// #
36/// #[derive(Error, Debug)]
37/// enum ScienceError {
38/// #[error("recursion limit exceeded")]
39/// RecursionLimitExceeded,
40/// # #[error("...")]
41/// # More = (stringify! {
42/// ...
43/// # }, 1).1,
44/// }
45///
46/// # fn main() -> Result<()> {
47/// # let depth = 0;
48/// #
49/// if depth > MAX_DEPTH {
50/// bail!(ScienceError::RecursionLimitExceeded);
51/// }
52/// # Ok(())
53/// # }
54/// ```
55#[macro_export]
56macro_rules! bail {
57 ($msg:literal $(,)?) => {
58 return $crate::__private::Err($crate::__anyhow!($msg))
59 };
60 ($err:expr $(,)?) => {
61 return $crate::__private::Err($crate::__anyhow!($err))
62 };
63 ($fmt:expr, $($arg:tt)*) => {
64 return $crate::__private::Err($crate::__anyhow!($fmt, $($arg)*))
65 };
66}
67
68/// Return early with an error if a condition is not satisfied.
69///
70/// This macro is equivalent to `if !$cond { return
71/// Err(`[`anyhow!($args...)`][anyhow!]`); }`.
72///
73/// The surrounding function's or closure's return value is required to be
74/// `Result<_,`[`anyhow::Error`][crate::Error]`>`.
75///
76/// Analogously to `assert!`, `ensure!` takes a condition and exits the function
77/// if the condition fails. Unlike `assert!`, `ensure!` returns an `Error`
78/// rather than panicking.
79///
80/// [anyhow!]: crate::anyhow
81///
82/// # Example
83///
84/// ```
85/// # use anyhow::{ensure, Result};
86/// #
87/// # fn main() -> Result<()> {
88/// # let user = 0;
89/// #
90/// ensure!(user == 0, "only user 0 is allowed");
91/// # Ok(())
92/// # }
93/// ```
94///
95/// ```
96/// # use anyhow::{ensure, Result};
97/// # use thiserror::Error;
98/// #
99/// # const MAX_DEPTH: usize = 1;
100/// #
101/// #[derive(Error, Debug)]
102/// enum ScienceError {
103/// #[error("recursion limit exceeded")]
104/// RecursionLimitExceeded,
105/// # #[error("...")]
106/// # More = (stringify! {
107/// ...
108/// # }, 1).1,
109/// }
110///
111/// # fn main() -> Result<()> {
112/// # let depth = 0;
113/// #
114/// ensure!(depth <= MAX_DEPTH, ScienceError::RecursionLimitExceeded);
115/// # Ok(())
116/// # }
117/// ```
118#[cfg(doc)]
119#[macro_export]
120macro_rules! ensure {
121 ($cond:expr $(,)?) => {
122 if !$cond {
123 return $crate::__private::Err($crate::Error::msg(
124 $crate::__private::concat!("Condition failed: `", $crate::__private::stringify!($cond), "`")
125 ));
126 }
127 };
128 ($cond:expr, $msg:literal $(,)?) => {
129 if !$cond {
130 return $crate::__private::Err($crate::__anyhow!($msg));
131 }
132 };
133 ($cond:expr, $err:expr $(,)?) => {
134 if !$cond {
135 return $crate::__private::Err($crate::__anyhow!($err));
136 }
137 };
138 ($cond:expr, $fmt:expr, $($arg:tt)*) => {
139 if !$cond {
140 return $crate::__private::Err($crate::__anyhow!($fmt, $($arg)*));
141 }
142 };
143}
144
145#[cfg(not(doc))]
146#[macro_export]
147macro_rules! ensure {
148 ($($tt:tt)*) => {
149 $crate::__parse_ensure!(
150 /* state */ 0
151 /* stack */ ()
152 /* bail */ ($($tt)*)
153 /* fuel */ (~~~~~~~~~~ ~~~~~~~~~~ ~~~~~~~~~~ ~~~~~~~~~~ ~~~~~~~~~~ ~~~~~~~~~~ ~~~~~~~~~~ ~~~~~~~~~~ ~~~~~~~~~~ ~~~~~~~~~~ ~~~~~~~~~~ ~~~~~~~~~~)
154 /* parse */ {()}
155 /* dup */ ($($tt)*)
156 /* rest */ $($tt)*
157 )
158 };
159}
160
161/// Construct an ad-hoc error from a string or existing non-`anyhow` error
162/// value.
163///
164/// This evaluates to an [`Error`][crate::Error]. It can take either just a
165/// string, or a format string with arguments. It also can take any custom type
166/// which implements `Debug` and `Display`.
167///
168/// If called with a single argument whose type implements `std::error::Error`
169/// (in addition to `Debug` and `Display`, which are always required), then that
170/// Error impl's `source` is preserved as the `source` of the resulting
171/// `anyhow::Error`.
172///
173/// # Example
174///
175/// ```
176/// # type V = ();
177/// #
178/// use anyhow::{anyhow, Result};
179///
180/// fn lookup(key: &str) -> Result<V> {
181/// if key.len() != 16 {
182/// return Err(anyhow!("key length must be 16 characters, got {:?}", key));
183/// }
184///
185/// // ...
186/// # Ok(())
187/// }
188/// ```
189#[macro_export]
190macro_rules! anyhow {
191 ($msg:literal $(,)?) => {
192 $crate::__private::must_use({
193 let error = $crate::__private::format_err($crate::__private::format_args!($msg));
194 error
195 })
196 };
197 ($err:expr $(,)?) => {
198 $crate::__private::must_use({
199 use $crate::__private::kind::*;
200 let error = match $err {
201 error => (&error).anyhow_kind().new(error),
202 };
203 error
204 })
205 };
206 ($fmt:expr, $($arg:tt)*) => {
207 $crate::Error::msg($crate::__private::format!($fmt, $($arg)*))
208 };
209}
210
211// Not public API. This is used in the implementation of some of the other
212// macros, in which the must_use call is not needed because the value is known
213// to be used.
214#[doc(hidden)]
215#[macro_export]
216macro_rules! __anyhow {
217 ($msg:literal $(,)?) => ({
218 let error = $crate::__private::format_err($crate::__private::format_args!($msg));
219 error
220 });
221 ($err:expr $(,)?) => ({
222 use $crate::__private::kind::*;
223 let error = match $err {
224 error => (&error).anyhow_kind().new(error),
225 };
226 error
227 });
228 ($fmt:expr, $($arg:tt)*) => {
229 $crate::Error::msg($crate::__private::format!($fmt, $($arg)*))
230 };
231}
232