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

#+BEGIN_SRC 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())
#+END_SRC

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