//! # SNAFU
//!
//! ## Design philosophy
//!
//! SNAFU believes that it should be easy to bin one underlying error
//! type (such as [`io::Error`](std::io::Error)) into multiple
//! domain-specific errors while also optionally adding contextual
//! information.
//!
//! SNAFU is designed to be used in libraries, not just end-user applications.
//!
//! ## Quick example
//!
//! This example mimics a (very poor) authentication process that
//! opens a file, writes to a file, and checks the user's ID. While
//! two of our operations involve an [`io::Error`](std::io::Error),
//! these are different conceptual errors to us.
//!
//! SNAFU creates *context selectors* mirroring each error
//! variant. These are used with the [`context`](ResultExt::context)
//! method to provide ergonomic error handling.
//!
//! ```rust
//! use snafu::{Snafu, ResultExt};
//! use std::{fs, path::{Path, PathBuf}};
//!
//! #[derive(Debug, Snafu)]
//! enum Error {
//!     #[snafu_display("Could not open config from {}: {}", "filename.display()", "source")]
//!     OpenConfig { filename: PathBuf, source: std::io::Error },
//!     #[snafu_display("Could not save config to {}: {}", "filename.display()", "source")]
//!     SaveConfig { filename: PathBuf, source: std::io::Error },
//!     #[snafu_display("The user id {} is invalid", "user_id")]
//!     UserIdInvalid { user_id: i32 },
//! }
//!
//! type Result<T, E = Error> = std::result::Result<T, E>;
//!
//! fn log_in_user<P>(config_root: P, user_id: i32) -> Result<()>
//! where
//!     P: AsRef<Path>,
//! {
//!     let config_root = config_root.as_ref();
//!     let filename = &config_root.join("config.toml");
//!
//!     let config = fs::read(filename).context(OpenConfig { filename })?;
//!     // Perform updates to config
//!     fs::write(filename, config).context(SaveConfig { filename })?;
//!
//!     if user_id != 42 {
//!         return Err(Error::UserIdInvalid { user_id });
//!     }
//!
//!     Ok(())
//! }
//! ```
//!
//! ## The `Snafu` macro
//!
//! This procedural macro implements the [`Error`](std::error::Error)
//! trait and produces the corresponding context selectors.
//!
//! ### Detailed example
//!
//! ```rust
//! use snafu::Snafu;
//! use std::path::PathBuf;
//!
//! #[derive(Debug, Snafu)]
//! enum Error {
//!     #[snafu_display("Could not open config at {}: {}", "filename.display()", "source")]
//!     OpenConfig { filename: PathBuf, source: std::io::Error },
//!     #[snafu_display("Could not open config: {}", "source")]
//!     SaveConfig { source: std::io::Error },
//! }
//! ```
//!
//! #### Generated code
//!
//! This will generate two additional types called *context
//! selectors*:
//!
//! ```rust,ignore
//! struct OpenConfig<P> { filename: P }
//! struct SaveConfig<P> { filename: P }
//! ```
//!
//! Notably:
//!
//! 1. One struct is created for each enum variant.
//! 1. The name of the struct is the same as the enum variant's name.
//! 1. The `source` field has been removed; the library will
//! automatically handle this for you.
//! 1. Each field's type has been replaced with a generic type.
//!
//! Each context selector will have an implementation of
//! [`From`](std::convert::From) for a `snafu::Context`:
//!
//! ```rust,ignore
//! impl<P> From<Context<Error, OpenConfig<T0>>> for Error
//! where
//!     P: Into<PathBuf>,
//! ```

pub use snafu_derive::Snafu;

/// A combination of an underlying error and additional information
/// about the error. It is not expected for users of this crate to
/// interact with this type.
pub struct Context<E, C> {
    /// The underlying error
    pub error: E,
    /// Information that provides a context for the underlying error
    pub context: C,
}

/// Additions to [`Result`](std::result::Result).
pub trait ResultExt<T, E> {
    /// Extend a `Result` with additional context-sensitive information.
    ///
    /// ```rust
    /// use snafu::{Snafu, ResultExt};
    ///
    /// #[derive(Debug, Snafu)]
    /// enum Error {
    ///     Authenticating { user_name: String, user_id: i32, source: ApiError },
    /// }
    ///
    /// fn example() -> Result<(), Error> {
    ///     another_function().context(Authenticating { user_name: "admin", user_id: 42 })?;
    ///     Ok(())
    /// }
    ///
    /// # type ApiError = Box<dyn std::error::Error>;
    /// fn another_function() -> Result<i32, ApiError> {
    ///     /* ... */
    /// # Ok(42)
    /// }
    /// ```
    ///
    /// Note that the [`From`](std::convert::From) implementation
    /// generated by the macro will call
    /// [`Into::into`](std::convert::Into::into) on each field, so the
    /// types are not required to exactly match.
    fn context<C>(self, context: C) -> Result<T, Context<E, C>>;

    /// Extend a `Result` with lazily-generated context-sensitive information.
    ///
    /// ```rust
    /// use snafu::{Snafu, ResultExt};
    ///
    /// #[derive(Debug, Snafu)]
    /// enum Error {
    ///     Authenticating { user_name: String, user_id: i32, source: ApiError },
    /// }
    ///
    /// fn example() -> Result<(), Error> {
    ///     another_function().with_context(|| Authenticating {
    ///         user_name: "admin".to_string(),
    ///         user_id: 42,
    ///     })?;
    ///     Ok(())
    /// }
    ///
    /// # type ApiError = std::io::Error;
    /// fn another_function() -> Result<i32, ApiError> {
    ///     /* ... */
    /// # Ok(42)
    /// }
    /// ```
    ///
    /// Note that this *may not* be needed in many cases because the
    /// [`From`](std::convert::From) implementation generated by the
    /// macro will call [`Into::into`](std::convert::Into::into) on
    /// each field.
    fn with_context<C>(self, context: impl FnOnce() -> C) -> Result<T, Context<E, C>>;
}

impl<T, E> ResultExt<T, E> for std::result::Result<T, E> {
    fn context<C>(self, context: C) -> Result<T, Context<E, C>> {
        self.map_err(|error| Context { error, context })
    }

    fn with_context<C>(self, context: impl FnOnce() -> C) -> Result<T, Context<E, C>> {
        self.map_err(|error| {
            let context = context();
            Context { error, context }
        })
    }
}