derive-error-chain 0.7.2

A Macros 1.1 implementation of error-chain
Documentation

A Macros 1.1 implementation of https://crates.io/crates/error-chain

The error-chain example

mod other_error {
    error_chain! {}
}

error_chain {
    types { Error, ErrorKind, ResultExt, Result; }

    links {
        Another(other_error::Error, other_error::ErrorKind) #[cfg(unix)];
    }

    foreign_links {
        Fmt(::std::fmt::Error);
        Io(::std::io::Error) #[cfg(unix)];
    }

    errors {
    	InvalidToolchainName(t: String) {
    		description("invalid toolchain name")
    		display("invalid toolchain name: '{}'", t)
    	}
    }
}

becomes

mod other_error {
    #[derive(Debug, error_chain)]
    pub enum ErrorKind {
        Msg(String), // A special variant that must always be present.
    }
}

#[derive(Debug, error_chain)]
// This attribute is optional if using the default names "Error", "ResultExt" and "Result".
#[error_chain(error = "Error", result_ext = "ResultExt", result = "Result")]
pub enum ErrorKind {
    Msg(String), // A special variant that must always be present.

    #[cfg(unix)]
    #[error_chain(link = "other_error::Error")]
    Another(other_error::ErrorKind),

    #[error_chain(foreign)]
    Fmt(::std::fmt::Error),

    #[cfg(unix)]
    #[error_chain(foreign)]
    Io(::std::io::Error),

    #[error_chain(custom, description = "invalid_toolchain_name_description", display = "invalid_toolchain_name_display")]
    InvalidToolchainName(String),
}

// A description function receives refs to all the variant constituents, and should return a &str
fn invalid_toolchain_name_description(_: &str) -> &str {
    "invalid toolchain name"
}

// A display function receives a formatter and refs to all the variant constituents, and should return a ::std::fmt::Result
fn invalid_toolchain_name_display(f: &mut ::std::fmt::Formatter, t: &str) -> ::std::fmt::Result {
    write!(f, "invalid toolchain name: '{}'", t)
}

Notes:

  • This library requires the nightly compiler to be able to use the proc_macro rust feature.

  • The macro output can be used with #[deny(missing_docs)] since it allows doc comments on the ErrorKind variants.

  • The result wrapper can be disabled by setting result = "" in the #[error_chain] attribute on the ErrorKind.

  • The backtrace functionality can be disabled by setting backtrace = "false" or backtrace = false in the #[error_chain] attribute on the ErrorKind.

  • The ErrorKind must have a special Msg(String) member. Unlike error_chain which adds this member implicitly, this macro requires it explicitly.

  • The description and display functions can be inlined like this:

     #[error_chain(custom)]
     #[error_chain(description = r#"(|_| "invalid toolchain name")"#)]
     #[error_chain(display = r#"(|f: &mut ::std::fmt::Formatter, t| write!(f, "invalid toolchain name: '{}'", t))"#)]
     InvalidToolchainName(String),