//! A string-based error type.
//!
//! # Introduction
//!
//! This crate provides a string-based error type, `StrError`, that
//! implements `std::error::Error`. `StrError`s behave much like
//! `String`s, except they may contain another error boxed inside
//! them, known as the "source" or "cause". Since the source can have
//! a source itself, sources form chains of errors, each error adding
//! context to the preceeding one.
//!
//! When a `StrError` is returned from `main`, its `Debug`
//! implementation causes the output of a CLI application to look like
//! this
//!
//! ```text
//! Error: ...
//! Caused by: ...
//! Caused by: ...
//! ...
//! ```
//!
//! Each "Caused by:" line corresponds to a boxed error in the chain
//! of sources.
//!
//! # The prelude
//!
//! This crate has a prelude to bring in all the things you need at
//! once.
//!
//! ```
//! use strerror::prelude::*;
//! ```
//!
//! Because some of the crate's functionality is contained in
//! extension traits, this is quite useful. The examples below all
//! assume the prelude is used.
//!
//! # Creating `StrError`s
//!
//! As with `String`s, there are quite a few ways to create a
//! `StrError`. Some have a `String` equivalent so we present these
//! alongside each other.
//!
//! ```
//! # use strerror::prelude::*;
//! // String                             // StrError
//! let str1 = "Error!".to_string();      let err1 = "Error!".to_error();
//! let str2 = String::from("Error!");    let err2 = StrError::from("Error!");
//! let str3: String = "Error!".into();   let err3: StrError = "Error!".into();
//! let str4 = format!("Error! #{}", 1);  let err4 = eformat!("Error! #{}", 1);
//! ```
//!
//! The above lines all create `StrError`s without a "source" or
//! "cause". Next we show two equivalent ways to create a `StrError`
//! containing a source. The `StrError` takes ownership of the source
//! which may or may not be another `StrError`.
//!
//! ```
//! # use strerror::prelude::*;
//! use std::io::Error as IoError;
//!
//! let source1 = IoError::from_raw_os_error(5);
//! let err1 = StrError::from_error(source1, "I/O error occurred");
//!
//! let source2 = IoError::from_raw_os_error(5);
//! let err2 = source2.chain("I/O error occurred");
//! ```
//!
//! The advantage of the second way using the `chain` method comes
//! from the fact that, in chaining methods together, an error chain
//! itself can be created.
//!
//! ```
//! # use strerror::prelude::*;
//! fn main() -> Result<(), StrError> {
//! # || -> Result<(), StrError> {
//!     let err = "Base error".to_error()
//!         .chain("Higher level error")
//!         .chain("Application error");
//!     Err(err)
//! # }().unwrap_err(); Ok(())
//! }
//! ```
//!
//! gives output
//!
//! ```text
//! Error: Application error
//! Caused by: Higher level error
//! Caused by: Base error
//! ```
//!
//! # Returning `Result`s
//!
//! While the `chain` method adds context to error types directly, we
//! can do a similar thing with the `Err` values contained within
//! `Result`s, with the `chain_err` method.
//!
//! ```
//! # use strerror::prelude::*;
//! use std::fs::File;
//!
//! fn main() -> Result<(), StrError> {
//! # || -> Result<(), StrError> {
//!     let file = "missing-file";
//!     let _ = File::open(file)                             // a Result
//!         .chain_err(format!("Failed to open {}", file))?; // main exits here
//!     Ok(())
//! # }().unwrap_err(); Ok(())
//! }
//! ```
//!
//! gives output
//!
//! ```text
//! Error: Failed to open missing-file
//! Caused by: No such file or directory (os error 2)
//! ```
//!
//! The `Result` is converted to the correct type by `chain_err` and
//! context is applied to the boxed error.
//!
//! # Converting `Option`s
//!
//! Sometimes `None` represents an application error and it is
//! desirable to convert an `Option<T>` into a
//! `Result<T, StrError>`. There is no special method needed in this
//! case and you can use `ok_or`/`ok_or_else` with a new `StrError`
//! (created using `to_error`, for example).
//!
//! ```
//! # use strerror::prelude::*;
//! use std::env;
//!
//! fn main() -> Result<(), StrError> {
//! # || -> Result<(), StrError> {
//!     let _ = env::var_os("MISSING_VAR")                       // an Option
//!         .ok_or_else(|| "MISSING_VAR not found".to_error())?; // main exits here
//!     Ok(())
//! # }().unwrap_err(); Ok(())
//! }
//! ```
//!
//! gives output
//!
//! ```text
//! Error: MISSING_VAR not found
//! ```
//!
//! However, if your containing function returns a
//! `Result<T, StrError>`, it is sufficient to pass just a `&str` or
//! `String` to `ok_or`/`ok_or_else`. This produces a
//! `Result<T, &str>` or `Result<T, String>`, but when used with the
//! `?` operator it is converted to a `Result<T, StrError>`. This
//! works because `StrError` implements `From<&str>` and
//! `From<String>`.
//!
//! ```
//! # use strerror::prelude::*;
//! use std::env;
//!
//! fn main() -> Result<(), StrError> {
//! # || -> Result<(), StrError> {
//!     let _ = env::var_os("MISSING_VAR")
//!         .ok_or("MISSING_VAR not found")?;
//!     Ok(())
//! # }().unwrap_err(); Ok(())
//! }
//! ```
//!
//! # `From` conversions
//!
//! `From` conversions are implemented for most of the standard
//! library error types, so you can return a `Result` containing one
//! directly from a function returning a `Result<T, StrError>`, using
//! the `?` operator.
//!
//! ```
//! # use strerror::prelude::*;
//! use std::fs::File;
//!
//! fn main() -> Result<(), StrError> {
//! # || -> Result<(), StrError> {
//!     let file = "missing-file";
//!     let _ = File::open(file)?; // main exits here
//!     Ok(())
//! # }().unwrap_err(); Ok(())
//! }
//! ```
//!
//! gives output
//!
//! ```text
//! Error: std::io::Error
//! Caused by: No such file or directory (os error 2)
//! ```
//!
//! `From` conversions are also implemented for `&str` and `String`,
//! as discussed above.
//!
//! However, for other error types, if you wish to use the `?`
//! operator, you will first need to call the `chain_err` method to
//! convert the `Result` into a `Result<T, StrError>`. Of course you
//! may choose to return a `Result<T, Box<dyn std::error::Error>>`
//! from your function instead, for which `?` will work for all error
//! types.
//!
//! # `Deref`
//!
//! `StrError`s deref to a `String`, so you can use many of the usual
//! `String` methods.
//!
//! ```
//! # use strerror::prelude::*;
//! fn main() -> Result<(), StrError> {
//! # || -> Result<(), StrError> {
//!     let mut err = "This is".to_error();
//!     *err += " an error";
//!     err.push_str(" message");
//!     Err(err)
//! # }().unwrap_err(); Ok(())
//! }
//! ```
//!
//! gives output
//!
//! ```text
//! Error: This is an error message
//! ```
//!
//! # Iterating through the source chain
//!
//! A reference to a `StrError` can be iterated over to examine its
//! chain of boxed sources.
//!
//! ```
//! # use strerror::prelude::*;
//! use std::io::Error as IoError;
//!
//! fn main() -> Result<(), StrError> {
//!     let err = IoError::from_raw_os_error(5)
//!         .chain("Failure reading disk")
//!         .chain("Application error");
//!     for e in &err {
//!         println!(
//!             "Error: {:31} Is StrError?: {}",
//!             e,
//!             e.downcast_ref::<StrError>().is_some()
//!         );
//!     }
//!     Ok(())
//! }
//! ```
//!
//! gives output
//!
//! ```text
//! Error: Application error               Is StrError?: true
//! Error: Failure reading disk            Is StrError?: true
//! Error: Input/output error (os error 5) Is StrError?: false
//! ```

