// define-errors - copyright 2017 The define-errors authors.
// See the AUTHORS file for further copyright information.
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.

//! A macro for defining error types.
//!
//! # Introduction
//!
//! The `define_errors` macro defines new error types. The error types
//! are enums that can hold other error values and/or error
//! descriptions. The macro is designed to allow the adding of
//! multiple levels of *context* to errors by sucessively wrapping
//! them, without losing any of the structured information contained
//! in the wrapped errors. It tries to be as simple as possible while
//! still achieving that goal.
//!
//! # Plain and wrapped errors
//!
//! To illustrate the syntax we will use examples. Firstly, the
//! following code will define a new error type called `MyError`, and
//! a macro `myerr_new` that can be used to create new values of type
//! `MyError`:
//!
//! ```
//! # #[macro_use] extern crate define_errors;
//! use std::error::Error; // required use statement
//!
//! define_errors! {
//!     MyError myerr_new {}
//! }
//! # fn main() {}
//! ```
//!
//! Note that the `use` statement is *required*. However, you can use
//! another name binding if you need to. For example, this will also
//! work:
//!
//! ```
//! # #[macro_use] extern crate define_errors;
//! use std::error::Error as StdError;
//!
//! define_errors! {
//!     MyError myerr_new {}
//! }
//! # fn main() {}
//! ```
//!
//! If the type being defined needs to be declared public you can add
//! the `pub` keyword before the name. Also, you can define multiple
//! error types at once (although in most cases one is all that is required):
//!
//! ```
//! # #[macro_use] extern crate define_errors;
//! # use std::error::Error;
//! define_errors! {
//!     pub MyError myerr_new {}
//!     MyError2 myerr2_new {}
//!     MyError3 myerr3_new {}
//! }
//! # fn main() {}
//! ```
//!
//! The `MyError` definition inserted by the macro above looks like
//! this:
//!
//! ```
//! pub enum MyError {
//!     Plain {
//!         description: String,
//!     },
//!     Wrapped {
//!         err: Box<MyError>,
//!         description: String,
//!     },
//! }
//! ```
//!
//! Since `MyError` is an enum, `MyError` values can be different
//! *variants*. In this case: `Plain` and `Wrapped`. `Plain` holds a
//! simple description string, but `Wrapped` holds a description and a
//! "wrapped" error, also of type `MyError`. The two variants can be
//! created in a simple way using the automatically defined
//! `myerr_new` macro, as shown in the next code example. The
//! description passed to `myerr_new` can be either a `&str` or a
//! `String`:
//!
//! ```
//! # #[macro_use] extern crate define_errors;
//! # use std::error::Error;
//! # define_errors! {
//! #     MyError myerr_new {}
//! # }
//! # fn main() {
//! let e_plain = myerr_new!(Plain, "a plain error");
//! let e_wrapped = myerr_new!(Wrapped, e_plain, "a wrapped error");
//! # }
//! ```
//!
//! When `e_wrapped` is converted to a string it will show the
//! description given to the `myerr_new` call, as well as the
//! description contained inside the wrapped error:
//!
//! ```
//! # #[macro_use] extern crate define_errors;
//! # use std::error::Error;
//! # define_errors! {
//! #     MyError myerr_new {}
//! # }
//! # fn main() {
//! # let e_plain = myerr_new!(Plain, "a plain error");
//! # let e_wrapped = myerr_new!(Wrapped, e_plain, "a wrapped error");
//! assert_eq!(format!("{}", e_wrapped), "a wrapped error: a plain error");
//! # }
//! ```
//!
//! In other words, `e_wrapped` has taken `e_plain` and added context
//! to it. It should also be noted that `e_wrapped` takes ownership of
//! `e_plain`.
//!
//! # Formatted descriptions
//!
//! There is a shortcut for creating formatted descriptions for
//! `Plain` and `Wrapped`. Instead of
//!
//! ```
//! # #[macro_use] extern crate define_errors;
//! # use std::error::Error;
//! # define_errors! {
//! #     MyError myerr_new {}
//! # }
//! # fn main() {
//! let e_plain2 = myerr_new!(Plain, format!("{}: {}", "str1", "str2"));
//! # }
//! ```
//!
//! you can instead use
//!
//! ```
//! # #[macro_use] extern crate define_errors;
//! # use std::error::Error;
//! # define_errors! {
//! #     MyError myerr_new {}
//! # }
//! # fn main() {
//! # let e_plain2 = myerr_new!(Plain, format!("{}: {}", "str1", "str2"));
//! let e_plain3 = myerr_new!(Plain, "{}: {}", "str1", "str2");
//! # assert_eq!(e_plain2.description(), e_plain3.description());
//! # }
//! ```
//!
//! This works for up to six `format` arguments, and for `Plain` and
//! `Wrapped` variants of `MyError`.
//!
//! # Existing error types
//!
//! `define_errors` can also define error types that holds existing
//! error types (such as `std::io::Error`) in corresponding
//! variants. For example:
//!
//! ```
//! # #[macro_use] extern crate define_errors;
//! # use std::error::Error;
//! define_errors! {
//!     MyError myerr_new {
//!         Io: std::io::Error,
//!         Utf8: std::str::Utf8Error,
//!     }
//! }
//! # fn main() {}
//! ```
//!
//! This defines an enum that looks like:
//!
//! ```
//! enum MyError {
//!     Plain {
//!         description: String,
//!     },
//!     Wrapped {
//!         err: Box<MyError>,
//!         description: String,
//!     },
//!     Io {
//!         err: std::io::Error,
//!     },
//!     Utf8 {
//!         err: std::str::Utf8Error,
//!     },
//! }
//! ```
//!
//! `Plain` and `Wrapped` variants are still present, but we now also
//! have `Io` and `Utf8`. These new variants of `MyError` can be
//! created in a similar fashion to before, again using
//! `myerr_new`. As when creating `Wrapped` variants, `myerr_new`
//! takes ownership of the errors being passed to it:
//!
//! ```
//! # #[macro_use] extern crate define_errors;
//! # use std::error::Error;
//! # use std::io::ErrorKind;
//! # define_errors! {
//! #     MyError myerr_new {
//! #         Io: std::io::Error,
//! #         Utf8: std::str::Utf8Error,
//! #     }
//! # }
//! # fn main() {
//! # let io_err = std::io::Error::new(ErrorKind::Other, "oh no!");
//! # let utf8_err = std::str::from_utf8(&[255]).unwrap_err();
//! // io_err: value of type std::io::Error
//! let e_io = myerr_new!(Io, io_err);
//!
//! // utf8_err: value of type std::str::Utf8Error
//! let e_utf8 = myerr_new!(Utf8, utf8_err);
//! # }
//! ```
//!
//! A nice thing is that the `From` traits for existing error types
//! are implemented as standard by `define_errors`. In this case:
//!
//! ```ignore
//! From<std::io::Error> for MyError
//! From<std::str::Utf8Error> for MyError
//! ```
//!
//! This means that when using the question mark operator or `try`
//! macro, existing error types get converted to our `MyError` type
//! automatically:
//!
//! ```
//! # #[macro_use] extern crate define_errors;
//! # use std::error::Error;
//! # define_errors! {
//! #     MyError myerr_new {
//! #         Io: std::io::Error,
//! #         Utf8: std::str::Utf8Error,
//! #     }
//! # }
//! type MyResult<T> = Result<T, MyError>;
//!
//! fn decode_some_utf8() -> MyResult<()> {
//!     // std::str::Utf8Error errors here are converted to MyError
//!     std::str::from_utf8(&[255])?;
//!     // this line is never reached - &[255] is bad utf8
//!     unreachable!();
//! }
//!
//! fn main() {
//!     match decode_some_utf8() {
//!         Ok(_) => unreachable!(),
//!         Err(ref e) => {
//!             assert_eq!(e.description(),
//!                        "invalid utf-8: corrupt contents");
//!         }
//!     }
//! }
//! ```
//!
//! Lastly, `MyError` also implements the `std::error::Error` trait,
//! so you can create trait objects if you wish:
//!
//! ```
//! # #[macro_use] extern crate define_errors;
//! # use std::error::Error;
//! # define_errors! {
//! #     MyError myerr_new {
//! #     }
//! # }
//!
//! fn use_trait_object(err: &std::error::Error)  {
//!     // do stuff with err
//!     let _ = err.description();
//!     let _ = err.cause();
//! }
//!
//! fn main() {
//!     let e = myerr_new!(Plain, "a plain old error");
//!     use_trait_object(&e);
//! }
//! ```
//!
//! That is all there is to `define_errors`.
//!
//! # A complete example
//!
//! Here is a complete example illustrating most of the above:
//!
//! ```
//! #[macro_use]
//! extern crate define_errors;
//!
//! use std::error::Error;
//! use std::fs::File;
//! use std::io::Read;
//! use std::path::Path;
//!
//! define_errors! {
//!     MyError myerr_new {
//!         Io: std::io::Error,
//!     }
//! }
//!
//! type MyResult<T> = Result<T, MyError>;
//!
//! fn load_file(path: &Path) -> MyResult<Vec<u8>> {
//!     // std::io::Error values here are automatically converted to MyError
//!     let mut f = File::open(path)?;
//!     let mut buffer = Vec::new();
//!     let _ = f.read_to_end(&mut buffer)?;
//!     Ok(buffer)
//! }
//!
//! fn load_file_add_context(path: &Path) -> MyResult<Vec<u8>> {
//!     if path.starts_with("/forbidden_area") {
//!         return Err(myerr_new!(Plain,
//!                               "{}: no access",
//!                               path.to_string_lossy()));
//!     }
//!     load_file(path).map_err(|e| {
//!         // add path context to errors returned from load_file
//!         myerr_new!(Wrapped, e, path.to_string_lossy())
//!     })
//! }
//!
//! fn main() {
//!     let result = load_file_add_context(Path::new("/path/to/invalid/file"));
//!     match result {
//!         Ok(_) => unreachable!(),
//!         Err(ref e) => {
//!             assert_eq!(format!("{}", e),
//!                        "/path/to/invalid/file: entity not found");
//!             assert_eq!(e.description(),
//!                        "/path/to/invalid/file: entity not found");
//!         }
//!     }
//! }
//! ```

