strerror 0.6.2

//! A string-based error type.
//!
//! # Introduction
//!
//! This crate provides a string-based error type,
//! [`StrError`](StrError), that implements
//! [`std::error::Error`](std::error::Error). It is for simple use
//! cases where you wish to work with string errors and/or box
//! existing errors of any type, adding context to them.
//!
//! [`StrError`](StrError)s behave in many ways like
//! [`String`](String)s, except they may also 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`](StrError) is returned from `main`, its
//! [`Debug`](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::*;
//! ```
//!
//! The examples below all assume use of the prelude.
//!
//! # Creating `StrError`s
//!
//! As with [`String`](String)s, there are quite a few ways to create
//! a [`StrError`](StrError). Some have an analagous
//! [`String`](String) equivalent, so are presented side-by-side with
//! them.
//!
//! ```
//! # use strerror::prelude::*;
//! // String                             // StrError
//! let str1 = "Error!".to_string();      let err1 = "Error!".into_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`](StrError)s without a
//! "source" or "cause". To create a [`StrError`](StrError) with a
//! source you can use [`chain_error`](ChainError::chain_error).
//!
//! ```
//! # use strerror::prelude::*;
//! use std::io::Error as IoError;
//!
//! let source = IoError::from_raw_os_error(5);
//! let err = source.chain_error("I/O error occurred");
//! ```
//!
//! Chaining [`chain_error`](ChainError::chain_error) method calls
//! together creates an error chain.
//!
//! ```
//! # use strerror::prelude::*;
//! fn main() -> Result<(), StrError> {
//! # || -> Result<(), StrError> {
//!     let err = "Base error".into_error()
//!         .chain_error("Higher level error")
//!         .chain_error("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_error`](ChainError::chain_error) method adds
//! context to error types directly, we can do a similar thing with
//! the [`Err`](Err) variant values in [`Result`](Result)s, with the
//! [`chain_err`](ChainErr::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
//!     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`](Result) is converted to the correct type by
//! [`chain_err`](ChainErr::chain_err) and context is applied to the
//! boxed error. Note that in the example above
//! [`chair_err`](ChainErr::chain_err) takes a closure, and not a
//! [`String`](String) directly. This is so the construction of the
//! [`String`](String) is not performed unless needed. You do not need
//! to use closures however, since [`chair_err`](ChainErr::chain_err)
//! accepts [`String`](String)s, and [`&str`](str)s as well.
//!
//! Returning a new [`StrError`](StrError) in a [`Result`](Result) can
//! be done in the following way, taking advantage of [`From`](From)
//! conversion from [`&str`](str).
//!
//! ```
//! # use strerror::prelude::*;
//!
//! fn main() -> Result<(), StrError> {
//! # || -> Result<(), StrError> {
//!     return Err("an error".into());
//! # }().unwrap_err(); Ok(())
//! }
//! ```
//!
//! An alternative is the [`into_err`](IntoErr::into_err) method,
//! which will call [`into`](Into::into) and create the [`Err`](Err)
//! variant in one step.
//!
//!
//! ```
//! # use strerror::prelude::*;
//!
//! fn main() -> Result<(), StrError> {
//! # || -> Result<(), StrError> {
//!     return "an error".into_err();
//! # }().unwrap_err(); Ok(())
//! }
//! ```
//!
//! # Converting `Option`s
//!
//! Sometimes [`None`](None) represents an application error and it is
//! desirable to convert an [`Option<T>`](Option) into a
//! `Result<T, StrError>`. There is no special method needed in this
//! case. You can use [`ok_or`](Option::ok_or) or
//! [`ok_or_else`](Option::ok_or_else).
//!
//! ```
//! # use strerror::prelude::*;
//! use std::env;
//!
//! fn main() -> Result<(), StrError> {
//! # || -> Result<(), StrError> {
//!     let _ = env::var_os("MISSING_VAR")    // an Option
//!         .ok_or("MISSING_VAR not found")?; // main exits
//!     Ok(())
//! # }().unwrap_err(); Ok(())
//! }
//! ```
//!
//! gives output
//!
//! ```text
//! Error: MISSING_VAR not found
//! ```
//!
//! We take advantage again of [`From`](From) conversion from
//! [`&str`](str) to return a [`StrError`](StrError).
//!
//! # `From` conversions to `StrError`
//!
//! [`From`](From) conversions are implemented for most of the
//! standard library error types, so you can return a
//! [`Result`](Result) containing one directly from a function
//! expecting 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
//!     Ok(())
//! # }().unwrap_err(); Ok(())
//! }
//! ```
//!
//! gives output
//!
//! ```text
//! Error: std::io::Error
//! Caused by: No such file or directory (os error 2)
//! ```
//!
//! [`From`](From) conversions are also implemented for [`&str`](str)
//! and [`String`](String), as mentioned previously.
//!
//! However, for other error types, if you wish to use the `?`
//! operator you will first need to call the
//! [`chain_err`](ChainErr::chain_err) method to convert the
//! [`Result<T, E>`](Result) into a `Result<T, StrError>`. Of course
//! you may choose to use a `Box<dyn std::error::Error>` instead of a
//! [`StrError`](StrError) in the the return type of your function, in
//! which case `?` will work for all error types.
//!
//! # `Deref`
//!
//! [`StrError`](StrError)s deref to a [`String`](String), so you can
//! use many of the usual [`String`](String) methods.
//!
//! ```
//! # use strerror::prelude::*;
//! fn main() -> Result<(), StrError> {
//! # || -> Result<(), StrError> {
//!     let mut err = "This is".into_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`](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_error("Failure reading disk")
//!         .chain_error("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`](eformat), [`ChainErr`](ChainErr),
/// [`ChainError`](ChainError), [`IntoErr`](IntoErr),
/// [`IntoError`](IntoError) and [`StrError`](StrError).
pub mod prelude {
    pub use super::{
        eformat, ChainErr, ChainError, IntoErr, IntoError, StrError,
    };
}

