Expand description
SNAFU
SNAFU is a library to easily assign underlying errors into domain-specific errors while adding context. For detailed information, please see the user’s guide.
Quick example
This example mimics a (very poor) authentication process that
opens a file, writes to a file, and checks the user’s ID. While
two of our operations involve an io::Error
,
these are different conceptual errors to us.
SNAFU creates a context selector type for each variant in the
error enum. These context selectors are used with the
context
method to provide ergonomic error
handling.
use snafu::{ensure, Backtrace, ErrorCompat, ResultExt, Snafu};
use std::{
fs,
path::{Path, PathBuf},
};
#[derive(Debug, Snafu)]
enum Error {
#[snafu(display("Could not open config from {}: {}", filename.display(), source))]
OpenConfig {
filename: PathBuf,
source: std::io::Error,
},
#[snafu(display("Could not save config to {}: {}", filename.display(), source))]
SaveConfig {
filename: PathBuf,
source: std::io::Error,
},
#[snafu(display("The user id {} is invalid", user_id))]
UserIdInvalid { user_id: i32, backtrace: Backtrace },
}
type Result<T, E = Error> = std::result::Result<T, E>;
fn log_in_user<P>(config_root: P, user_id: i32) -> Result<bool>
where
P: AsRef<Path>,
{
let config_root = config_root.as_ref();
let filename = &config_root.join("config.toml");
let config = fs::read(filename).context(OpenConfig { filename })?;
// Perform updates to config
fs::write(filename, config).context(SaveConfig { filename })?;
ensure!(user_id == 42, UserIdInvalid { user_id });
Ok(true)
}
fn log_in() {
match log_in_user(CONFIG_DIRECTORY, USER_ID) {
Ok(true) => println!("Logged in!"),
Ok(false) => println!("Not logged in!"),
Err(e) => {
eprintln!("An error occurred: {}", e);
if let Some(backtrace) = ErrorCompat::backtrace(&e) {
println!("{}", backtrace);
}
}
}
}
Macros
- Ensure a condition is true. If it is not, return from the function with an error.
Structs
- A backtrace starting from the beginning of the thread.
Traits
- Converts the receiver into an
Error
trait object, suitable for use inError::source
. - Backports changes to the
Error
trait to versions of Rust lacking them. - Construct a backtrace, allowing it to be optional.
- Combines an underlying error with additional information about the error.
- Additions to
Option
. - Additions to
Result
.
Derive Macros
- See the crate-level documentation for SNAFU which contains tested examples of this macro.