/// A macro for defining error types.
///
/// See the crate documentation for details.
#[macro_export]
macro_rules! define_errors {
    (@implementations $name:ident $mcname:ident ($($vrnt:ident $err:path)*)) =>
    {
        $(
            impl From<$err> for $name {
                fn from(e: $err) -> $name {
                    $name::$vrnt { err: e }
                }
            }
        )*
        impl ::std::fmt::Display for $name {
            fn fmt(&self, f: &mut ::std::fmt::Formatter) ->
                ::std::fmt::Result {
                match *self {
                    $name::Plain { description: ref s } => write!(f, "{}", s),
                    $name::Wrapped { err: _, description: ref s } => {
                        write!(f, "{}", s)
                    }
                    $(
                        $name::$vrnt { err: ref e } => {
                            write!(f, "{}", e.description())
                        }
                    )*
                }
            }
        }
        impl ::std::error::Error for $name {
            fn description(&self) -> &str {
                match *self {
                    $name::Plain { description: ref s } => &*s,
                    $name::Wrapped { err: _, description: ref s } => &*s,
                    $(
                        $name::$vrnt { err: ref e } => e.description(),
                    )*
                }
            }
            fn cause(&self) -> Option<&::std::error::Error> {
                match *self {
                    $name::Plain { description: _ } => None,
                    $name::Wrapped { err: ref e, description: _ } => Some(e),
                    $(
                        $name::$vrnt { err: ref e } => Some(e),
                    )*
                }
            }
        }
        macro_rules! $mcname {
            (Plain, $a1:expr) => {
                $name::Plain{description: format!("{}", $a1)}
            };
            (Plain, $a1:expr, $a2:expr) => {
                $name::Plain{description: format!($a1, $a2)}
            };
            (Plain, $a1:expr, $a2:expr, $a3:expr) => {
                $name::Plain{description: format!($a1, $a2, $a3)}
            };
            (Plain, $a1:expr, $a2:expr, $a3:expr, $a4:expr) => {
                $name::Plain{description: format!($a1, $a2, $a3, $a4)}
            };
            (Plain, $a1:expr, $a2:expr, $a3:expr, $a4:expr, $a5:expr) => {
                $name::Plain{description: format!($a1, $a2, $a3, $a4, $a5)}
            };
            (Plain, $a1:expr, $a2:expr, $a3:expr, $a4:expr, $a5:expr, $a6:expr) => {
                $name::Plain{description: format!($a1, $a2, $a3, $a4, $a5, $a6)}
            };
            (Wrapped, $wrapped_err:expr, $a1:expr) => {
                $name::Wrapped{
                    description: format!("{}: {}",
                                         format!("{}", $a1),
                                         $wrapped_err.description()),
                    err: Box::new($wrapped_err)
                }
            };
            (Wrapped, $wrapped_err:expr, $a1:expr, $a2:expr) => {
                $name::Wrapped{
                    description: format!("{}: {}",
                                         format!($a1, $a2),
                                         $wrapped_err.description()),
                    err: Box::new($wrapped_err)
                }
            };
            (Wrapped, $wrapped_err:expr, $a1:expr, $a2:expr, $a3:expr) => {
                $name::Wrapped{
                    description: format!("{}: {}",
                                         format!($a1, $a2, $a3),
                                         $wrapped_err.description()),
                    err: Box::new($wrapped_err)
                }
            };
            (Wrapped, $wrapped_err:expr, $a1:expr, $a2:expr, $a3:expr, $a4:expr) => {
                $name::Wrapped{
                    description: format!("{}: {}",
                                         format!($a1, $a2, $a3, $a4),
                                         $wrapped_err.description()),
                    err: Box::new($wrapped_err)
                }
            };
            (Wrapped, $wrapped_err:expr, $a1:expr, $a2:expr, $a3:expr, $a4:expr, $a5:expr) => {
                $name::Wrapped{
                    description: format!("{}: {}",
                                         format!($a1, $a2, $a3, $a4, $a5),
                                         $wrapped_err.description()),
                    err: Box::new($wrapped_err)
                }
            };
            (Wrapped, $wrapped_err:expr, $a1:expr, $a2:expr, $a3:expr, $a4:expr, $a5:expr, $a6: expr) => {
                $name::Wrapped{
                    description: format!("{}: {}",
                                         format!($a1, $a2, $a3, $a4, $a5, $a6),
                                         $wrapped_err.description()),
                    err: Box::new($wrapped_err)
                }
            };
            $(
                ($vrnt, $err_val:expr) => {
                    $name::$vrnt{err: $err_val}
                };
            )*
        }
    };
    (pub $name:ident $mcname:ident {$($vrnt:ident: $err:path,)*} $($tt:tt)*)
        => {
        #[derive(Debug)]
        #[allow(dead_code)]
        pub enum $name {
            /// A plain error with a description.
            Plain { description: String },
            /// A wrapped error with a description.
            Wrapped {
                err: Box<$name>,
                description: String,
            },
            $(
                /// A specific error of the given type
                $vrnt {
                    err: $err,
                },
            )*
        }
        define_errors!(@implementations $name $mcname ($($vrnt $err)*));
        define_errors!($($tt)*);
    };
    ($name:ident $mcname:ident {$($vrnt:ident: $err:path,)*} $($tt:tt)*)
        => {
        #[derive(Debug)]
        #[allow(dead_code)]
        enum $name {
            /// A plain error with a description.
            Plain { description: String },
            /// A wrapped error with a description.
            Wrapped {
                err: Box<$name>,
                description: String,
            },
            $(
                /// A specific error of the given type
                $vrnt {
                    err: $err,
                },
            )*
        }
        define_errors!(@implementations $name $mcname ($($vrnt $err)*));
        define_errors!($($tt)*);
    };
    () => {};
}