Crate errs 

This crate is for error handling in Rust programs, providing an Err struct which represents an error with a reason.

The type of this reason is any, but typically an enum variant is used. The name of this enum variant indicates the reason for the error, and its fields store contextual information about the situation in which the error occurred. Since the path of an enum variant, including its package, is unique within a program, the enum variant representing the reason is useful for identifying the specific error, locating where it occurred, or generating appropriate error messages, etc.

Optionally, by using errs-notify feature and registering error handlers in advance, it is possible to receive notifications either synchronously or asynchronously at the time the error struct is created.

Install

In Cargo.toml, write this crate as a dependency:

[dependencies]
errs = "0.4.0"

If you want to use error notification, specifies errs-notify or full in the dependency features:

[dependencies]
errs = { version = "0.4.0", features = ["errs-notify"] }

Usage

Err instantiation and identification of a reason

The Err struct can be instantiated with new<R>(reason: R) function or with_source<R, E>(reason: R, source: E) function.

Then, the reason can be identified with reason<R>(&self) method and a match statement, or match_reason<R>(&self, func fn(&R)) method.

The following code is an example which uses new<R>(reason: R) function for instantiation, and reason<R>(&self) method and a match statement for identifying a reason:

use errs::Err;

#[derive(Debug)]
enum Reasons {
    IllegalState { state: String },
    // ...
}

let err = Err::new(Reasons::IllegalState { state: "bad state".to_string() });

match err.reason::<Reasons>() {
    Ok(r) => match r {
        Reasons::IllegalState { state } => println!("state = {state}"),
        _ => { /* ... */ }
    }
    Err(err) => match err.reason::<String>() {
        Ok(s) => println!("string reason = {s}"),
        Err(err) => { /* ... */ }
    }
}

Notification of Err instantiations

This crate optionally provides a feature to notify pre-registered error handlers when an Err is instantiated. Multiple error handlers can be registered, and you can choose to receive notifications either synchronously or asynchronously. To register error handlers that receive notifications synchronously, use the add_sync_err_handler function. For asynchronous notifications, use the add_async_err_handler! macro.

Error notifications will not occur until the fix_err_handlers function is called. This function locks the current set of error handlers, preventing further additions and enabling notification processing.

errs::add_async_err_handler(|err, tm| {
    println!("{}:{}:{} - {}", tm, err.file(), err.line(), err);
});

errs::add_sync_err_handler(|err, tm| {
    println!("{}:{}:{} - {}", tm, err.file(), err.line(), err);
});

errs::fix_err_handlers();

Structs

Err

Struct that represents an error with a reason.

ErrHandlingErrorerrs-notify

Represents an error that occurred during the error handling notification process.

Enums

ErrHandlingErrorKinderrs-notify

Represents the specific kind of error that can occur within the error handling notification system.

Functions

add_async_err_handlererrs-notify

Registers an asynchronous error handler.

add_sync_err_handlererrs-notify

Registers a synchronous error handler.

fix_err_handlerserrs-notify

Fixes the set of registered error handlers, preventing any further additions.