//! [![github]](https://github.com/dtolnay/anyhow) [![crates-io]](https://crates.io/crates/anyhow) [![docs-rs]](https://docs.rs/anyhow)

//!

//! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github

//! [crates-io]: https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=555555&logo=rust

//! [docs-rs]: https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs

//!

//! <br>

//!

//! This library provides [`anyhow::Error`][Error], a trait object based error

//! type for easy idiomatic error handling in Rust applications.

//!

//! <br>

//!

//! # Details

//!

//! - Use `Result<T, anyhow::Error>`, or equivalently `anyhow::Result<T>`, as

//!   the return type of any fallible function.

//!

//!   Within the function, use `?` to easily propagate any error that implements

//!   the `std::error::Error` trait.

//!

//!   ```

//!   # pub trait Deserialize {}

//!   #

//!   # mod serde_json {

//!   #     use super::Deserialize;

//!   #     use std::io;

//!   #

//!   #     pub fn from_str<T: Deserialize>(json: &str) -> io::Result<T> {

//!   #         unimplemented!()

//!   #     }

//!   # }

//!   #

//!   # struct ClusterMap;

//!   #

//!   # impl Deserialize for ClusterMap {}

//!   #

//!   use anyhow::Result;

//!

//!   fn get_cluster_info() -> Result<ClusterMap> {

//!       let config = std::fs::read_to_string("cluster.json")?;

//!       let map: ClusterMap = serde_json::from_str(&config)?;

//!       Ok(map)

//!   }

//!   #

//!   # fn main() {}

//!   ```

//!

//! - Attach context to help the person troubleshooting the error understand

//!   where things went wrong. A low-level error like "No such file or

//!   directory" can be annoying to debug without more context about what higher

//!   level step the application was in the middle of.

//!

//!   ```

//!   # struct It;

//!   #

//!   # impl It {

//!   #     fn detach(&self) -> Result<()> {

//!   #         unimplemented!()

//!   #     }

//!   # }

//!   #

//!   use anyhow::{Context, Result};

//!

//!   fn main() -> Result<()> {

//!       # return Ok(());

//!       #

//!       # const _: &str = stringify! {

//!       ...

//!       # };

//!       #

//!       # let it = It;

//!       # let path = "./path/to/instrs.json";

//!       #

//!       it.detach().context("Failed to detach the important thing")?;

//!

//!       let content = std::fs::read(path)

//!           .with_context(|| format!("Failed to read instrs from {}", path))?;

//!       #

//!       # const _: &str = stringify! {

//!       ...

//!       # };

//!       #

//!       # Ok(())

//!   }

//!   ```

//!

//!   ```console

//!   Error: Failed to read instrs from ./path/to/instrs.json

//!

//!   Caused by:

//!       No such file or directory (os error 2)

//!   ```

//!

//! - Downcasting is supported and can be by value, by shared reference, or by

//!   mutable reference as needed.

//!

//!   ```

//!   # use anyhow::anyhow;

//!   # use std::fmt::{self, Display};

//!   # use std::task::Poll;

//!   #

//!   # #[derive(Debug)]

//!   # enum DataStoreError {

//!   #     Censored(()),

//!   # }

//!   #

//!   # impl Display for DataStoreError {

//!   #     fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {

//!   #         unimplemented!()

//!   #     }

//!   # }

//!   #

//!   # impl std::error::Error for DataStoreError {}

//!   #

//!   # const REDACTED_CONTENT: () = ();

//!   #

//!   # let error = anyhow!("...");

//!   # let root_cause = &error;

//!   #

//!   # let ret =

//!   // If the error was caused by redaction, then return a

//!   // tombstone instead of the content.

//!   match root_cause.downcast_ref::<DataStoreError>() {

//!       Some(DataStoreError::Censored(_)) => Ok(Poll::Ready(REDACTED_CONTENT)),

//!       None => Err(error),

//!   }

//!   # ;

//!   ```

//!

//! - If using the nightly channel, or stable with `features = ["backtrace"]`, a

//!   backtrace is captured and printed with the error if the underlying error

//!   type does not already provide its own. In order to see backtraces, they

//!   must be enabled through the environment variables described in

//!   [`std::backtrace`]:

//!

//!   - If you want panics and errors to both have backtraces, set

