README.org

Goof

An early composable, and re-usable library for tiny structs that you would be writing on your own, but which you really shouldn’t.

use goof::{Mismatch, assert_eq};

fn fallible_func(thing: &[u8]) -> Result<(), Mismatch<usize>> {
	  assert_eq(&32, &thing.len())?;
	
	  Ok(())
}

assert_eq!(fallible_func(&[]).unwrap_err(), assert_eq(&32, &0).unwrap_err())

So why use it? It’s pre-alpha, so it’s not particularly useful yet. But imagine a situation in which you don’t really want to panic on failed assertions. These functions can then be a lightweight 1-1 replacement of the standard library `assert_eq!` macro. It will not panic immediately, but instead create a structure called rust_src{Mismatch}, which has all of the appropriate traits (except std::error::Error because I want to add std support, rather than subtract it) implemented.

These will participate in all manner of goodies, that don’t necessarily depend on std, but that can effectively make goof a one-stop-shop for all your error handling needs. It will hopefully be as useful as eyre and thiserror while providing a slightly different approach to designing error APIs.

Goals

Overarching API decisions

• Be no_std compatible. The structures should be easy to use across the FFI boundary, simple and hopefully predictable in their behaviours.
• Embedded-friendly. We want to act as if we have an allocator, while keeping all of the structures on-stack for as much as possible.
• All structs should attempt to be Copy-able if possible.
• Nudge users to avoid panics as much as possible.
• Ergonomic design. Commonly used patterns should be terse and maximally easy to write.
• Few to no dependencies.
• Few to no features.
• LTO-friendly code elimination.

Supported use-cases

• Contextual error propagation like the old =failure= crate.
  • Each error can have an optional wrapping structure which explains the context and helps in debugging.
  • Support for tracing spans, so that errors have tracing spans attached.
• Different error handling methods:
  • Fail fast, where any failed assertion immediately produces the corresponding error and is being propagated upwards.
  • Fail completely, where any failure will stop some logic from being executed, but will accumulate errors instead of immediately propagating them upwards.
  • Fail recoverably, where functions to try and catch specific failure modes can be applied to recover from some, but not all error conditions.
  • Resumable error, where any form of failure is propagated up the call stack, but the failure can be corrected and the function can be resumed.
• Pretty printing, like in eyre, and (hopefully) like in miette.

Progress

The library is in its early stages. I’m planning on approaching this from the minimalist perspective, of making a bunch of 0.* versions and when the library is complete, releasing the 1.0 version. While this is in no way a pre-release candidate and as is, it should be ready for production use, I would recommend not spending too much time worrying about the changes in the newer versions. Update as you see fit, if you do, I will be providing detailed notes on how to make the jump.

Changelog

• 0.1.0
  • Initial, extremely basic implementation of Mismatch,

  Outside and Unknown structures.

  • Initial implementations of assert_eq, assert_in, assert_known_enum, and assert_known.
• 0.2.0
  • Swapped around arguments in assert_eq for more consistency.