Skip to content

Latest commit

 

History

History
99 lines (82 loc) · 3.94 KB

README.md

File metadata and controls

99 lines (82 loc) · 3.94 KB
Raw

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 `asserteq!` macro. It will not panic immediately, but instead create a structure called rustsrc{Mismatch}, which has all of the appropriate traits (except std::error::Error{.verbatim} because I want to add std{.verbatim} support, rather than subtract it) implemented.

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

Goals

Overarching API decisions

  • Be no_std{.verbatim} 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{.verbatim}-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{.verbatim} 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{.verbatim}, and (hopefully) like in miette{.verbatim}.

Progress

The library is in its early stages. I'm planning on approaching this from the minimalist perspective, of making a bunch of 0.*{.verbatim} versions and when the library is complete, releasing the 1.0{.verbatim} 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{.verbatim}, Outside{.verbatim} and Unknown{.verbatim} structures.
    • Initial implementations of assert_eq{.verbatim}, assert_in{.verbatim}, assert_known_enum{.verbatim}, and assert_known{.verbatim}.
  • 0.2.0
    • Swapped around arguments in assert_eq{.verbatim} for more consistency.