//!     `RUST_BACKTRACE=1`;

//!   - If you want only errors to have backtraces, set `RUST_LIB_BACKTRACE=1`;

//!   - If you want only panics to have backtraces, set `RUST_BACKTRACE=1` and

//!     `RUST_LIB_BACKTRACE=0`.

//!

//!   The tracking issue for this feature is [rust-lang/rust#53487].

//!

//!   [`std::backtrace`]: https://doc.rust-lang.org/std/backtrace/index.html#environment-variables

//!   [rust-lang/rust#53487]: https://github.com/rust-lang/rust/issues/53487

//!

//! - Anyhow works with any error type that has an impl of `std::error::Error`,

//!   including ones defined in your crate. We do not bundle a `derive(Error)`

//!   macro but you can write the impls yourself or use a standalone macro like

//!   [thiserror].

//!

//!   [thiserror]: https://github.com/dtolnay/thiserror

//!

//!   ```

//!   use thiserror::Error;

//!

//!   #[derive(Error, Debug)]

//!   pub enum FormatError {

//!       #[error("Invalid header (expected {expected:?}, got {found:?})")]

//!       InvalidHeader {

//!           expected: String,

//!           found: String,

//!       },

//!       #[error("Missing attribute: {0}")]

//!       MissingAttribute(String),

//!   }

//!   ```

//!

//! - One-off error messages can be constructed using the `anyhow!` macro, which

//!   supports string interpolation and produces an `anyhow::Error`.

//!

//!   ```

//!   # use anyhow::{anyhow, Result};

//!   #

//!   # fn demo() -> Result<()> {

//!   #     let missing = "...";

//!   return Err(anyhow!("Missing attribute: {}", missing));

//!   #     Ok(())

//!   # }

//!   ```

//!

//!   A `bail!` macro is provided as a shorthand for the same early return.

//!

//!   ```

//!   # use anyhow::{bail, Result};

//!   #

//!   # fn demo() -> Result<()> {

//!   #     let missing = "...";

//!   bail!("Missing attribute: {}", missing);

//!   #     Ok(())

//!   # }

//!   ```

//!

//! <br>

//!

//! # No-std support

//!

//! In no_std mode, the same API is almost all available and works the same way.

//! To depend on Anyhow in no_std mode, disable our default enabled "std"

//! feature in Cargo.toml. A global allocator is required.

//!

//! ```toml

//! [dependencies]

//! anyhow = { version = "1.0", default-features = false }

//! ```

//!

//! Since the `?`-based error conversions would normally rely on the

//! `std::error::Error` trait which is only available through std, no_std mode

//! will require an explicit `.map_err(Error::msg)` when working with a

//! non-Anyhow error type inside a function that returns Anyhow's error type.

#![doc(html_root_url = "https://docs.rs/anyhow/1.0.75")]

#![cfg_attr(backtrace, feature(error_generic_member_access))]

#![cfg_attr(doc_cfg, feature(doc_cfg))]

#![cfg_attr(not(feature = "std"), no_std)]

#![deny(dead_code, unused_imports, unused_mut)]

#![allow(

    clippy::doc_markdown,

    clippy::enum_glob_use,

    clippy::explicit_auto_deref,

    clippy::extra_unused_type_parameters,

    clippy::let_underscore_untyped,

    clippy::missing_errors_doc,

    clippy::missing_panics_doc,

    clippy::module_name_repetitions,

    clippy::must_use_candidate,

    clippy::needless_doctest_main,

    clippy::new_ret_no_self,

    clippy::redundant_else,

    clippy::return_self_not_must_use,

    clippy::unused_self,

    clippy::used_underscore_binding,

    clippy::wildcard_imports,

    clippy::wrong_self_convention

)]

extern crate alloc;

#[macro_use]

mod backtrace;

mod chain;

mod context;

mod ensure;

mod error;

mod fmt;

mod kind;

mod macros;

mod ptr;

mod wrapper;

use crate::error::ErrorImpl;

use crate::ptr::Own;

use core::fmt::Display;

#[cfg(not(feature = "std"))]

use core::fmt::Debug;

#[cfg(feature = "std")]

use std::error::Error as StdError;

#[cfg(not(feature = "std"))]

