//! # 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 {
//!         UserIdInvalid { user_id }.fail()?;
//!     }
//!
//!     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 },
//!     #[snafu_display("The user id {} is invalid", "user_id")]
//!     UserIdInvalid { user_id: i32 },
//! }
//! ```
//!
//! #### Generated code
//!
//! This will generate three additional types called *context
//! selectors*:
//!
//! ```rust,ignore
//! struct OpenConfig<P> { filename: P }
//! struct SaveConfig<P> { filename: P }
//! struct UserIdInvalid<I> { user_id: I }
//! ```
//!
//! 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.
//!
//! If the original variant had a `source` field, its context selector
//! will have an implementation of [`From`](std::convert::From) for a
//! `snafu::Context`:
//!
//! ```rust,ignore
//! impl<P> From<Context<Error, OpenConfig<P>>> for Error
//! where
//!     P: Into<PathBuf>,
//! ```
//!
//! Otherwise, the context selector will have an inherent method
//! `fail`:
//!
//! ```rust,ignore
//! impl<I> UserIdInvalid<I>
//! where
//!     I: Into<i32>,
//! {
//!     fn fail<T>(self) -> Result<T, Error> { /* ... */ }
//! }
//! ```

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>: Sized {
    /// 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>>;

    /// Extend a `Result` with additional context-sensitive
    /// information and immediately convert it to another `Result`.
    ///
    /// This is most useful when using `Result`'s combinators and when
    /// the final `Result` type is already constrained.
    ///
    /// ```rust
    /// use snafu::{Snafu, ResultExt};
    ///
    /// #[derive(Debug, Snafu)]
    /// enum Error {
    ///     Authenticating { user_name: String, user_id: i32, source: ApiError },
    /// }
    ///
    /// fn example() -> Result<i32, Error> {
    ///     another_function()
    ///         .map(|v| v + 10)
    ///         .eager_context(Authenticating { user_name: "admin", user_id: 42 })
    /// }
    ///
    /// # type ApiError = std::io::Error;
    /// fn another_function() -> Result<i32, ApiError> {
    ///     /* ... */
    /// # Ok(42)
    /// }
    /// ```
    fn eager_context<C, E2>(self, context: C) -> Result<T, E2>
    where
        E2: From<Context<E, C>>,
    {
        self.context(context).map_err(Into::into)
    }

    /// Extend a `Result` with lazily-generated context-sensitive
    /// information and immediately convert it to another `Result`.
    ///
    /// This is most useful when using `Result`'s combinators and when
    /// the final `Result` type is already constrained.
    ///
    /// ```rust
    /// use snafu::{Snafu, ResultExt};
    ///
    /// #[derive(Debug, Snafu)]
    /// enum Error {
    ///     Authenticating { user_name: String, user_id: i32, source: ApiError },
    /// }
    ///
    /// fn example() -> Result<i32, Error> {
    ///     another_function()
    ///         .map(|v| v + 10)
    ///         .with_eager_context(|| Authenticating {
    ///             user_name: "admin".to_string(),
    ///             user_id: 42,
    ///         })
    /// }
    ///
    /// # 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_eager_context<C, E2>(self, context: impl FnOnce() -> C) -> Result<T, E2>
    where
        E2: From<Context<E, C>>,
    {
        self.with_context(context).map_err(Into::into)
    }
}

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 }
        })
    }
}