how.rs/README.md

# *How*

A seriously contextual error library that focuses on how you got there. Designed to make debugging easier, *how* enables you to concisely capture any and all context that could possibly have contributed to an error.

## Getting started

A basic example takes just 2 imports:

```rust,should_panic
use how::{How, Result};

fn main() -> Result<()> {
	Err(How::new("TODO: implement amazing new program"))
}
```

But usually you'll want to [attach some information](Explain::context) too:
```rust,should_panic
use how::{How, Explain, Result};

fn main() -> Result<()> {
	Err(How::new("TODO: implement amazing new program")
        .context("I plan to do it eventually™"))
}
```

And you'll probably want to get [nicer output](TerminationResult) when you return an error from `main` (this one requires `feature = "termination"`):
```rust,should_panic,compile_fail
use how::{How, Explain, Result, TerminationResult};

fn main() -> TerminationResult<()> {
	Err(How::new("TODO: implement amazing new program")
        .context("I plan to do it eventually™"))
        .into()
}
```

[`How`] intentionally omits a [`From`] implementation for [`Error`](std::error::Error) to discourage the creation of [`How`]s with no caller context. Instead, the [`Explain`] trait is implemented for all [`Result`][^1] and [`Option`] and provides a convenient [`context`](Explain::context) function.

[^1]: Where `E` is either [`How`] or implements [`Error + 'static`](std::error::Error).