Crates.io | extracterr |
lib.rs | extracterr |
version | 0.1.1 |
source | src |
created_at | 2020-05-18 16:58:40.112247 |
updated_at | 2020-05-18 17:24:54.908759 |
description | helper type and traits for passing context through dyn Error trait objects |
homepage | |
repository | https://github.com/yaahc/extracterr |
max_upload_size | |
id | 243092 |
size | 23,154 |
Helpers for bundling context with errors and later extracting said context thru dyn Error
trait objects.
The primary purpose of this crate is to pass context to error reporters through dyn Error
trait objects. This is useful for information that may need to be captured by leaf errors but
which doesn't belong in any single error's message. Backtraces, http status codes, and help
messages are all examples of context that one might wish to pass directly to an error reporter
rather than printing in the chain of errors.
[dependencies]
extracterr = "0.1"
use backtrace::Backtrace;
use std::error::Error;
use extracterr::{Bundle, Bundled, Extract};
#[derive(Debug, thiserror::Error)]
#[error("Example Error")]
struct ExampleError;
let error = ExampleError;
// Capture a backtrace via `Default` and `From`
let error: Bundled<_, Backtrace> = error.into();
// Convert it to a trait object to throw away type information
let error: Box<dyn Error + Send + Sync + 'static> = error.into();
// first error in chain is the unerased version of the error `Bundled<ExampleError, Backtrace>`
assert!(error.downcast_ref::<Bundled<ExampleError, Backtrace>>().is_some());
assert_eq!("Example Error", error.to_string());
assert!(error.extract::<Backtrace>().is_none());
// Move to the next error in the chain
let error = error.source().unwrap();
// The second error in the chain is the erased version `Bundled<Erased, Backtrace>` which now
// works with downcasting, letting us access the bundled context
let backtrace = error.extract::<Backtrace>();
assert!(backtrace.is_some());
// The Display / Debug impls of the fake error that contains the bundled context print the
// context's type_name
assert_eq!(error.to_string(), std::any::type_name::<Backtrace>());
The main type provided by this library is the Bundled
type, which bundles an error and a
context type into a new error. This type can be constructed either via From+Default
or
Bundle
, for more details check out the docs on Bundled
.
This type works best with the error kind pattern, as seen in std::io::Error
:
use backtrace::Backtrace;
use extracterr::{Bundle, Bundled};
#[derive(Debug, thiserror::Error)]
#[error(transparent)]
struct Error {
kind: Bundled<Kind, Backtrace>,
}
#[derive(Debug, thiserror::Error, Clone, Copy)]
enum Kind {
#[error("could not enqueue item")]
Queue,
#[error("could not dequeue item")]
Dequeue
}
impl Error {
fn kind(&self) -> Kind {
*self.kind.inner()
}
}
impl From<Kind> for Error {
fn from(kind: Kind) -> Self {
Self { kind: Bundled::from(kind) }
}
}
impl From<Bundled<Kind, Backtrace>> for Error {
fn from(kind: Bundled<Kind, Backtrace>) -> Self {
Self { kind }
}
}
fn queue() -> Result<(), Error> {
Err(Kind::Queue)?
}
fn dequeue() -> Result<(), Error> {
Err(Kind::Dequeue).bundle(Backtrace::new())?
}
use extracterr::Extract;
let error = dequeue().unwrap_err();
// Convert it to a trait object to throw away type information
let error: Box<dyn std::error::Error + Send + Sync + 'static> = error.into();
assert!(error.downcast_ref::<Error>().is_some());
assert_eq!("could not dequeue item", error.to_string());
assert!(error.extract::<Backtrace>().is_none());
// Move to the next error in the chain
let error = error.source().unwrap();
let backtrace = error.extract::<Backtrace>();
assert!(backtrace.is_some());
Once context has been bundled into a chain of errors it can then be extracted back out via the
Extract
trait. Check out the source code of stable-eyre
for a simple example of
idiomatic usage of Extract
in an error reporter.