trait StdError: Debug + Display {

    fn source(&self) -> Option<&(dyn StdError + 'static)> {

        None

    }

}

#[doc(no_inline)]

pub use anyhow as format_err;

/// The `Error` type, a wrapper around a dynamic error type.

///

/// `Error` works a lot like `Box<dyn std::error::Error>`, but with these

/// differences:

///

/// - `Error` requires that the error is `Send`, `Sync`, and `'static`.

/// - `Error` guarantees that a backtrace is available, even if the underlying

///   error type does not provide one.

/// - `Error` is represented as a narrow pointer — exactly one word in

///   size instead of two.

///

/// <br>

///

/// # Display representations

///

/// When you print an error object using "{}" or to_string(), only the outermost

/// underlying error or context is printed, not any of the lower level causes.

/// This is exactly as if you had called the Display impl of the error from

/// which you constructed your anyhow::Error.

///

/// ```console

/// Failed to read instrs from ./path/to/instrs.json

/// ```

///

/// To print causes as well using anyhow's default formatting of causes, use the

/// alternate selector "{:#}".

///

/// ```console

/// Failed to read instrs from ./path/to/instrs.json: No such file or directory (os error 2)

/// ```

///

/// The Debug format "{:?}" includes your backtrace if one was captured. Note

/// that this is the representation you get by default if you return an error

/// from `fn main` instead of printing it explicitly yourself.

///

/// ```console

/// Error: Failed to read instrs from ./path/to/instrs.json

///

/// Caused by:

///     No such file or directory (os error 2)

/// ```

///

/// and if there is a backtrace available:

///

/// ```console

/// Error: Failed to read instrs from ./path/to/instrs.json

///

/// Caused by:

///     No such file or directory (os error 2)

///

/// Stack backtrace:

///    0: <E as anyhow::context::ext::StdError>::ext_context

///              at /git/anyhow/src/backtrace.rs:26

///    1: core::result::Result<T,E>::map_err

///              at /git/rustc/src/libcore/result.rs:596

///    2: anyhow::context::<impl anyhow::Context<T,E> for core::result::Result<T,E>>::with_context

///              at /git/anyhow/src/context.rs:58

///    3: testing::main

///              at src/main.rs:5

///    4: std::rt::lang_start

///              at /git/rustc/src/libstd/rt.rs:61

///    5: main

///    6: __libc_start_main

///    7: _start

/// ```

///

/// To see a conventional struct-style Debug representation, use "{:#?}".

///

/// ```console

/// Error {

///     context: "Failed to read instrs from ./path/to/instrs.json",

///     source: Os {

///         code: 2,

///         kind: NotFound,

///         message: "No such file or directory",

///     },

/// }

/// ```

///

/// If none of the built-in representations are appropriate and you would prefer

/// to render the error and its cause chain yourself, it can be done something

/// like this:

///

/// ```

/// use anyhow::{Context, Result};

///

/// fn main() {

///     if let Err(err) = try_main() {

///         eprintln!("ERROR: {}", err);

///         err.chain().skip(1).for_each(|cause| eprintln!("because: {}", cause));

///         std::process::exit(1);

///     }

/// }

///

/// fn try_main() -> Result<()> {

///     # const IGNORE: &str = stringify! {

///     ...

///     # };

///     # Ok(())

/// }

/// ```

#[cfg_attr(not(doc), repr(transparent))]

pub struct Error {

    inner: Own<ErrorImpl>,

}

/// Iterator of a chain of source errors.

///

/// This type is the iterator returned by [`Error::chain`].

///

/// # Example

///

/// ```

/// use anyhow::Error;

/// use std::io;

///

/// pub fn underlying_io_error_kind(error: &Error) -> Option<io::ErrorKind> {

///     for cause in error.chain() {

///         if let Some(io_error) = cause.downcast_ref::<io::Error>() {

///             return Some(io_error.kind());

///         }

///     }

///     None

/// }

/// ```

#[cfg(feature = "std")]

#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]

#[derive(Clone)]

pub struct Chain<'a> {

    state: crate::chain::ChainState<'a>,

}

/// `Result<T, Error>`

///

/// This is a reasonable return type to use throughout your application but also

/// for `fn main`; if you do, failures will be printed along with any

