Expand description
§Module :: error_tools
error_tools
is a foundational library for error handling in Rust, providing a unified interface over the popular anyhow
and thiserror
crates. It simplifies error management by offering clear, consistent patterns for both untyped and typed errors, without requiring you to choose between them at the crate level.
§Key Features
- Unified Error Handling: Use
anyhow
’s flexibility andthiserror
’s structure through a single, consistent API. - Simple Prelude: A comprehensive
prelude
makes it easy to import everything you need. - Contextual Errors: Easily add context to your errors with the
ErrWith
trait.
§How It Works
error_tools
acts as a facade, re-exporting the core functionalities of anyhow
and thiserror
under its untyped
and typed
modules, respectively. This allows you to leverage the power of these crates with simplified imports and a consistent feel across your project.
§Untyped Errors (like anyhow
)
For functions where you need flexible, dynamic error handling without defining custom error types for every possible failure, use the untyped
module. It’s a direct pass-through to anyhow
.
§Example
This example shows a function that reads a file and can fail in multiple ways, all handled by error_tools::untyped::Result
.
// In your code:
use error_tools::untyped::{ Result, Context, format_err };
fn read_and_process_file( path : &str ) -> Result< String >
{
let content = std::fs::read_to_string( path )
.context( format_err!( "Failed to read file at '{}'", path ) )?;
if content.is_empty()
{
return Err( format_err!( "File is empty!" ) );
}
Ok( content.to_uppercase() )
}
See the full runnable example in
examples/replace_anyhow.rs
.
§Typed Errors (like thiserror
)
For library code or situations where you want to define a clear, structured contract for possible errors, use the typed
module. It re-exports thiserror
’s Error
derive macro.
§Example
Here, we define a custom DataError
enum. The #[derive(Error)]
macro comes directly from error_tools
.
Note: When using #[derive(Error)]
or other thiserror
macros, thiserror
must be explicitly present in the namespace. This can be achieved by adding use error_tools::dependency::thiserror;
or use thiserror;
in your module, depending on your project’s setup.
// In your code:
use error_tools::typed::Error;
use std::path::PathBuf;
// The derive macro is re-exported for convenience.
#[ derive( Debug, Error ) ]
pub enum DataError
{
#[ error( "I/O error for file: {0}" ) ]
Io( std::io::Error, PathBuf ),
#[ error( "Parsing error: {0}" ) ]
Parse( String ),
}
// Manual implementation of From trait for DataError
impl From< std::io::Error > for DataError
{
fn from( err : std::io::Error ) -> Self
{
DataError::Io( err, PathBuf::new() )
}
}
fn process_data( path : &PathBuf ) -> Result< i32, DataError >
{
let content = std::fs::read_to_string( path )
.map_err( | e | DataError::Io( e, path.clone() ) )?;
content.trim().parse::< i32 >()
.map_err( | _ | DataError::Parse( "Could not parse content as integer".into() ) )
}
See the full runnable example in
examples/replace_thiserror.rs
.
§To add to your project
cargo add error_tools
§Try out from the repository
git clone https://github.com/Wandalen/wTools
cd wTools
cargo run --example error_tools_trivial
# Or try the specific examples
cargo run --example replace_anyhow
cargo run --example replace_thiserror
Modules§
- assert
- Assertions.
- dependency
- Namespace with dependencies.
- error
- Core error handling utilities. Core error handling utilities.
- prelude
- Prelude to use essentials:
use error_tools::prelude::*
. - typed
- Typed error handling, a facade for
thiserror
. Typed error handling, a facade forthiserror
. - untyped
- Untyped error handling, a facade for
anyhow
. Untyped error handling, a facade foranyhow
.
Macros§
- anyhow
- Construct an ad-hoc error from a string or existing non-
anyhow
error value. - bail
- Return early with an error.
- debug_
assert_ id - Macro asserts that two expressions are identical to each other. Unlike
std::assert_eq
it is removed from a release build. - debug_
assert_ identical - Macro asserts that two expressions are identical to each other. Unlike
std::assert_eq
it is removed from a release build. Alias ofdebug_assert_id
. - debug_
assert_ ni - Macro asserts that two expressions are not identical to each other. Unlike
std::assert_eq
it is removed from a release build. - debug_
assert_ not_ identical - Macro asserts that two expressions are not identical to each other. Unlike
std::assert_eq
it is removed from a release build. - ensure
- format_
err - Construct an ad-hoc error from a string or existing non-
anyhow
error value.
Structs§
- Error
- The
Error
type, a wrapper around a dynamic error type.
Traits§
- Context
- Provides the
context
method forResult
. - ErrWith
- Trait to add extra context or information to an error.
- Error
Trait Error
is a trait representing the basic expectations for error values, i.e., values of typeE
inResult<T, E>
.
Functions§
- Ok
- Equivalent to Ok::<_, anyhow::Error>(value).
Type Aliases§
- Result
Result<T, Error>
- Result
With Report - A type alias for a
Result
that contains an error which is a tuple of a report and an original error.