use std::borrow::Cow;
use std::error::Error;
use std::fmt::Error as FmtError;
use std::fmt::{Debug, Display, Formatter};
use std::ops::{Deref, DerefMut};

/// Reexports of `eformat`, `ErrorChainExt`, `ResultChainErrExt`,
/// `StrError` and `StringToErrorExt`.
pub mod prelude {
    pub use super::{
        eformat, ErrorChainExt, ResultChainErrExt, StrError, StringToErrorExt,
    };
}

/// A string-based error type implementing `std::error::Error`.
///
/// `From` conversions to `StrError` are implemented for most standard
/// library error types, and for `String`s and `&str`s. `Deref`
/// converts to a `String`.
///
/// See crate level documentation for usage examples.
pub struct StrError {
    description: String,
    source: Option<Box<dyn Error + Send + Sync>>,
}

impl StrError {
    /// Convert an error of any type to a `StrError`, adding context
    /// and boxing it.
    pub fn from_error<T, E>(err: E, context: T) -> Self
    where
        T: Into<String>,
        E: Into<Box<dyn Error + Send + Sync>>,
    {
        StrError { description: context.into(), source: Some(err.into()) }
    }

    /// Create an iterator over a `StrError` and it's sources. When
    /// using the iterator, the first item retrieved is a reference to
    /// the `StrError` itself (as a trait object). This is then
    /// followed by the chain of sources. You can also use
    /// `&StrError`'s implementation of `IntoIterator` to obtain an
    /// iterator.
    pub fn iter(&self) -> Iter<'_> {
        Iter { next: Some(self) }
    }
}