/// [context][Context] and a backtrace if one was captured.

///

/// `anyhow::Result` may be used with one *or* two type parameters.

///

/// ```rust

/// use anyhow::Result;

///

/// # const IGNORE: &str = stringify! {

/// fn demo1() -> Result<T> {...}

///            // ^ equivalent to std::result::Result<T, anyhow::Error>

///

/// fn demo2() -> Result<T, OtherError> {...}

///            // ^ equivalent to std::result::Result<T, OtherError>

/// # };

/// ```

///

/// # Example

///

/// ```

/// # pub trait Deserialize {}

/// #

/// # mod serde_json {

/// #     use super::Deserialize;

/// #     use std::io;

/// #

/// #     pub fn from_str<T: Deserialize>(json: &str) -> io::Result<T> {

/// #         unimplemented!()

/// #     }

/// # }

/// #

/// # #[derive(Debug)]

/// # struct ClusterMap;

/// #

/// # impl Deserialize for ClusterMap {}

/// #

/// use anyhow::Result;

///

/// fn main() -> Result<()> {

///     # return Ok(());

///     let config = std::fs::read_to_string("cluster.json")?;

///     let map: ClusterMap = serde_json::from_str(&config)?;

///     println!("cluster info: {:#?}", map);

///     Ok(())

/// }

/// ```

pub type Result<T, E = Error> = core::result::Result<T, E>;

/// Provides the `context` method for `Result`.

///

/// This trait is sealed and cannot be implemented for types outside of

/// `anyhow`.

///

/// <br>

///

/// # Example

///

/// ```

/// use anyhow::{Context, Result};

/// use std::fs;

/// use std::path::PathBuf;

///

/// pub struct ImportantThing {

///     path: PathBuf,

/// }

///

/// impl ImportantThing {

///     # const IGNORE: &'static str = stringify! {

///     pub fn detach(&mut self) -> Result<()> {...}

///     # };

///     # fn detach(&mut self) -> Result<()> {

///     #     unimplemented!()

///     # }

/// }

///

/// pub fn do_it(mut it: ImportantThing) -> Result<Vec<u8>> {

///     it.detach().context("Failed to detach the important thing")?;

///

///     let path = &it.path;

///     let content = fs::read(path)

///         .with_context(|| format!("Failed to read instrs from {}", path.display()))?;

///

///     Ok(content)

/// }

/// ```

///

/// When printed, the outermost context would be printed first and the lower

/// level underlying causes would be enumerated below.

///

/// ```console

/// Error: Failed to read instrs from ./path/to/instrs.json

///

/// Caused by:

///     No such file or directory (os error 2)

/// ```

///

/// Refer to the [Display representations] documentation for other forms in

/// which this context chain can be rendered.

///

/// [Display representations]: Error#display-representations

///

/// <br>

///

/// # Effect on downcasting

///

/// After attaching context of type `C` onto an error of type `E`, the resulting

/// `anyhow::Error` may be downcast to `C` **or** to `E`.

///

/// That is, in codebases that rely on downcasting, Anyhow's context supports

/// both of the following use cases:

///

///   - **Attaching context whose type is insignificant onto errors whose type

///     is used in downcasts.**

///

///     In other error libraries whose context is not designed this way, it can

///     be risky to introduce context to existing code because new context might

///     break existing working downcasts. In Anyhow, any downcast that worked

///     before adding context will continue to work after you add a context, so

///     you should freely add human-readable context to errors wherever it would

///     be helpful.

///

///     ```

///     # use anyhow::bail;

///     # use thiserror::Error;

///     #

///     # #[derive(Error, Debug)]

///     # #[error("???")]

///     # struct SuspiciousError;

///     #

///     # fn helper() -> Result<()> {

///     #     bail!(SuspiciousError);

///     # }

///     #

///     use anyhow::{Context, Result};

///

///     fn do_it() -> Result<()> {

///         helper().context("Failed to complete the work")?;

///         # const IGNORE: &str = stringify! {

///         ...

///         # };

///         # unreachable!()

///     }

///

///     fn main() {

///         let err = do_it().unwrap_err();

///         if let Some(e) = err.downcast_ref::<SuspiciousError>() {

///             // If helper() returned SuspiciousError, this downcast will

