| 1 |
//! [![github]](https://github.com/dtolnay/anyhow) [![crates-io]](https://crates.io/crates/anyhow) [![docs-rs]](https://docs.rs/anyhow) |
| 2 |
//! |
| 3 |
//! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github |
| 4 |
//! [crates-io]: https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=555555&logo=rust |
| 5 |
//! [docs-rs]: https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs |
| 6 |
//! |
| 7 |
//! <br> |
| 8 |
//! |
| 9 |
//! This library provides [`anyhow::Error`][Error], a trait object based error |
| 10 |
//! type for easy idiomatic error handling in Rust applications. |
| 11 |
//! |
| 12 |
//! <br> |
| 13 |
//! |
| 14 |
//! # Details |
| 15 |
//! |
| 16 |
//! - Use `Result<T, anyhow::Error>`, or equivalently `anyhow::Result<T>`, as |
| 17 |
//! the return type of any fallible function. |
| 18 |
//! |
| 19 |
//! Within the function, use `?` to easily propagate any error that implements |
| 20 |
//! the [`std::error::Error`] trait. |
| 21 |
//! |
| 22 |
//! ``` |
| 23 |
//! # pub trait Deserialize {} |
| 24 |
//! # |
| 25 |
//! # mod serde_json { |
| 26 |
//! # use super::Deserialize; |
| 27 |
//! # use std::io; |
| 28 |
//! # |
| 29 |
//! # pub fn from_str<T: Deserialize>(json: &str) -> io::Result<T> { |
| 30 |
//! # unimplemented!() |
| 31 |
//! # } |
| 32 |
//! # } |
| 33 |
//! # |
| 34 |
//! # struct ClusterMap; |
| 35 |
//! # |
| 36 |
//! # impl Deserialize for ClusterMap {} |
| 37 |
//! # |
| 38 |
//! use anyhow::Result; |
| 39 |
//! |
| 40 |
//! fn get_cluster_info() -> Result<ClusterMap> { |
| 41 |
//! let config = std::fs::read_to_string("cluster.json")?; |
| 42 |
//! let map: ClusterMap = serde_json::from_str(&config)?; |
| 43 |
//! Ok(map) |
| 44 |
//! } |
| 45 |
//! # |
| 46 |
//! # fn main() {} |
| 47 |
//! ``` |
| 48 |
//! |
| 49 |
//! - Attach context to help the person troubleshooting the error understand |
| 50 |
//! where things went wrong. A low-level error like "No such file or |
| 51 |
//! directory" can be annoying to debug without more context about what higher |
| 52 |
//! level step the application was in the middle of. |
| 53 |
//! |
| 54 |
//! ``` |
| 55 |
//! # struct It; |
| 56 |
//! # |
| 57 |
//! # impl It { |
| 58 |
//! # fn detach(&self) -> Result<()> { |
| 59 |
//! # unimplemented!() |
| 60 |
//! # } |
| 61 |
//! # } |
| 62 |
//! # |
| 63 |
//! use anyhow::{Context, Result}; |
| 64 |
//! |
| 65 |
//! fn main() -> Result<()> { |
| 66 |
//! # return Ok(()); |
| 67 |
//! # |
| 68 |
//! # const _: &str = stringify! { |
| 69 |
//! ... |
| 70 |
//! # }; |
| 71 |
//! # |
| 72 |
//! # let it = It; |
| 73 |
//! # let path = "./path/to/instrs.json"; |
| 74 |
//! # |
| 75 |
//! it.detach().context("Failed to detach the important thing")?; |
| 76 |
//! |
| 77 |
//! let content = std::fs::read(path) |
| 78 |
//! .with_context(|| format!("Failed to read instrs from {}", path))?; |
| 79 |
//! # |
| 80 |
//! # const _: &str = stringify! { |
| 81 |
//! ... |
| 82 |
//! # }; |
| 83 |
//! # |
| 84 |
//! # Ok(()) |
| 85 |
//! } |
| 86 |
//! ``` |
| 87 |
//! |
| 88 |
//! ```console |
| 89 |
//! Error: Failed to read instrs from ./path/to/instrs.json |
| 90 |
//! |
| 91 |
//! Caused by: |
| 92 |
//! No such file or directory (os error 2) |
| 93 |
//! ``` |
| 94 |
//! |
| 95 |
//! - Downcasting is supported and can be by value, by shared reference, or by |
| 96 |
//! mutable reference as needed. |
| 97 |
//! |
| 98 |
//! ``` |
| 99 |
//! # use anyhow::anyhow; |
| 100 |
//! # use std::fmt::{self, Display}; |
| 101 |
//! # use std::task::Poll; |
| 102 |
//! # |
| 103 |
//! # #[derive(Debug)] |
| 104 |
//! # enum DataStoreError { |
| 105 |
//! # Censored(()), |
| 106 |
//! # } |
| 107 |
//! # |
| 108 |
//! # impl Display for DataStoreError { |
| 109 |
//! # fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result { |
| 110 |
//! # unimplemented!() |
| 111 |
//! # } |
| 112 |
//! # } |
| 113 |
//! # |
| 114 |
//! # impl std::error::Error for DataStoreError {} |
| 115 |
//! # |
| 116 |
//! # const REDACTED_CONTENT: () = (); |
| 117 |
//! # |
| 118 |
//! # let error = anyhow!("..."); |
| 119 |
//! # let root_cause = &error; |
| 120 |
//! # |
| 121 |
//! # let ret = |
| 122 |
//! // If the error was caused by redaction, then return a |
| 123 |
//! // tombstone instead of the content. |
| 124 |
//! match root_cause.downcast_ref::<DataStoreError>() { |
| 125 |
//! Some(DataStoreError::Censored(_)) => Ok(Poll::Ready(REDACTED_CONTENT)), |
| 126 |
//! None => Err(error), |
| 127 |
//! } |
| 128 |
//! # ; |
| 129 |
//! ``` |
| 130 |
//! |
| 131 |
//! - If using Rust ≥ 1.65, a backtrace is captured and printed with the |
| 132 |
//! error if the underlying error type does not already provide its own. In |
| 133 |
//! order to see backtraces, they must be enabled through the environment |
| 134 |
//! variables described in [`std::backtrace`]: |
| 135 |
//! |
| 136 |
//! - If you want panics and errors to both have backtraces, set |
| 137 |
//! `RUST_BACKTRACE=1`; |
| 138 |
//! - If you want only errors to have backtraces, set `RUST_LIB_BACKTRACE=1`; |
| 139 |
//! - If you want only panics to have backtraces, set `RUST_BACKTRACE=1` and |
| 140 |
//! `RUST_LIB_BACKTRACE=0`. |
| 141 |
//! |
| 142 |
//! [`std::backtrace`]: std::backtrace#environment-variables |
| 143 |
//! |
| 144 |
//! - Anyhow works with any error type that has an impl of `std::error::Error`, |
| 145 |
//! including ones defined in your crate. We do not bundle a `derive(Error)` |
| 146 |
//! macro but you can write the impls yourself or use a standalone macro like |
| 147 |
//! [thiserror]. |
| 148 |
//! |
| 149 |
//! [thiserror]: https://github.com/dtolnay/thiserror |
| 150 |
//! |
| 151 |
//! ``` |
| 152 |
//! use thiserror::Error; |
| 153 |
//! |
| 154 |
//! #[derive(Error, Debug)] |
| 155 |
//! pub enum FormatError { |
| 156 |
//! #[error("Invalid header (expected {expected:?}, got {found:?})")] |
| 157 |
//! InvalidHeader { |
| 158 |
//! expected: String, |
| 159 |
//! found: String, |
| 160 |
//! }, |
| 161 |
//! #[error("Missing attribute: {0}")] |
| 162 |
//! MissingAttribute(String), |
| 163 |
//! } |
| 164 |
//! ``` |
| 165 |
//! |
| 166 |
//! - One-off error messages can be constructed using the `anyhow!` macro, which |
| 167 |
//! supports string interpolation and produces an `anyhow::Error`. |
| 168 |
//! |
| 169 |
//! ``` |
| 170 |
//! # use anyhow::{anyhow, Result}; |
| 171 |
//! # |
| 172 |
//! # fn demo() -> Result<()> { |
| 173 |
//! # let missing = "..."; |
| 174 |
//! return Err(anyhow!("Missing attribute: {}", missing)); |
| 175 |
//! # Ok(()) |
| 176 |
//! # } |
| 177 |
//! ``` |
| 178 |
//! |
| 179 |
//! A `bail!` macro is provided as a shorthand for the same early return. |
| 180 |
//! |
| 181 |
//! ``` |
| 182 |
//! # use anyhow::{bail, Result}; |
| 183 |
//! # |
| 184 |
//! # fn demo() -> Result<()> { |
| 185 |
//! # let missing = "..."; |
| 186 |
//! bail!("Missing attribute: {}", missing); |
| 187 |
//! # Ok(()) |
| 188 |
//! # } |
| 189 |
//! ``` |
| 190 |
//! |
| 191 |
//! <br> |
| 192 |
//! |
| 193 |
//! # No-std support |
| 194 |
//! |
| 195 |
//! In no_std mode, almost all of the same API is available and works the same |
| 196 |
//! way. To depend on Anyhow in no_std mode, disable our default enabled "std" |
| 197 |
//! feature in Cargo.toml. A global allocator is required. |
| 198 |
//! |
| 199 |
//! ```toml |
| 200 |
//! [dependencies] |
| 201 |
//! anyhow = { version = "1.0", default-features = false } |
| 202 |
//! ``` |
| 203 |
//! |
| 204 |
//! With versions of Rust older than 1.81, no_std mode may require an additional |
| 205 |
//! `.map_err(Error::msg)` when working with a non-Anyhow error type inside a |
| 206 |
//! function that returns Anyhow's error type, as the trait that `?`-based error |
| 207 |
//! conversions are defined by is only available in std in those old versions. |
| 208 |
|
| 209 |
#![doc(html_root_url = "https://docs.rs/anyhow/1.0.100")] |
| 210 |
#![cfg_attr(error_generic_member_access, feature(error_generic_member_access))] |
| 211 |
#![no_std] |
| 212 |
#![deny(dead_code, unused_imports, unused_mut)] |
| 213 |
#![cfg_attr( |
| 214 |
not(anyhow_no_unsafe_op_in_unsafe_fn_lint), |
| 215 |
deny(unsafe_op_in_unsafe_fn) |
| 216 |
)] |
| 217 |
#![cfg_attr(anyhow_no_unsafe_op_in_unsafe_fn_lint, allow(unused_unsafe))] |
| 218 |
#![allow( |
| 219 |
clippy::doc_markdown, |
| 220 |
clippy::elidable_lifetime_names, |
| 221 |
clippy::enum_glob_use, |
| 222 |
clippy::explicit_auto_deref, |
| 223 |
clippy::extra_unused_type_parameters, |
| 224 |
clippy::incompatible_msrv, |
| 225 |
clippy::let_underscore_untyped, |
| 226 |
clippy::missing_errors_doc, |
| 227 |
clippy::missing_panics_doc, |
| 228 |
clippy::module_name_repetitions, |
| 229 |
clippy::must_use_candidate, |
| 230 |
clippy::needless_doctest_main, |
| 231 |
clippy::needless_lifetimes, |
| 232 |
clippy::new_ret_no_self, |
| 233 |
clippy::redundant_else, |
| 234 |
clippy::return_self_not_must_use, |
| 235 |
clippy::struct_field_names, |
| 236 |
clippy::unused_self, |
| 237 |
clippy::used_underscore_binding, |
| 238 |
clippy::wildcard_imports, |
| 239 |
clippy::wrong_self_convention |
| 240 |
)] |
| 241 |
#![allow(unknown_lints, mismatched_lifetime_syntaxes)] |
| 242 |
|
| 243 |
#[cfg(all( |
| 244 |
anyhow_nightly_testing, |
| 245 |
feature = "std", |
| 246 |
not(error_generic_member_access) |
| 247 |
))] |
| 248 |
compile_error!("Build script probe failed to compile."); |
| 249 |
|
| 250 |
extern crate alloc; |
| 251 |
|
| 252 |
#[cfg(feature = "std")] |
| 253 |
extern crate std; |
| 254 |
|
| 255 |
#[macro_use] |
| 256 |
mod backtrace; |
| 257 |
mod chain; |
| 258 |
mod context; |
| 259 |
mod ensure; |
| 260 |
mod error; |
| 261 |
mod fmt; |
| 262 |
mod kind; |
| 263 |
mod macros; |
| 264 |
#[cfg(error_generic_member_access)] |
| 265 |
mod nightly; |
| 266 |
mod ptr; |
| 267 |
mod wrapper; |
| 268 |
|
| 269 |
use crate::error::ErrorImpl; |
| 270 |
use crate::ptr::Own; |
| 271 |
use core::fmt::Display; |
| 272 |
|
| 273 |
#[cfg(all(not(feature = "std"), anyhow_no_core_error))] |
| 274 |
use core::fmt::Debug; |
| 275 |
|
| 276 |
#[cfg(feature = "std")] |
| 277 |
use std::error::Error as StdError; |
| 278 |
|
| 279 |
#[cfg(not(any(feature = "std", anyhow_no_core_error)))] |
| 280 |
use core::error::Error as StdError; |
| 281 |
|
| 282 |
#[cfg(all(not(feature = "std"), anyhow_no_core_error))] |
| 283 |
trait StdError: Debug + Display { |
| 284 |
fn source(&self) -> Option<&(dyn StdError + 'static)> { |
| 285 |
None |
| 286 |
} |
| 287 |
} |
| 288 |
|
| 289 |
#[doc(no_inline)] |
| 290 |
pub use anyhow as format_err; |
| 291 |
|
| 292 |
/// The `Error` type, a wrapper around a dynamic error type. |
| 293 |
/// |
| 294 |
/// `Error` works a lot like `Box<dyn std::error::Error>`, but with these |
| 295 |
/// differences: |
| 296 |
/// |
| 297 |
/// - `Error` requires that the error is `Send`, `Sync`, and `'static`. |
| 298 |
/// - `Error` guarantees that a backtrace is available, even if the underlying |
| 299 |
/// error type does not provide one. |
| 300 |
/// - `Error` is represented as a narrow pointer — exactly one word in |
| 301 |
/// size instead of two. |
| 302 |
/// |
| 303 |
/// <br> |
| 304 |
/// |
| 305 |
/// # Display representations |
| 306 |
/// |
| 307 |
/// When you print an error object using "{}" or to_string(), only the outermost |
| 308 |
/// underlying error or context is printed, not any of the lower level causes. |
| 309 |
/// This is exactly as if you had called the Display impl of the error from |
| 310 |
/// which you constructed your anyhow::Error. |
| 311 |
/// |
| 312 |
/// ```console |
| 313 |
/// Failed to read instrs from ./path/to/instrs.json |
| 314 |
/// ``` |
| 315 |
/// |
| 316 |
/// To print causes as well using anyhow's default formatting of causes, use the |
| 317 |
/// alternate selector "{:#}". |
| 318 |
/// |
| 319 |
/// ```console |
| 320 |
/// Failed to read instrs from ./path/to/instrs.json: No such file or directory (os error 2) |
| 321 |
/// ``` |
| 322 |
/// |
| 323 |
/// The Debug format "{:?}" includes your backtrace if one was captured. Note |
| 324 |
/// that this is the representation you get by default if you return an error |
| 325 |
/// from `fn main` instead of printing it explicitly yourself. |
| 326 |
/// |
| 327 |
/// ```console |
| 328 |
/// Error: Failed to read instrs from ./path/to/instrs.json |
| 329 |
/// |
| 330 |
/// Caused by: |
| 331 |
/// No such file or directory (os error 2) |
| 332 |
/// ``` |
| 333 |
/// |
| 334 |
/// and if there is a backtrace available: |
| 335 |
/// |
| 336 |
/// ```console |
| 337 |
/// Error: Failed to read instrs from ./path/to/instrs.json |
| 338 |
/// |
| 339 |
/// Caused by: |
| 340 |
/// No such file or directory (os error 2) |
| 341 |
/// |
| 342 |
/// Stack backtrace: |
| 343 |
/// 0: <E as anyhow::context::ext::StdError>::ext_context |
| 344 |
/// at /git/anyhow/src/backtrace.rs:26 |
| 345 |
/// 1: core::result::Result<T,E>::map_err |
| 346 |
/// at /git/rustc/src/libcore/result.rs:596 |
| 347 |
/// 2: anyhow::context::<impl anyhow::Context<T,E> for core::result::Result<T,E>>::with_context |
| 348 |
/// at /git/anyhow/src/context.rs:58 |
| 349 |
/// 3: testing::main |
| 350 |
/// at src/main.rs:5 |
| 351 |
/// 4: std::rt::lang_start |
| 352 |
/// at /git/rustc/src/libstd/rt.rs:61 |
| 353 |
/// 5: main |
| 354 |
/// 6: __libc_start_main |
| 355 |
/// 7: _start |
| 356 |
/// ``` |
| 357 |
/// |
| 358 |
/// To see a conventional struct-style Debug representation, use "{:#?}". |
| 359 |
/// |
| 360 |
/// ```console |
| 361 |
/// Error { |
| 362 |
/// context: "Failed to read instrs from ./path/to/instrs.json", |
| 363 |
/// source: Os { |
| 364 |
/// code: 2, |
| 365 |
/// kind: NotFound, |
| 366 |
/// message: "No such file or directory", |
| 367 |
/// }, |
| 368 |
/// } |
| 369 |
/// ``` |
| 370 |
/// |
| 371 |
/// If none of the built-in representations are appropriate and you would prefer |
| 372 |
/// to render the error and its cause chain yourself, it can be done something |
| 373 |
/// like this: |
| 374 |
/// |
| 375 |
/// ``` |
| 376 |
/// use anyhow::{Context, Result}; |
| 377 |
/// |
| 378 |
/// fn main() { |
| 379 |
/// if let Err(err) = try_main() { |
| 380 |
/// eprintln!("ERROR: {}", err); |
| 381 |
/// err.chain().skip(1).for_each(|cause| eprintln!("because: {}", cause)); |
| 382 |
/// std::process::exit(1); |
| 383 |
/// } |
| 384 |
/// } |
| 385 |
/// |
| 386 |
/// fn try_main() -> Result<()> { |
| 387 |
/// # const IGNORE: &str = stringify! { |
| 388 |
/// ... |
| 389 |
/// # }; |
| 390 |
/// # Ok(()) |
| 391 |
/// } |
| 392 |
/// ``` |
| 393 |
#[repr(transparent)] |
| 394 |
pub struct Error { |
| 395 |
inner: Own<ErrorImpl>, |
| 396 |
} |
| 397 |
|
| 398 |
/// Iterator of a chain of source errors. |
| 399 |
/// |
| 400 |
/// This type is the iterator returned by [`Error::chain`]. |
| 401 |
/// |
| 402 |
/// # Example |
| 403 |
/// |
| 404 |
/// ``` |
| 405 |
/// use anyhow::Error; |
| 406 |
/// use std::io; |
| 407 |
/// |
| 408 |
/// pub fn underlying_io_error_kind(error: &Error) -> Option<io::ErrorKind> { |
| 409 |
/// for cause in error.chain() { |
| 410 |
/// if let Some(io_error) = cause.downcast_ref::<io::Error>() { |
| 411 |
/// return Some(io_error.kind()); |
| 412 |
/// } |
| 413 |
/// } |
| 414 |
/// None |
| 415 |
/// } |
| 416 |
/// ``` |
| 417 |
#[cfg(any(feature = "std", not(anyhow_no_core_error)))] |
| 418 |
#[derive(Clone)] |
| 419 |
pub struct Chain<'a> { |
| 420 |
state: crate::chain::ChainState<'a>, |
| 421 |
} |
| 422 |
|
| 423 |
/// `Result<T, Error>` |
| 424 |
/// |
| 425 |
/// This is a reasonable return type to use throughout your application but also |
| 426 |
/// for `fn main`; if you do, failures will be printed along with any |
| 427 |
/// [context][Context] and a backtrace if one was captured. |
| 428 |
/// |
| 429 |
/// `anyhow::Result` may be used with one *or* two type parameters. |
| 430 |
/// |
| 431 |
/// ```rust |
| 432 |
/// use anyhow::Result; |
| 433 |
/// |
| 434 |
/// # const IGNORE: &str = stringify! { |
| 435 |
/// fn demo1() -> Result<T> {...} |
| 436 |
/// // ^ equivalent to std::result::Result<T, anyhow::Error> |
| 437 |
/// |
| 438 |
/// fn demo2() -> Result<T, OtherError> {...} |
| 439 |
/// // ^ equivalent to std::result::Result<T, OtherError> |
| 440 |
/// # }; |
| 441 |
/// ``` |
| 442 |
/// |
| 443 |
/// # Example |
| 444 |
/// |
| 445 |
/// ``` |
| 446 |
/// # pub trait Deserialize {} |
| 447 |
/// # |
| 448 |
/// # mod serde_json { |
| 449 |
/// # use super::Deserialize; |
| 450 |
/// # use std::io; |
| 451 |
/// # |
| 452 |
/// # pub fn from_str<T: Deserialize>(json: &str) -> io::Result<T> { |
| 453 |
/// # unimplemented!() |
| 454 |
/// # } |
| 455 |
/// # } |
| 456 |
/// # |
| 457 |
/// # #[derive(Debug)] |
| 458 |
/// # struct ClusterMap; |
| 459 |
/// # |
| 460 |
/// # impl Deserialize for ClusterMap {} |
| 461 |
/// # |
| 462 |
/// use anyhow::Result; |
| 463 |
/// |
| 464 |
/// fn main() -> Result<()> { |
| 465 |
/// # return Ok(()); |
| 466 |
/// let config = std::fs::read_to_string("cluster.json")?; |
| 467 |
/// let map: ClusterMap = serde_json::from_str(&config)?; |
| 468 |
/// println!("cluster info: {:#?}", map); |
| 469 |
/// Ok(()) |
| 470 |
/// } |
| 471 |
/// ``` |
| 472 |
pub type Result<T, E = Error> = core::result::Result<T, E>; |
| 473 |
|
| 474 |
/// Provides the `context` method for `Result`. |
| 475 |
/// |
| 476 |
/// This trait is sealed and cannot be implemented for types outside of |
| 477 |
/// `anyhow`. |
| 478 |
/// |
| 479 |
/// <br> |
| 480 |
/// |
| 481 |
/// # Example |
| 482 |
/// |
| 483 |
/// ``` |
| 484 |
/// use anyhow::{Context, Result}; |
| 485 |
/// use std::fs; |
| 486 |
/// use std::path::PathBuf; |
| 487 |
/// |
| 488 |
/// pub struct ImportantThing { |
| 489 |
/// path: PathBuf, |
| 490 |
/// } |
| 491 |
/// |
| 492 |
/// impl ImportantThing { |
| 493 |
/// # const IGNORE: &'static str = stringify! { |
| 494 |
/// pub fn detach(&mut self) -> Result<()> {...} |
| 495 |
/// # }; |
| 496 |
/// # fn detach(&mut self) -> Result<()> { |
| 497 |
/// # unimplemented!() |
| 498 |
/// # } |
| 499 |
/// } |
| 500 |
/// |
| 501 |
/// pub fn do_it(mut it: ImportantThing) -> Result<Vec<u8>> { |
| 502 |
/// it.detach().context("Failed to detach the important thing")?; |
| 503 |
/// |
| 504 |
/// let path = &it.path; |
| 505 |
/// let content = fs::read(path) |
| 506 |
/// .with_context(|| format!("Failed to read instrs from {}", path.display()))?; |
| 507 |
/// |
| 508 |
/// Ok(content) |
| 509 |
/// } |
| 510 |
/// ``` |
| 511 |
/// |
| 512 |
/// When printed, the outermost context would be printed first and the lower |
| 513 |
/// level underlying causes would be enumerated below. |
| 514 |
/// |
| 515 |
/// ```console |
| 516 |
/// Error: Failed to read instrs from ./path/to/instrs.json |
| 517 |
/// |
| 518 |
/// Caused by: |
| 519 |
/// No such file or directory (os error 2) |
| 520 |
/// ``` |
| 521 |
/// |
| 522 |
/// Refer to the [Display representations] documentation for other forms in |
| 523 |
/// which this context chain can be rendered. |
| 524 |
/// |
| 525 |
/// [Display representations]: Error#display-representations |
| 526 |
/// |
| 527 |
/// <br> |
| 528 |
/// |
| 529 |
/// # Effect on downcasting |
| 530 |
/// |
| 531 |
/// After attaching context of type `C` onto an error of type `E`, the resulting |
| 532 |
/// `anyhow::Error` may be downcast to `C` **or** to `E`. |
| 533 |
/// |
| 534 |
/// That is, in codebases that rely on downcasting, Anyhow's context supports |
| 535 |
/// both of the following use cases: |
| 536 |
/// |
| 537 |
/// - **Attaching context whose type is insignificant onto errors whose type |
| 538 |
/// is used in downcasts.** |
| 539 |
/// |
| 540 |
/// In other error libraries whose context is not designed this way, it can |
| 541 |
/// be risky to introduce context to existing code because new context might |
| 542 |
/// break existing working downcasts. In Anyhow, any downcast that worked |
| 543 |
/// before adding context will continue to work after you add a context, so |
| 544 |
/// you should freely add human-readable context to errors wherever it would |
| 545 |
/// be helpful. |
| 546 |
/// |
| 547 |
/// ``` |
| 548 |
/// # use anyhow::bail; |
| 549 |
/// # use thiserror::Error; |
| 550 |
/// # |
| 551 |
/// # #[derive(Error, Debug)] |
| 552 |
/// # #[error("???")] |
| 553 |
/// # struct SuspiciousError; |
| 554 |
/// # |
| 555 |
/// # fn helper() -> Result<()> { |
| 556 |
/// # bail!(SuspiciousError); |
| 557 |
/// # } |
| 558 |
/// # |
| 559 |
/// use anyhow::{Context, Result}; |
| 560 |
/// |
| 561 |
/// fn do_it() -> Result<()> { |
| 562 |
/// helper().context("Failed to complete the work")?; |
| 563 |
/// # const IGNORE: &str = stringify! { |
| 564 |
/// ... |
| 565 |
/// # }; |
| 566 |
/// # unreachable!() |
| 567 |
/// } |
| 568 |
/// |
| 569 |
/// fn main() { |
| 570 |
/// let err = do_it().unwrap_err(); |
| 571 |
/// if let Some(e) = err.downcast_ref::<SuspiciousError>() { |
| 572 |
/// // If helper() returned SuspiciousError, this downcast will |
| 573 |
/// // correctly succeed even with the context in between. |
| 574 |
/// # return; |
| 575 |
/// } |
| 576 |
/// # panic!("expected downcast to succeed"); |
| 577 |
/// } |
| 578 |
/// ``` |
| 579 |
/// |
| 580 |
/// - **Attaching context whose type is used in downcasts onto errors whose |
| 581 |
/// type is insignificant.** |
| 582 |
/// |
| 583 |
/// Some codebases prefer to use machine-readable context to categorize |
| 584 |
/// lower level errors in a way that will be actionable to higher levels of |
| 585 |
/// the application. |
| 586 |
/// |
| 587 |
/// ``` |
| 588 |
/// # use anyhow::bail; |
| 589 |
/// # use thiserror::Error; |
| 590 |
/// # |
| 591 |
/// # #[derive(Error, Debug)] |
| 592 |
/// # #[error("???")] |
| 593 |
/// # struct HelperFailed; |
| 594 |
/// # |
| 595 |
/// # fn helper() -> Result<()> { |
| 596 |
/// # bail!("no such file or directory"); |
| 597 |
/// # } |
| 598 |
/// # |
| 599 |
/// use anyhow::{Context, Result}; |
| 600 |
/// |
| 601 |
/// fn do_it() -> Result<()> { |
| 602 |
/// helper().context(HelperFailed)?; |
| 603 |
/// # const IGNORE: &str = stringify! { |
| 604 |
/// ... |
| 605 |
/// # }; |
| 606 |
/// # unreachable!() |
| 607 |
/// } |
| 608 |
/// |
| 609 |
/// fn main() { |
| 610 |
/// let err = do_it().unwrap_err(); |
| 611 |
/// if let Some(e) = err.downcast_ref::<HelperFailed>() { |
| 612 |
/// // If helper failed, this downcast will succeed because |
| 613 |
/// // HelperFailed is the context that has been attached to |
| 614 |
/// // that error. |
| 615 |
/// # return; |
| 616 |
/// } |
| 617 |
/// # panic!("expected downcast to succeed"); |
| 618 |
/// } |
| 619 |
/// ``` |
| 620 |
pub trait Context<T, E>: context::private::Sealed { |
| 621 |
/// Wrap the error value with additional context. |
| 622 |
fn context<C>(self, context: C) -> Result<T, Error> |
| 623 |
where |
| 624 |
C: Display + Send + Sync + 'static; |
| 625 |
|
| 626 |
/// Wrap the error value with additional context that is evaluated lazily |
| 627 |
/// only once an error does occur. |
| 628 |
fn with_context<C, F>(self, f: F) -> Result<T, Error> |
| 629 |
where |
| 630 |
C: Display + Send + Sync + 'static, |
| 631 |
F: FnOnce() -> C; |
| 632 |
} |
| 633 |
|
| 634 |
/// Equivalent to `Ok::<_, anyhow::Error>(value)`. |
| 635 |
/// |
| 636 |
/// This simplifies creation of an `anyhow::Result` in places where type |
| 637 |
/// inference cannot deduce the `E` type of the result — without needing |
| 638 |
/// to write`Ok::<_, anyhow::Error>(value)`. |
| 639 |
/// |
| 640 |
/// One might think that `anyhow::Result::Ok(value)` would work in such cases |
| 641 |
/// but it does not. |
| 642 |
/// |
| 643 |
/// ```console |
| 644 |
/// error[E0282]: type annotations needed for `std::result::Result<i32, E>` |
| 645 |
/// --> src/main.rs:11:13 |
| 646 |
/// | |
| 647 |
/// 11 | let _ = anyhow::Result::Ok(1); |
| 648 |
/// | - ^^^^^^^^^^^^^^^^^^ cannot infer type for type parameter `E` declared on the enum `Result` |
| 649 |
/// | | |
| 650 |
/// | consider giving this pattern the explicit type `std::result::Result<i32, E>`, where the type parameter `E` is specified |
| 651 |
/// ``` |
| 652 |
#[allow(non_snake_case)] |
| 653 |
pub fn Ok<T>(value: T) -> Result<T> { |
| 654 |
Result::Ok(value) |
| 655 |
} |
| 656 |
|
| 657 |
// Not public API. Referenced by macro-generated code. |
| 658 |
#[doc(hidden)] |
| 659 |
pub mod __private { |
| 660 |
use self::not::Bool; |
| 661 |
use crate::Error; |
| 662 |
use alloc::fmt; |
| 663 |
use core::fmt::Arguments; |
| 664 |
|
| 665 |
#[doc(hidden)] |
| 666 |
pub use crate::ensure::{BothDebug, NotBothDebug}; |
| 667 |
#[doc(hidden)] |
| 668 |
pub use alloc::format; |
| 669 |
#[doc(hidden)] |
| 670 |
pub use core::result::Result::Err; |
| 671 |
#[doc(hidden)] |
| 672 |
pub use core::{concat, format_args, stringify}; |
| 673 |
|
| 674 |
#[doc(hidden)] |
| 675 |
pub mod kind { |
| 676 |
#[doc(hidden)] |
| 677 |
pub use crate::kind::{AdhocKind, TraitKind}; |
| 678 |
|
| 679 |
#[cfg(any(feature = "std", not(anyhow_no_core_error)))] |
| 680 |
#[doc(hidden)] |
| 681 |
pub use crate::kind::BoxedKind; |
| 682 |
} |
| 683 |
|
| 684 |
#[doc(hidden)] |
| 685 |
#[inline] |
| 686 |
#[cold] |
| 687 |
pub fn format_err(args: Arguments) -> Error { |
| 688 |
#[cfg(anyhow_no_fmt_arguments_as_str)] |
| 689 |
let fmt_arguments_as_str = None::<&str>; |
| 690 |
#[cfg(not(anyhow_no_fmt_arguments_as_str))] |
| 691 |
let fmt_arguments_as_str = args.as_str(); |
| 692 |
|
| 693 |
if let Some(message) = fmt_arguments_as_str { |
| 694 |
// anyhow!("literal"), can downcast to &'static str |
| 695 |
Error::msg(message) |
| 696 |
} else { |
| 697 |
// anyhow!("interpolate {var}"), can downcast to String |
| 698 |
Error::msg(fmt::format(args)) |
| 699 |
} |
| 700 |
} |
| 701 |
|
| 702 |
#[doc(hidden)] |
| 703 |
#[inline] |
| 704 |
#[cold] |
| 705 |
#[must_use] |
| 706 |
pub fn must_use(error: Error) -> Error { |
| 707 |
error |
| 708 |
} |
| 709 |
|
| 710 |
#[doc(hidden)] |
| 711 |
#[inline] |
| 712 |
pub fn not(cond: impl Bool) -> bool { |
| 713 |
cond.not() |
| 714 |
} |
| 715 |
|
| 716 |
mod not { |
| 717 |
#[doc(hidden)] |
| 718 |
pub trait Bool { |
| 719 |
fn not(self) -> bool; |
| 720 |
} |
| 721 |
|
| 722 |
impl Bool for bool { |
| 723 |
#[inline] |
| 724 |
fn not(self) -> bool { |
| 725 |
!self |
| 726 |
} |
| 727 |
} |
| 728 |
|
| 729 |
impl Bool for &bool { |
| 730 |
#[inline] |
| 731 |
fn not(self) -> bool { |
| 732 |
!*self |
| 733 |
} |
| 734 |
} |
| 735 |
} |
| 736 |
} |