impl Error for StrError {
    /// Return the lower-level source of this `StrError`, if any.
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        self.source.as_ref().map(|e| &**e as &(dyn Error + 'static))
    }
}

impl Display for StrError {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), FmtError> {
        Display::fmt(&**self, f)
    }
}

impl Debug for StrError {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), FmtError> {
        write!(f, "{}", self)?;
        for e in self.iter().skip(1) {
            write!(f, "\nCaused by: {}", e)?;
        }
        Ok(())
    }
}

/// An iterator producing a reference to a `StrError` (as a trait
/// object), followed by its chain of sources.
pub struct Iter<'a> {
    next: Option<&'a (dyn Error + 'static)>,
}

impl<'a> Iterator for Iter<'a> {
    type Item = &'a (dyn Error + 'static);

    fn next(&mut self) -> Option<Self::Item> {
        match &self.next {
            None => None,
            Some(e) => {
                let next = self.next;
                self.next = e.source();
                next
            }
        }
    }
}

impl<'a> IntoIterator for &'a StrError {
    type Item = &'a (dyn Error + 'static);
    type IntoIter = Iter<'a>;
    fn into_iter(self) -> Iter<'a> {
        self.iter()
    }
}

/// Trait providing `chain` for converting an error of any type to a
/// `StrError`.
///
/// See crate level documentation for usage examples.
pub trait ErrorChainExt<T> {
    /// Convert an error of any type to a `StrError`, adding context.
    fn chain(self, context: T) -> StrError;
}

impl<T, E> ErrorChainExt<T> for E
where
    T: Into<String>,
    E: Into<Box<dyn Error + Send + Sync>>,
{
    fn chain(self, context: T) -> StrError {
        StrError::from_error(self.into(), context.into())
    }
}

/// Trait providing `chain_err` for mapping the `Err` value within a
/// `Result` to a `StrError`.
///
/// See crate level documentation for usage examples.
pub trait ResultChainErrExt<T, U> {
    /// Map the `Err` value within a `Result` to a `StrError`, adding
    /// context.
    fn chain_err(self, context: T) -> Result<U, StrError>;
}

impl<T, U, E> ResultChainErrExt<T, U> for Result<U, E>
where
    T: Into<String>,
    E: Into<Box<dyn Error + Send + Sync>>,
{
    fn chain_err(self, context: T) -> Result<U, StrError> {
        self.map_err(|e| StrError::from_error(e.into(), context.into()))
    }
}

/// Trait providing `to_error` for converting a `String` or `&str` to
/// a `StrError`.
///
/// See crate level documentation for usage examples.
pub trait StringToErrorExt {
    /// Convert a `String` or `&str` to a `StrError`.
    fn to_error(self) -> StrError;
}