/// A string-based error type implementing
/// [`std::error::Error`](std::error::Error).
///
/// [`From`](From) conversions to [`StrError`](StrError) are
/// implemented for most standard library error types, and for
/// [`String`](String)s and [`&str`](str)s. [`Deref`](Deref) converts
/// to a [`String`](String).
///
/// See crate level documentation for usage examples.
pub struct StrError(Box<StrErrorInner>);

struct StrErrorInner {
    context: String,
    source: Option<Box<dyn Error + Send + Sync>>,
}

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

    /// Destroy the [`StrError`](StrError), returning its raw
    /// parts. These are its context string and its source error (if
    /// it has one).
    pub fn into_raw_parts(
        self,
    ) -> (String, Option<Box<dyn Error + Send + Sync>>) {
        (self.0.context, self.0.source)
    }
}

impl Error for StrError {
    /// Return the lower-level source of this [`StrError`](StrError),
    /// if any.
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        self.0.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`](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_error`](ChainError::chain_error) for
/// converting an error of any type to a [`StrError`](StrError).
///
/// See crate level documentation for usage examples.
pub trait ChainError {
    /// Convert an error of any type to a [`StrError`](StrError), adding
    /// context.
    fn chain_error<C>(self, context: C) -> StrError
    where
        C: IntoChained;
}

impl<E> ChainError for E
where
    E: Into<Box<dyn Error + Send + Sync>>,
{
    fn chain_error<C>(self, context: C) -> StrError
    where
        C: IntoChained,
    {
        context.into_chained(self)
    }
}

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

impl<T, E> ChainErr<T> for Result<T, E>
where
    E: Into<Box<dyn Error + Send + Sync>>,
{
    fn chain_err<C>(self, context: C) -> Result<T, StrError>
    where
        C: IntoChained,
    {
        self.map_err(|e| context.into_chained(e))
    }
}

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

impl<S> IntoError for S
where
    S: Into<StrError>,
{
    fn into_error(self) -> StrError {
        self.into()
    }
}

/// Trait providing [`into_err`](IntoErr::into_err) for converting a
/// [`String`](String), [`&str`](str) or error to an [`Err`](Err)
/// variant [`Result`](Result).
///
/// [`into_err`](IntoErr::into_err) has a very simple implementation:
/// `Err(self.into())`, which is similar to how the `?` operator
/// returns errors.
///
/// See crate level documentation for usage examples.
pub trait IntoErr {
    /// Convert a [`String`](String), [`&str`](str) or error to an
    /// [`Err`](Err) variant [`Result`](Result).
    fn into_err<T, E>(self) -> Result<T, E>
    where
        Self: Into<E>;
}

impl<C> IntoErr for C {
    fn into_err<T, E>(self) -> Result<T, E>
    where
        Self: Into<E>,
    {
        Err(self.into())
    }
}

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

/// Trait providing [`into_chained`](IntoChained::into_chained) for
/// converting context into a chained error.
///
/// You will likely not use this trait directly, and it is not in the
/// prelude. It is used to implement [`ChainErr`](ChainErr) and
/// [`ChainError`](ChainError), which you should use instead.
pub trait IntoChained {
    fn into_chained<S>(self, source: S) -> StrError
    where
        S: Into<Box<dyn Error + Send + Sync>>;
}

impl IntoChained for Box<str> {
    fn into_chained<S>(self, source: S) -> StrError
    where
        S: Into<Box<dyn Error + Send + Sync>>,
    {
        self.into_string().into_chained(source)
    }
}
impl IntoChained for Cow<'_, str> {
    fn into_chained<S>(self, source: S) -> StrError
    where
        S: Into<Box<dyn Error + Send + Sync>>,
    {
        self.into_owned().into_chained(source)
    }
}
impl IntoChained for &str {
    fn into_chained<S>(self, source: S) -> StrError
    where
        S: Into<Box<dyn Error + Send + Sync>>,
    {
        self.to_owned().into_chained(source)
    }
}
impl IntoChained for String {
    fn into_chained<S>(self, source: S) -> StrError
    where
        S: Into<Box<dyn Error + Send + Sync>>,
    {
        StrError(Box::new(StrErrorInner {
            context: self,
            source: Some(source.into()),
        }))
    }
}
impl IntoChained for &String {
    fn into_chained<S>(self, source: S) -> StrError
    where
        S: Into<Box<dyn Error + Send + Sync>>,
    {
        self.clone().into_chained(source)
    }
}
impl<F, C> IntoChained for F
where
    F: FnOnce() -> C,
    C: IntoChained,
{
    fn into_chained<S>(self, source: S) -> StrError
    where
        S: Into<Box<dyn Error + Send + Sync>>,
    {
        self().into_chained(source)
    }
}

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

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

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

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

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