///             // correctly succeed even with the context in between.

///             # return;

///         }

///         # panic!("expected downcast to succeed");

///     }

///     ```

///

///   - **Attaching context whose type is used in downcasts onto errors whose

///     type is insignificant.**

///

///     Some codebases prefer to use machine-readable context to categorize

///     lower level errors in a way that will be actionable to higher levels of

///     the application.

///

///     ```

///     # use anyhow::bail;

///     # use thiserror::Error;

///     #

///     # #[derive(Error, Debug)]

///     # #[error("???")]

///     # struct HelperFailed;

///     #

///     # fn helper() -> Result<()> {

///     #     bail!("no such file or directory");

///     # }

///     #

///     use anyhow::{Context, Result};

///

///     fn do_it() -> Result<()> {

///         helper().context(HelperFailed)?;

///         # const IGNORE: &str = stringify! {

///         ...

///         # };

///         # unreachable!()

///     }

///

///     fn main() {

///         let err = do_it().unwrap_err();

///         if let Some(e) = err.downcast_ref::<HelperFailed>() {

///             // If helper failed, this downcast will succeed because

///             // HelperFailed is the context that has been attached to

///             // that error.

///             # return;

///         }

///         # panic!("expected downcast to succeed");

///     }

///     ```

pub trait Context<T, E>: context::private::Sealed {

    /// Wrap the error value with additional context.

    fn context<C>(self, context: C) -> Result<T, Error>

    where

        C: Display + Send + Sync + 'static;

    /// Wrap the error value with additional context that is evaluated lazily

    /// only once an error does occur.

    fn with_context<C, F>(self, f: F) -> Result<T, Error>

    where

        C: Display + Send + Sync + 'static,

        F: FnOnce() -> C;

}

/// Equivalent to Ok::<_, anyhow::Error>(value).

///

/// This simplifies creation of an anyhow::Result in places where type inference

/// cannot deduce the `E` type of the result — without needing to write

/// `Ok::<_, anyhow::Error>(value)`.

///

/// One might think that `anyhow::Result::Ok(value)` would work in such cases

/// but it does not.

///

/// ```console

/// error[E0282]: type annotations needed for `std::result::Result<i32, E>`

///   --> src/main.rs:11:13

///    |

/// 11 |     let _ = anyhow::Result::Ok(1);

///    |         -   ^^^^^^^^^^^^^^^^^^ cannot infer type for type parameter `E` declared on the enum `Result`

///    |         |

///    |         consider giving this pattern the explicit type `std::result::Result<i32, E>`, where the type parameter `E` is specified

/// ```

#[allow(non_snake_case)]

pub fn Ok<T>(t: T) -> Result<T> {

    Result::Ok(t)

}

// Not public API. Referenced by macro-generated code.

#[doc(hidden)]

pub mod __private {

    use crate::Error;

    use alloc::fmt;

    use core::fmt::Arguments;

    #[doc(hidden)]

    pub use crate::ensure::{BothDebug, NotBothDebug};

    #[doc(hidden)]

    pub use alloc::format;

    #[doc(hidden)]

    pub use core::result::Result::Err;

    #[doc(hidden)]

    pub use core::{concat, format_args, stringify};

    #[doc(hidden)]

    pub mod kind {

        #[doc(hidden)]

        pub use crate::kind::{AdhocKind, TraitKind};

        #[cfg(feature = "std")]

        #[doc(hidden)]

        pub use crate::kind::BoxedKind;

    }

    #[doc(hidden)]

    #[inline]

    #[cold]

    pub fn format_err(args: Arguments) -> Error {

        #[cfg(anyhow_no_fmt_arguments_as_str)]

        let fmt_arguments_as_str = None::<&str>;

        #[cfg(not(anyhow_no_fmt_arguments_as_str))]

        let fmt_arguments_as_str = args.as_str();

        if let Some(message) = fmt_arguments_as_str {

            // anyhow!("literal"), can downcast to &'static str

            Error::msg(message)

        } else {

            // anyhow!("interpolate {var}"), can downcast to String

            Error::msg(fmt::format(args))

        }

    }

    #[doc(hidden)]

    #[inline]

    #[cold]

    #[must_use]

    pub fn must_use(error: Error) -> Error {

        error

    }

}