Crate onlyerror

Expand description

no_std-compatible derive macro for error handling.

onlyerror is comparable in feature set to the venerable thiserror crate with two major differences:

The feature subset is highly restricted.
Generally much faster compile times.

For more on compile times, see the myn benchmarks.

§Example

use onlyerror::Error;

#[derive(Debug, Error)]
pub enum HttpClientError {
    /// I/O error.
    Io(#[from] std::io::Error),

    /// Login error.
    #[error("Login error. Server message: `{0}`.")]
    LoginError(String),

    /// Invalid header.
    #[error("Invalid header (expected {expected:?}, found {found:?}).")]
    InvalidHeader {
        expected: String,
        found: String,
    },

    /// Unknown.
    Unknown,
}

§DSL reference

The macro has a DSL modeled after thiserror, so it should feel familiar to anyone who has used it.

The macro derives an implementation for the Error trait.
Display is derived using the #[error("...")] attributes with a fallback to doc comments.
From is derived for each #[from] or #[source] attribute.

Error messages in #[error("...")] can reference enum variant fields by name (for struct-like variants) or by number (for tuple-like variants) using the std::fmt machinery.

It is recommended to use #[error("...")] when you need interpolation, otherwise use doc comments. Doing this will keep implementation details out of your documentation while making the error variants self-documenting.

§Limitations

Only enum types are supported by the Error macro.
Only inline string interpolations are supported by the derived Display impl.
Either all variants must be given an error message, or #[no_display] attribute must be set to enum with hand-written Display implementation
From impls are only derived for #[from] and #[source] attributes, not implicitly for any field names.
Backtrace is not supported.
#[error(transparent)] is not supported.

§Cargo features

std (default): use the std::error module.

To use onlyerror in a no_std environment, disable default features in your Cargo manifest.

As of writing, you must add #![feature(error_in_core)] to the top-level lib.rs or main.rs file to enable the core::error module. This feature flag is only available on nightly compilers.

Derive Macros§

Error