nuhound

A Rust library for enhanced error tracking

Rust programmers often find the question mark operator invaluable in extracting values from Result and Option and immediately returning to the calling context in the case of an Err or None. This crate provides some enhancements to this functionality by:

• Converting Result::Err and Option::None values to a single nuhound type error;
• Creating an error chain that can help pinpoint the source of the error;
• Providing a disclose feature that enhances error messages by incuding the filename, line number and column number of the source file that caused the error. This functionality is provided by the here! macro when the disclose feature is enabled;
• Simplifying error handling with a concise and consistent Rust style.
• Providing a simple implementation that requires minimal changes to your coding experience.

Remember to add this to Cargo.toml:

[features]
# To help diagnose errors, use the disclose feature when compiling.
# This ensures that the source file name and line number are displayed
# when using the here! macro.
# example usage: cargo build --features=disclose
disclose = []

Example

The following example shows how the here macro is used to report an error but still retain the underlying error or errors that can be displayed using the trace method.

use nuhound::{Report, here, ResultExtension};

fn generate_error() -> Report<u32> {
    let text = "NaN";
    let value = text.parse::<u32>().report(|e| here!(e, "Oh dear - '{}' could not be \
    converted to an integer", text))?;
    Ok(value)
}

let result = generate_error();

match result {
    Ok(_) => unreachable!(),
    Err(e) => {
        println!("Display the error:\n{e}\n");
        println!("Or trace the error:\n{}\n", e.trace());
    }
}
// This will emit:
// Display the error:
// Oh dear - 'NaN' could not be converted to an integer
//
// Or trace the error:
// 0: Oh dear - 'NaN' could not be converted to an integer
// 1: invalid digit found in string
//
// This will also show the name of the file causing the error
// and the line and column number if the code is compiled with
// the disclose feature enabled.

License

This project is licensed under either:

• Apache License, Version 2.0, (LICENSE.apache-2.0 or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE.MIT or https://opensource.org/licenses/MIT)