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&logoColor=white&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K 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 the nightly channel, 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 //! The tracking issue for this feature is [rust-lang/rust#53487]. 143 //! 144 //! [`std::backtrace`]: https://doc.rust-lang.org/std/backtrace/index.html#environment-variables 145 //! [rust-lang/rust#53487]: https://github.com/rust-lang/rust/issues/53487 146 //! 147 //! - Anyhow works with any error type that has an impl of `std::error::Error`, 148 //! including ones defined in your crate. We do not bundle a `derive(Error)` 149 //! macro but you can write the impls yourself or use a standalone macro like 150 //! [thiserror]. 151 //! 152 //! [thiserror]: https://github.com/dtolnay/thiserror 153 //! 154 //! ``` 155 //! use thiserror::Error; 156 //! 157 //! #[derive(Error, Debug)] 158 //! pub enum FormatError { 159 //! #[error("Invalid header (expected {expected:?}, got {found:?})")] 160 //! InvalidHeader { 161 //! expected: String, 162 //! found: String, 163 //! }, 164 //! #[error("Missing attribute: {0}")] 165 //! MissingAttribute(String), 166 //! } 167 //! ``` 168 //! 169 //! - One-off error messages can be constructed using the `anyhow!` macro, which 170 //! supports string interpolation and produces an `anyhow::Error`. 171 //! 172 //! ``` 173 //! # use anyhow::{anyhow, Result}; 174 //! # 175 //! # fn demo() -> Result<()> { 176 //! # let missing = "..."; 177 //! return Err(anyhow!("Missing attribute: {}", missing)); 178 //! # Ok(()) 179 //! # } 180 //! ``` 181 //! 182 //! <br> 183 //! 184 //! # No-std support 185 //! 186 //! In no_std mode, the same API is almost all available and works the same way. 187 //! To depend on Anyhow in no_std mode, disable our default enabled "std" 188 //! feature in Cargo.toml. A global allocator is required. 189 //! 190 //! ```toml 191 //! [dependencies] 192 //! anyhow = { version = "1.0", default-features = false } 193 //! ``` 194 //! 195 //! Since the `?`-based error conversions would normally rely on the 196 //! `std::error::Error` trait which is only available through std, no_std mode 197 //! will require an explicit `.map_err(Error::msg)` when working with a 198 //! non-Anyhow error type inside a function that returns Anyhow's error type. 199 200 #![doc(html_root_url = "https://docs.rs/anyhow/1.0.32")] 201 #![cfg_attr(backtrace, feature(backtrace))] 202 #![cfg_attr(doc_cfg, feature(doc_cfg))] 203 #![cfg_attr(not(feature = "std"), no_std)] 204 #![allow( 205 clippy::needless_doctest_main, 206 clippy::new_ret_no_self, 207 clippy::wrong_self_convention 208 )] 209 210 mod alloc { 211 #[cfg(not(feature = "std"))] 212 extern crate alloc; 213 214 #[cfg(not(feature = "std"))] 215 pub use alloc::boxed::Box; 216 217 #[cfg(feature = "std")] 218 pub use std::boxed::Box; 219 } 220 221 #[macro_use] 222 mod backtrace; 223 mod chain; 224 mod context; 225 mod error; 226 mod fmt; 227 mod kind; 228 mod macros; 229 mod wrapper; 230 231 use crate::alloc::Box; 232 use crate::error::ErrorImpl; 233 use core::fmt::Display; 234 use core::mem::ManuallyDrop; 235 236 #[cfg(not(feature = "std"))] 237 use core::fmt::Debug; 238 239 #[cfg(feature = "std")] 240 use std::error::Error as StdError; 241 242 #[cfg(not(feature = "std"))] 243 trait StdError: Debug + Display { source(&self) -> Option<&(dyn StdError + 'static)>244 fn source(&self) -> Option<&(dyn StdError + 'static)> { 245 None 246 } 247 } 248 249 pub use anyhow as format_err; 250 251 /// The `Error` type, a wrapper around a dynamic error type. 252 /// 253 /// `Error` works a lot like `Box<dyn std::error::Error>`, but with these 254 /// differences: 255 /// 256 /// - `Error` requires that the error is `Send`, `Sync`, and `'static`. 257 /// - `Error` guarantees that a backtrace is available, even if the underlying 258 /// error type does not provide one. 259 /// - `Error` is represented as a narrow pointer — exactly one word in 260 /// size instead of two. 261 /// 262 /// <br> 263 /// 264 /// # Display representations 265 /// 266 /// When you print an error object using "{}" or to_string(), only the outermost 267 /// underlying error or context is printed, not any of the lower level causes. 268 /// This is exactly as if you had called the Display impl of the error from 269 /// which you constructed your anyhow::Error. 270 /// 271 /// ```console 272 /// Failed to read instrs from ./path/to/instrs.json 273 /// ``` 274 /// 275 /// To print causes as well using anyhow's default formatting of causes, use the 276 /// alternate selector "{:#}". 277 /// 278 /// ```console 279 /// Failed to read instrs from ./path/to/instrs.json: No such file or directory (os error 2) 280 /// ``` 281 /// 282 /// The Debug format "{:?}" includes your backtrace if one was captured. Note 283 /// that this is the representation you get by default if you return an error 284 /// from `fn main` instead of printing it explicitly yourself. 285 /// 286 /// ```console 287 /// Error: Failed to read instrs from ./path/to/instrs.json 288 /// 289 /// Caused by: 290 /// No such file or directory (os error 2) 291 /// ``` 292 /// 293 /// and if there is a backtrace available: 294 /// 295 /// ```console 296 /// Error: Failed to read instrs from ./path/to/instrs.json 297 /// 298 /// Caused by: 299 /// No such file or directory (os error 2) 300 /// 301 /// Stack backtrace: 302 /// 0: <E as anyhow::context::ext::StdError>::ext_context 303 /// at /git/anyhow/src/backtrace.rs:26 304 /// 1: core::result::Result<T,E>::map_err 305 /// at /git/rustc/src/libcore/result.rs:596 306 /// 2: anyhow::context::<impl anyhow::Context<T,E> for core::result::Result<T,E>>::with_context 307 /// at /git/anyhow/src/context.rs:58 308 /// 3: testing::main 309 /// at src/main.rs:5 310 /// 4: std::rt::lang_start 311 /// at /git/rustc/src/libstd/rt.rs:61 312 /// 5: main 313 /// 6: __libc_start_main 314 /// 7: _start 315 /// ``` 316 /// 317 /// To see a conventional struct-style Debug representation, use "{:#?}". 318 /// 319 /// ```console 320 /// Error { 321 /// context: "Failed to read instrs from ./path/to/instrs.json", 322 /// source: Os { 323 /// code: 2, 324 /// kind: NotFound, 325 /// message: "No such file or directory", 326 /// }, 327 /// } 328 /// ``` 329 /// 330 /// If none of the built-in representations are appropriate and you would prefer 331 /// to render the error and its cause chain yourself, it can be done something 332 /// like this: 333 /// 334 /// ``` 335 /// use anyhow::{Context, Result}; 336 /// 337 /// fn main() { 338 /// if let Err(err) = try_main() { 339 /// eprintln!("ERROR: {}", err); 340 /// err.chain().skip(1).for_each(|cause| eprintln!("because: {}", cause)); 341 /// std::process::exit(1); 342 /// } 343 /// } 344 /// 345 /// fn try_main() -> Result<()> { 346 /// # const IGNORE: &str = stringify! { 347 /// ... 348 /// # }; 349 /// # Ok(()) 350 /// } 351 /// ``` 352 pub struct Error { 353 inner: ManuallyDrop<Box<ErrorImpl<()>>>, 354 } 355 356 /// Iterator of a chain of source errors. 357 /// 358 /// This type is the iterator returned by [`Error::chain`]. 359 /// 360 /// # Example 361 /// 362 /// ``` 363 /// use anyhow::Error; 364 /// use std::io; 365 /// 366 /// pub fn underlying_io_error_kind(error: &Error) -> Option<io::ErrorKind> { 367 /// for cause in error.chain() { 368 /// if let Some(io_error) = cause.downcast_ref::<io::Error>() { 369 /// return Some(io_error.kind()); 370 /// } 371 /// } 372 /// None 373 /// } 374 /// ``` 375 #[cfg(feature = "std")] 376 #[derive(Clone)] 377 pub struct Chain<'a> { 378 state: crate::chain::ChainState<'a>, 379 } 380 381 /// `Result<T, Error>` 382 /// 383 /// This is a reasonable return type to use throughout your application but also 384 /// for `fn main`; if you do, failures will be printed along with any 385 /// [context][Context] and a backtrace if one was captured. 386 /// 387 /// `anyhow::Result` may be used with one *or* two type parameters. 388 /// 389 /// ```rust 390 /// use anyhow::Result; 391 /// 392 /// # const IGNORE: &str = stringify! { 393 /// fn demo1() -> Result<T> {...} 394 /// // ^ equivalent to std::result::Result<T, anyhow::Error> 395 /// 396 /// fn demo2() -> Result<T, OtherError> {...} 397 /// // ^ equivalent to std::result::Result<T, OtherError> 398 /// # }; 399 /// ``` 400 /// 401 /// # Example 402 /// 403 /// ``` 404 /// # pub trait Deserialize {} 405 /// # 406 /// # mod serde_json { 407 /// # use super::Deserialize; 408 /// # use std::io; 409 /// # 410 /// # pub fn from_str<T: Deserialize>(json: &str) -> io::Result<T> { 411 /// # unimplemented!() 412 /// # } 413 /// # } 414 /// # 415 /// # #[derive(Debug)] 416 /// # struct ClusterMap; 417 /// # 418 /// # impl Deserialize for ClusterMap {} 419 /// # 420 /// use anyhow::Result; 421 /// 422 /// fn main() -> Result<()> { 423 /// # return Ok(()); 424 /// let config = std::fs::read_to_string("cluster.json")?; 425 /// let map: ClusterMap = serde_json::from_str(&config)?; 426 /// println!("cluster info: {:#?}", map); 427 /// Ok(()) 428 /// } 429 /// ``` 430 pub type Result<T, E = Error> = core::result::Result<T, E>; 431 432 /// Provides the `context` method for `Result`. 433 /// 434 /// This trait is sealed and cannot be implemented for types outside of 435 /// `anyhow`. 436 /// 437 /// <br> 438 /// 439 /// # Example 440 /// 441 /// ``` 442 /// use anyhow::{Context, Result}; 443 /// use std::fs; 444 /// use std::path::PathBuf; 445 /// 446 /// pub struct ImportantThing { 447 /// path: PathBuf, 448 /// } 449 /// 450 /// impl ImportantThing { 451 /// # const IGNORE: &'static str = stringify! { 452 /// pub fn detach(&mut self) -> Result<()> {...} 453 /// # }; 454 /// # fn detach(&mut self) -> Result<()> { 455 /// # unimplemented!() 456 /// # } 457 /// } 458 /// 459 /// pub fn do_it(mut it: ImportantThing) -> Result<Vec<u8>> { 460 /// it.detach().context("Failed to detach the important thing")?; 461 /// 462 /// let path = &it.path; 463 /// let content = fs::read(path) 464 /// .with_context(|| format!("Failed to read instrs from {}", path.display()))?; 465 /// 466 /// Ok(content) 467 /// } 468 /// ``` 469 /// 470 /// When printed, the outermost context would be printed first and the lower 471 /// level underlying causes would be enumerated below. 472 /// 473 /// ```console 474 /// Error: Failed to read instrs from ./path/to/instrs.json 475 /// 476 /// Caused by: 477 /// No such file or directory (os error 2) 478 /// ``` 479 /// 480 /// <br> 481 /// 482 /// # Effect on downcasting 483 /// 484 /// After attaching context of type `C` onto an error of type `E`, the resulting 485 /// `anyhow::Error` may be downcast to `C` **or** to `E`. 486 /// 487 /// That is, in codebases that rely on downcasting, Anyhow's context supports 488 /// both of the following use cases: 489 /// 490 /// - **Attaching context whose type is insignificant onto errors whose type 491 /// is used in downcasts.** 492 /// 493 /// In other error libraries whose context is not designed this way, it can 494 /// be risky to introduce context to existing code because new context might 495 /// break existing working downcasts. In Anyhow, any downcast that worked 496 /// before adding context will continue to work after you add a context, so 497 /// you should freely add human-readable context to errors wherever it would 498 /// be helpful. 499 /// 500 /// ``` 501 /// # use anyhow::bail; 502 /// # use thiserror::Error; 503 /// # 504 /// # #[derive(Error, Debug)] 505 /// # #[error("???")] 506 /// # struct SuspiciousError; 507 /// # 508 /// # fn helper() -> Result<()> { 509 /// # bail!(SuspiciousError); 510 /// # } 511 /// # 512 /// use anyhow::{Context, Result}; 513 /// 514 /// fn do_it() -> Result<()> { 515 /// helper().context("Failed to complete the work")?; 516 /// # const IGNORE: &str = stringify! { 517 /// ... 518 /// # }; 519 /// # unreachable!() 520 /// } 521 /// 522 /// fn main() { 523 /// let err = do_it().unwrap_err(); 524 /// if let Some(e) = err.downcast_ref::<SuspiciousError>() { 525 /// // If helper() returned SuspiciousError, this downcast will 526 /// // correctly succeed even with the context in between. 527 /// # return; 528 /// } 529 /// # panic!("expected downcast to succeed"); 530 /// } 531 /// ``` 532 /// 533 /// - **Attaching context whose type is used in downcasts onto errors whose 534 /// type is insignificant.** 535 /// 536 /// Some codebases prefer to use machine-readable context to categorize 537 /// lower level errors in a way that will be actionable to higher levels of 538 /// the application. 539 /// 540 /// ``` 541 /// # use anyhow::bail; 542 /// # use thiserror::Error; 543 /// # 544 /// # #[derive(Error, Debug)] 545 /// # #[error("???")] 546 /// # struct HelperFailed; 547 /// # 548 /// # fn helper() -> Result<()> { 549 /// # bail!("no such file or directory"); 550 /// # } 551 /// # 552 /// use anyhow::{Context, Result}; 553 /// 554 /// fn do_it() -> Result<()> { 555 /// helper().context(HelperFailed)?; 556 /// # const IGNORE: &str = stringify! { 557 /// ... 558 /// # }; 559 /// # unreachable!() 560 /// } 561 /// 562 /// fn main() { 563 /// let err = do_it().unwrap_err(); 564 /// if let Some(e) = err.downcast_ref::<HelperFailed>() { 565 /// // If helper failed, this downcast will succeed because 566 /// // HelperFailed is the context that has been attached to 567 /// // that error. 568 /// # return; 569 /// } 570 /// # panic!("expected downcast to succeed"); 571 /// } 572 /// ``` 573 pub trait Context<T, E>: context::private::Sealed { 574 /// Wrap the error value with additional context. context<C>(self, context: C) -> Result<T, Error> where C: Display + Send + Sync + 'static575 fn context<C>(self, context: C) -> Result<T, Error> 576 where 577 C: Display + Send + Sync + 'static; 578 579 /// Wrap the error value with additional context that is evaluated lazily 580 /// only once an error does occur. with_context<C, F>(self, f: F) -> Result<T, Error> where C: Display + Send + Sync + 'static, F: FnOnce() -> C581 fn with_context<C, F>(self, f: F) -> Result<T, Error> 582 where 583 C: Display + Send + Sync + 'static, 584 F: FnOnce() -> C; 585 } 586 587 // Not public API. Referenced by macro-generated code. 588 #[doc(hidden)] 589 pub mod private { 590 use crate::Error; 591 use core::fmt::{Debug, Display}; 592 593 #[cfg(backtrace)] 594 use std::backtrace::Backtrace; 595 596 pub use core::result::Result::Err; 597 598 #[doc(hidden)] 599 pub mod kind { 600 pub use crate::kind::{AdhocKind, TraitKind}; 601 602 #[cfg(feature = "std")] 603 pub use crate::kind::BoxedKind; 604 } 605 new_adhoc<M>(message: M) -> Error where M: Display + Debug + Send + Sync + 'static,606 pub fn new_adhoc<M>(message: M) -> Error 607 where 608 M: Display + Debug + Send + Sync + 'static, 609 { 610 Error::from_adhoc(message, backtrace!()) 611 } 612 } 613