# 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 including the filename, line
number and column number of the source file that caused the error. This functionality is
provided by the `here!`, `convert!`, `examine!` and `custom!` macros when the `disclose`
feature is enabled;
- Simplifying error handling in 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:
```text
[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!, convert!, examine! and custom! macros.
# example usage: cargo build --features=disclose
disclose = []
```
## Examples
### here!
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) => {
#[cfg(feature = "disclose")]
eprintln!("{}", e.trace());
#[cfg(not(feature = "disclose"))]
eprintln!("{}", e);
},
}
// With the disclose feature enabled the code will emit:
// 0: src/main.rs:6:48: Oh dear - 'NaN' could not be converted to an integer
// 1: invalid digit found in string
//
// With the disclose feature disabled the code will emit:
// Oh dear - 'NaN' could not be converted to an integer
```
### convert! and examine!
The following example shows how the `convert` and `examine` macros are used to simplify error
tracing. This is achieved by encapsulating rust methods and functions that return values in the form of
`Result<T, E>`. Using these macros affords the same error handling capabilities as the `here`
macro but in a more compact form.
Notice that the `convert` macro is used to translate the error produced by `text.parse` into a
`nuhound` error. The `examine` macro is used when the code generating an error is already a
`nuhound` type. It would, however, be possible to replace the `examine` macros in this example with
`convert`, but it is more code efficient to use `examine` whenever possible.
```
use nuhound::{Report, ResultExtension, examine, convert};
fn my_result() -> Report<()> {
let text = "NaN";
let _value = convert!(text.parse::<u32>(), "Oh dear - '{}' could not be \
converted to an integer", text)?;
Ok(())
}
fn layer2() -> Report<()> {
let _result = examine!(my_result(), "Layer 2 failure")?;
Ok(())
}
fn layer1() -> Report<()> {
let _result = examine!(layer2(), "Layer 1 failure")?;
Ok(())
}
match layer1() {
Ok(_) => unreachable!(),
Err(e) => {
#[cfg(feature = "disclose")]
eprintln!("{}", e.trace());
#[cfg(not(feature = "disclose"))]
eprintln!("{}", e);
},
}
// With the disclose feature enabled the code will emit:
// 0: src/main.rs:16:23: Layer 1 failure
// 1: src/main.rs:11:23: Layer 2 failure
// 2: src/main.rs:6:22: Oh dear - 'NaN' could not be converted to an integer
// 3: invalid digit found in string
//
// With the disclose feature disabled the code will emit:
// Layer 1 failure
```
### custom!
This example shows how the `custom!` macro could be used to generate an error based on a
conditional branch
```
use nuhound::{Report, ResultExtension, examine, custom};
fn my_custom() -> Report<()> {
let reason = "No reason at all";
if reason != "" {
custom!("This just fails because of: {}", reason)
} else {
Ok(())
}
}
fn layer2() -> Report<()> {
let _result = examine!(my_custom(), "Layer 2 failure")?;
Ok(())
}
fn layer1() -> Report<()> {
let _result = examine!(layer2(), "Top level failure")?;
Ok(())
}
match layer1() {
Ok(_) => unreachable!(),
Err(e) => {
#[cfg(feature = "disclose")]
eprintln!("{}", e.trace());
#[cfg(not(feature = "disclose"))]
eprintln!("{}", e);
},
}
// With the disclose feature enabled the code will emit:
// 0: src/main.rs:19:23: Top level failure
// 1: src/main.rs:14:23: Layer 2 failure
// 2: src/main.rs:7:13: This just fails because of: No reason at all
//
// With the disclose feature disabled the code will emit:
// Top level failure
```
### Option handling
The `convert!` macro can be used with an Option to handle 'None' as a type of error. In this
example we attempt to get a value from a vector with an out-of-range index. The 'get' will
return a None value that is handled by the `convert!` macro.
```
use nuhound::{Report, ResultExtension, OptionExtension, examine, convert};
fn my_option() -> Report<()> {
let vector = vec![0,1,2,3];
let index = 4;
let value = convert!(vector.get(index), "Index {index} is out of range")?;
println!("Value = {value}");
Ok(())
}
fn layer2() -> Report<()> {
let _result = examine!(my_option(), "Layer 2 failure")?;
Ok(())
}
fn layer1() -> Report<()> {
let _result = examine!(layer2(), "Top level failure")?;
Ok(())
}
match layer1() {
Ok(_) => unreachable!(),
Err(e) => {
#[cfg(feature = "disclose")]
eprintln!("{}", e.trace());
#[cfg(not(feature = "disclose"))]
eprintln!("{}", e);
},
}
// With the disclose feature enabled the code will emit:
// 0: src/main.rs:18:23: Top level failure
// 1: src/main.rs:13:23: Layer 2 failure
// 2: src/main.rs:7:21: Index 4 is out of range
// 3: Option::None detected
//
// With the disclose feature disabled the code will emit:
// Top level failure
```
### Using closures
The `convert` and `examine` macros may used with closures provided they are delimited with
curly braces. The example shown here encloses the vector get, as above, in a closure.
```
use nuhound::{Report, ResultExtension, OptionExtension, examine, convert};
fn my_closure_test() -> Report<()> {
let vector = vec![0,1,2,3];
let index = 4;
// Notice that the closure is delimited with curly braces
let _ = convert!({||
vector.get(index)
}(), "Index out of range")?;
Ok(())
}
fn layer2() -> Report<()> {
let _result = examine!(my_closure_test(), "Layer 2 failure")?;
Ok(())
}
fn layer1() -> Report<()> {
let _result = examine!(layer2(), "Top level failure")?;
Ok(())
}
match layer1() {
Ok(_) => unreachable!(),
Err(e) => {
#[cfg(feature = "disclose")]
eprintln!("{}", e.trace());
#[cfg(not(feature = "disclose"))]
eprintln!("{}", e);
},
}
// With the disclose feature enabled the code will emit:
// 0: src/main.rs:20:23: Top level failure
// 1: src/main.rs:15:23: Layer 2 failure
// 2: src/main.rs:8:17: Index out of range
// 3: Option::None detected
//
// With the disclose feature disabled the code will emit:
// Top level failure
```
## License
This project is licensed under either:
- Apache License, Version 2.0, ([LICENSE.apache-2.0](LICENSE.apache-2.0) or
https://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE.MIT](LICENSE.MIT) or
https://opensource.org/licenses/MIT)