third_party/rust/anyhow/src/macros.rs

   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]
  56 macro_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]
 120 macro_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]
 147 macro_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]
 190 macro_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]
 216 macro_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 }