Error

Derive Macro Error 

Source
#[derive(Error)]
{
    // Attributes available to this derive:
    #[display]
}
Expand description

Derive macro for the Error trait that implements the best practices for error-stack.

§Overview

This derive macro allows you to automatically implement the required Display and Error traits for custom types that you want to use as context types in error-stack Reports without all the boilerplate.

The macro has a display attribute, which specifies a formatting string to print a value of the given type or enum variant.

§Examples

use error_stack_macros2::Error;

#[derive(Debug, Error)]
#[display("invalid card string")]
struct ParseCardError;

§Enum

use error_stack_macros2::Error;

#[derive(Debug, Error)]
#[display("credit card error")] // optional default
enum CreditCardError {
    #[display("credit card not found")]
    InvalidInput(String),

    #[display("failed to retrieve credit card")]
    Other,
}

§Field interpolation (discouraged)

use error_stack_macros2::Error;

#[derive(Debug, Error)]
#[display("invalid card string: {0:?}")]
struct ParseCardError(String);

let err = ParseCardError("1234567".to_string());
assert_eq!(err.to_string(), "invalid card string: \"1234567\"");

§This may look familiar…

This derive macro is heavily inspired by the popular thiserror crate. In fact, you can use the thiserror crate to derive the same traits for your types. However, error-stack is very opinionated about how context types should be designed and used, and this derive macro enforces those best practices, whereas thiserror is more flexible and designed for general use cases.

Also, due to this macro’s more simple and restricted design, it can potentially be more efficient than thiserror in terms of compile time and generated code size.