[−][src]Derive Macro embedded_error_chain::ErrorCategory

#[derive(ErrorCategory)]
{
    // Attributes available to this derive:
    #[error_category]
    #[error]
}

Derive ErrorCategory for an enum.

This will also derive the trait dependencies of ErrorCategory with the exception of Copy:

The traits Into<ErrorCode> and From<ErrorCode> are only derived if the enum is repr(u8) (see Data Layout in the nomicon) or does not contain any variants.

#[error_category] attribute

This attribute is optionally put once on the enum that is to be derived. It specifies an optional ErrorCategory::NAME value (used for debug printing) and 0 to 6 linked ErrorCategory types. If no name argument is given, the name of the enum will be used for ErrorCategory::NAME. If no links are specified, the error category is not linked.

Example:

#[derive(Clone, Copy, ErrorCategory)]
#[error_category(name = "CustomName", links(Type0, Type1))]
#[repr(u8)]
enum FooError {
    Error,
}

#[error] attribute

This attribute is also optional and can be placed once above every enum variant. Its arguments specify the arguments used for debug printing of an error code represented by the variant.

Everything inside the paranthese (#[error(...)]) will directly be used as the arguments of the write! macro. So the attribute #[error("fmt string {} {}", GLOBAL_VAL, 5)] will be translated to write!(f, "fmt string {} {}", GLOBAL_VAL, 5). The first argument must be a string literal and can contain special placeholders that will be replaced by the derive macro:

  • {category} will be replaced with the value of ErrorCategory::NAME.
  • {variant} will be replaced with the name of the variant.
  • {details} will be replaced with the details section of the doc comments on the variant.
  • {summary} will be replaced with the summary of the doc comments on the variant.

The summary section of the doc comments is all non-empty lines, ignoring all empty lines until the first non-empty line, until an empty line or the end of the doc comments. All the summary lines are then trimmed for whitespace and joined using a space character ( ).

The details section of the doc comments is all lines (empty and non-empty) with the first whitespace removed after the summary section and ignoring all empty-lines until the first non-empty line.

Example:

<summmary> /// Summary starts here...
           /// some more summary
</summary> /// ...and ends here.
           ///
           ///
<details>  /// Details start here...
           ///
           /// more details
</details> /// ...and end here.

  • summary:

    Summary starts here... some more summary ...and ends here.

  • details:

    Details start here...

more details
...and end here.

If no #[error] attribute is put on the variant, then the summary part of the doc comments will be used (see above). If the summary does not exist (no doc comments on the variant) or is empty, then the variant name is used for debug printing.

Full example

use embedded_error_chain::prelude::*;

#[derive(Clone, Copy, ErrorCategory)]
#[repr(u8)]
enum OtherError {
    ExtremeFailure,
}

static SOME_GLOBAL_VARIABLE: usize = 200;

#[derive(Clone, Copy, ErrorCategory)]
#[error_category(name = "optional name", links(OtherError))]
#[repr(u8)]
enum TestError {
    /// Foo error (summary)
    ///
    /// Detailed description.
    /// The summary and detailed description are available as placeholders in
    /// the `#[error(...)]` attribute. If no such attribute is put on the variant
    /// or the `...` part is empty, then the summary will be used. If the summary
    /// does not exist (no doc comments on the variant), then the variant name is
    /// used for debug printing.
    #[error("format string {summary}, {details}, {variant}, {category}")]
    Foo = 0,

    #[error("custom {}, {:?}", "some_expr", SOME_GLOBAL_VARIABLE)]
    Other,

    /// Some explanation explanation
    Bar,
}

#[derive(Clone, Copy, ErrorCategory)]
#[error_category(links(OtherError, TestError))]
#[repr(u8)]
enum SeperateError {
    SomethingHappened,
}

#[derive(Clone, Copy, ErrorCategory)]
enum YetEmptyError {}