Crate error_tools

Source
Expand description

§Module :: error_tools

experimental rust-status docs.rs Open in Gitpod discord

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 and thiserror’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 for thiserror.
untyped
Untyped error handling, a facade for anyhow. Untyped error handling, a facade for anyhow.

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 of debug_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 for Result.
ErrWith
Trait to add extra context or information to an error.
ErrorTrait
Error is a trait representing the basic expectations for error values, i.e., values of type E in Result<T, E>.

Functions§

Ok
Equivalent to Ok::<_, anyhow::Error>(value).

Type Aliases§

Result
Result<T, Error>
ResultWithReport
A type alias for a Result that contains an error which is a tuple of a report and an original error.

Derive Macros§

Error