# 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.

``` rust

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`{.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}](https://docs.rs/failure/latest/failure/)
    crate.
    -   Each error can have an optional wrapping structure which
        explains the context and helps in debugging.
    -   Support for [tracing
        spans](https://docs.rs/tracing/latest/tracing/), 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.