[−][src]Crate eyre
This library provides eyre::ErrReport
, a trait object based error
type for easy idiomatic error handling in Rust applications.
Details
-
Use
Result<T, eyre::ErrReport>
, or equivalentlyeyre::Result<T>
, as the return type of any fallible function.Within the function, use
?
to easily propagate any error that implements thestd::error::ErrReport
trait.use eyre::Result; fn get_cluster_info() -> Result<ClusterMap> { let config = std::fs::read_to_string("cluster.json")?; let map: ClusterMap = serde_json::from_str(&config)?; Ok(map) }
-
Create new errors from messages to help the person troubleshooting the error understand where things went wrong. A low-level error like "No such file or directory" can be annoying to directly and often benefit from being wrapped with higher level error messages.
use eyre::{WrapErr, Result}; fn main() -> Result<()> { ... it.detach().wrap_err("Failed to detach the important thing")?; let content = std::fs::read(path) .wrap_err_with(|| format!("Failed to read instrs from {}", path))?; ... }
Error: Failed to read instrs from ./path/to/instrs.json Caused by: No such file or directory (os error 2)
-
Downcasting is supported and can be by value, by shared reference, or by mutable reference as needed.
// If the error was caused by redaction, then return a // tombstone instead of the content. match root_cause.downcast_ref::<DataStoreError>() { Some(DataStoreError::Censored(_)) => Ok(Poll::Ready(REDACTED_CONTENT)), None => Err(error), }
-
A backtrace is captured and printed with the error if the underlying error type does not already provide its own. In order to see backtraces, the
RUST_LIB_BACKTRACE=1
environment variable must be defined. -
Eyre works with any error type that has an impl of
std::error::Error
, including ones defined in your crate. We do not bundle aderive(Error)
macro but you can write the impls yourself or use a standalone macro like thiserror.use thiserror::Error; #[derive(Error, Debug)] pub enum FormatError { #[error("Invalid header (expected {expected:?}, got {found:?})")] InvalidHeader { expected: String, found: String, }, #[error("Missing attribute: {0}")] MissingAttribute(String), }
-
One-off error messages can be constructed using the
eyre!
macro, which supports string interpolation and produces aneyre::ErrReport
.return Err(eyre!("Missing attribute: {}", missing));
No-std support
In no_std mode, the same API is almost all available and works the same way. To depend on Eyre in no_std mode, disable our default enabled "std" feature in Cargo.toml. A global allocator is required.
[dependencies]
eyre = { version = "0.3", default-features = false }
Since the ?
-based error conversions would normally rely on the
std::error::ErrReport
trait which is only available through std, no_std mode
will require an explicit .map_err(ErrReport::msg)
when working with a
non-Eyre error type inside a function that returns Eyre's error type.
Re-exports
pub use eyre as format_err; |
Macros
bail | Return early with an error. |
ensure | Return early with an error if a condition is not satisfied. |
eyre | Construct an ad-hoc error from a string. |
Structs
Chain | Iterator of a chain of source errors. |
DefaultContext | |
ErrReport | The |
Traits
EyreContext | |
WrapErr | Provides the |
Type Definitions
Result |
|