impl<T> StringToErrorExt for T
where
    T: Into<String>,
{
    fn to_error(self) -> StrError {
        StrError::from(self.into())
    }
}

/// A macro for creating a `StrError` using interpolation of runtime
/// expressions (like `format!`).
///
/// `eformat!` is an extremely simple macro meant to save some
/// keystrokes when creating `StrError`s. The name was chosen to
/// mirror that of `eprint!` in the standard library, which is an
/// "error" version of `print!`.
///
/// Call `eformat!` as you would call `format!`, but you will get a
/// `StrError` instead of a `String`.
#[macro_export]
macro_rules! eformat {
    ($($arg:tt)*) => {
        StrError::from(format!($($arg)*))
    }
}

// Deref conversion for StrError.
impl Deref for StrError {
    type Target = String;

    fn deref(&self) -> &String {
        &self.description
    }
}
impl DerefMut for StrError {
    fn deref_mut(&mut self) -> &mut String {
        &mut self.description
    }
}

// From conversions for Strings,  &strs etc
impl From<Box<str>> for StrError {
    fn from(s: Box<str>) -> Self {
        StrError { description: s.into_string(), source: None }
    }
}
impl<'a> From<Cow<'a, str>> for StrError {
    fn from(s: Cow<'a, str>) -> Self {
        StrError { description: s.into_owned(), source: None }
    }
}
impl From<&str> for StrError {
    fn from(s: &str) -> Self {
        StrError { description: s.to_owned(), source: None }
    }
}
impl From<String> for StrError {
    fn from(s: String) -> Self {
        StrError { description: s, source: None }
    }
}
impl From<&String> for StrError {
    fn from(s: &String) -> Self {
        StrError { description: s.clone(), source: None }
    }
}

// From conversions for stdlib errors.
macro_rules! impl_from {
    ($from:ty) => {
        impl From<$from> for StrError {
            fn from(err: $from) -> Self {
                StrError::from_error(err, stringify!($from))
            }
        }
    };
    ($from:ty, $param:ident $(, $bound:ident)* ) => {
        impl<$param> From<$from> for StrError
        where
            $param: Send + Sync + 'static $(+ $bound)*,
        {
            fn from(err: $from) -> Self {
                StrError::from_error(err, stringify!($from))
            }
        }
    };
}

impl_from!(std::alloc::LayoutErr);
impl_from!(std::array::TryFromSliceError);
impl_from!(std::boxed::Box<T>, T, Error);
impl_from!(std::cell::BorrowError);
impl_from!(std::cell::BorrowMutError);
impl_from!(std::char::CharTryFromError);
impl_from!(std::char::DecodeUtf16Error);
impl_from!(std::char::ParseCharError);
impl_from!(std::env::JoinPathsError);
impl_from!(std::env::VarError);
impl_from!(std::ffi::FromBytesWithNulError);
impl_from!(std::ffi::IntoStringError);
impl_from!(std::ffi::NulError);
impl_from!(std::fmt::Error);
impl_from!(std::io::Error);
impl_from!(std::io::IntoInnerError<T>, T, Debug);
impl_from!(std::net::AddrParseError);
impl_from!(std::num::ParseFloatError);
impl_from!(std::num::ParseIntError);
impl_from!(std::num::TryFromIntError);
impl_from!(std::path::StripPrefixError);
impl_from!(std::str::ParseBoolError);
impl_from!(std::str::Utf8Error);
impl_from!(std::string::FromUtf16Error);
impl_from!(std::string::FromUtf8Error);
impl_from!(std::string::ParseError);
impl_from!(std::sync::PoisonError<T>, T);
impl_from!(std::sync::TryLockError<T>, T);
impl_from!(std::sync::mpsc::RecvError);
impl_from!(std::sync::mpsc::RecvTimeoutError);
impl_from!(std::sync::mpsc::SendError<T>, T);
impl_from!(std::sync::mpsc::TryRecvError);
impl_from!(std::sync::mpsc::TrySendError<T>, T);
impl_from!(std::time::SystemTimeError);