anyhow/lib.rs
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.99")]
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))]
248compile_error!("Build script probe failed to compile.");
249
250extern crate alloc;
251
252#[cfg(feature = "std")]
253extern crate std;
254
255#[macro_use]
256mod backtrace;
257mod chain;
258mod context;
259mod ensure;
260mod error;
261mod fmt;
262mod kind;
263mod macros;
264#[cfg(error_generic_member_access)]
265mod nightly;
266mod ptr;
267mod wrapper;
268
269use crate::error::ErrorImpl;
270use crate::ptr::Own;
271use core::fmt::Display;
272
273#[cfg(all(not(feature = "std"), anyhow_no_core_error))]
274use core::fmt::Debug;
275
276#[cfg(feature = "std")]
277use std::error::Error as StdError;
278
279#[cfg(not(any(feature = "std", anyhow_no_core_error)))]
280use core::error::Error as StdError;
281
282#[cfg(all(not(feature = "std"), anyhow_no_core_error))]
283trait StdError: Debug + Display {
284 fn source(&self) -> Option<&(dyn StdError + 'static)> {
285 None
286 }
287}
288
289#[doc(no_inline)]
290pub 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)]
394pub 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)]
419pub 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/// ```
472pub 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/// ```
620pub 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)]
653pub 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)]
659pub 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}