Track and put down bugs using simple concise error handling
Avoid terminating execution randomly in your code with panics via unwrap and expect varients,
or laboriously writing custom enum wrapers, or having to work with Box types which is messy;
instead use Result<T> from witcher as the return type and wrap errors easily for additional
contextual messaging automatically propogated up the stack. witcher implements std::error::Error
retaining downcasting and chaining. Best of all witcher provides the holy grail: automatic
simplified backtraces.
std::error::Error unsafe Coming from a Golang background, most recently, I fully expected to just import the defacto standard
error package in Rust similar to something like Golang's pkg/errors
and I'd be off to the races. Instead, as I dug, I found a rich anthropological layered history of
a myriad of projects and authors all professing nobal ideals and principles all trying to solve the
same issue. Rust's error handling story isn't full featured enough by itself yet. It feels a lot like
Golang's before the existance of pkg/errors. I found a few projects clearly more used than others
and saw the tide turn on once popular packages. Literally weeks of research and testing of numerous
different patterns and packages later though I have still yet to find anything as simple and usable
as the venerable pkg/errors. Thus witcher was born.
As a side note I moved all my research on low level TraitObject manipulation, when I was going down
the rabbit hole, over to phR0ze/rust-examples and am happy
to say witcher is 100% safe code.
Use the wrap extension method on Result types to wrap the error with additional contextual
messaging and automatically chain errors together. wrap returns a Result<T> so there are fewer
symbols and less typing needed.
source methodImport witcher in your Cargo.toml and keep debug symbols
```toml
[dependencies]
witcher = "0.1"
[profile.release] debug = true ```
rust
use witcher::prelude::*;
Result<T> alias as your return type
rust
fn do_something() -> Result<()>;
wrap extension method on Result to provide context
rust
fn do_something() -> Result<()> {
do_external_thing().wrap("Failed to slay beast")
}
fn do_external_thing() -> std::io::Result<()> {
Err(std::io::Error::new(std::io::ErrorKind::Other, "Oh no, we missed!"))?
}
Color is automatically controlled by the gory based on tty
detection. You can disable color manually by setting the TERM_COLOR environment variable to
something falsy see gory docs on controlling use.
bash
$ TERM_COLOR=0 cargo run -q --example simple
We can match on error types using downcasting or with the match_err! macro.
downcast_ref - access std::error::Error's downcast_ref ```rust use witcher::prelude::*;
// Wrap our internal error with additional context as we move up the stack fn dosomething() -> Result<()> { doexternal_thing().wrap("Failed to slay beast") }
// Function that returns an external error type outside our codebase fn doexternalthing() -> std::io::Result<()> { Err(std::io::Error::new(std::io::ErrorKind::Other, "Oh no, we missed!"))? }
fn main() { let err = dosomething().unwraperr();
// Get the last error in the error chain which will be the root cause
let root_cause = err.last();
// Match single concrete error type
if let Some(e) = root_cause.downcast_ref::<std::io::Error>() {
println!("Root cause is a std::io::Error: {}", e)
} else {
println!("{}", err)
}
} ```
match_err! - matches on concrete error typese ```rust use witcher::prelude::*;
fn dosomething() -> Result<()> { doexternal_thing().wrap("Failed to slay beast") }
fn doexternalthing() -> std::io::Result<()> { Err(std::io::Error::new(std::io::ErrorKind::Other, "Oh no, we missed!"))? }
fn main() { let err = dosomething().unwraperr();
// Match multiple downcasted cases to handle errors differently
match_err!(err.last(), {
x: Error => println!("Root cause is witcher::Error: {}", x),
x: std::io::Error => println!("Root cause is std::io::Error: {}", x),
_ => println!("{}", err)
});
} ```
We can continue to leverage std::error::Error's source method for chaining of errors. The first
error wrapped will retain its concrete type but errors there after in the chain have lost that
information.
source - std::error::Error's source method is exposed ```rust use witcher::prelude::*;
struct SuperError { side: SuperErrorSideKick, } impl std::fmt::Display for SuperError { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { write!(f, "SuperError is here!") } } impl std::error::Error for SuperError { fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { Some(&self.side) } }
struct SuperErrorSideKick; impl std::fmt::Display for SuperErrorSideKick { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { write!(f, "SuperErrorSideKick is here!") } } impl std::error::Error for SuperErrorSideKick {}
fn dosomething() -> Result<()> { doexternal_thing().wrap("Failed doing super hero work") }
fn doexternalthing() -> std::result::Result<(), SuperError> { Err(SuperError {side: SuperErrorSideKick}) }
fn main() { if let Err(err) = do_something() {
// Traverse the error chain
let mut source = Some(err.std());
while let Some(err) = source {
match_err!(err, {
// Using alternate form of display for `Error` to get just the message
x: Error => println!("Found witcher::Error: {:#}", x),
x: SuperError => println!("Found SuperError: {}", x),
x: SuperErrorSideKick => println!("Found SuperErrorSideKick: {}", x),
_ => println!("unknown")
});
source = err.source();
}
}
} ```
We can retry failing code with a few different Result extension functions.
err_is - will return true if an error exists and is the given type ```rust use witcher::prelude::*;
fn retryonconcreateerrortypeusingerris() -> Result<()> {
let mut retries = 0;
let mut result = doexternalthing();
while retries < 3 && result.erris::
fn main() { println!("{}", retryonconcreateerrortypeusingerris().unwraperr()); } ```
retry_on - is a cleaner simplified way to do a similar thing as our err_is example ```rust use witcher::prelude::*;
fn retryonconcreateerrortype() -> Result<()> {
doexternalthing().retryon(3, TypeId::of::
fn main() { println!("{}", retryonconcreateerrortype().unwrap_err()); } ```
retry - is similar to retry_on but doesn't take the type of error into account ```rust use witcher::prelude::*;
fn retry() -> Result<()> { doexternalthing().retry(3, |i| { println!("std::io::Error: retrying! #{}", i); doexternalthing() }).wrap("Failed while attacking beast") } fn doexternalthing() -> std::io::Result<()> { Err(std::io::Error::new(std::io::ErrorKind::Other, "Oh no, we missed!")) }
fn main() { println!("{}", retry().unwrap_err()); } ```
Witcher's Error type implements different functionality for each of the Display format options.
They follow a level of verbosity in witcher from least information to most i.e. {} {:#} {:?} {:#?}
Normal: {} - will write out the first error message only 
Alternate: {:#} - will write out all error messages in the chain 
Debug: {:?} - will write out all error messaging with simplified backtracing
Alternate Debug: {:#?} - will write out all error messaging with simplified backtracing 
Pull requests are always welcome. However understand that they will be evaluated purely on whether or not the change fits with my goals/ideals for the project.
Enable the git hooks to have automatic version increments
bash
cd ~/Projects/witcher
git config core.hooksPath .githooks
This project is licensed under either of: * MIT license LICENSE-MIT or http://opensource.org/licenses/MIT * Apache License, Version 2.0 LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
{:#?}