[announcement post]: https://hash.dev/blog/announcing-error-stack
[crates.io]: https://crates.io/crates/anystack
[libs.rs]: https://lib.rs/crates/anystack
[rust-version]: https://www.rust-lang.org
[documentation]: https://docs.rs/anystack
[license]: https://github.com/zakstucke/anystack/LICENSE.md
[][crates.io]
[][libs.rs]
[][rust-version]
[][documentation]
[][license]
# anystack
**`anystack` is a context-aware error-handling library that supports arbitrary attached user data.**
Read our [announcement post] for the story behind its origins.
The library enables building a `Report` around an error as it propagates:
```rust
use core::{error::Error, fmt};
use anystack::{Report, ResultExt};
#[derive(Debug)]
struct ParseExperimentError;
impl fmt::Display for ParseExperimentError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str("invalid experiment description")
}
}
impl Error for ParseExperimentError {}
fn parse_experiment(description: &str) -> Result<(u64, u64), Report<ParseExperimentError>> {
let value = description
.parse::<u64>()
.attach_printable_lazy(|| format!("{description:?} could not be parsed as experiment"))
.change_context(ParseExperimentError)?;
Ok((value, 2 * value))
}
#[derive(Debug)]
struct ExperimentError;
impl fmt::Display for ExperimentError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str("experiment error: could not run experiment")
}
}
impl Error for ExperimentError {}
fn start_experiments(
experiment_ids: &[usize],
experiment_descriptions: &[&str],
) -> Result<Vec<u64>, Report<ExperimentError>> {
let experiments = experiment_ids
.iter()
.map(|exp_id| {
let description = experiment_descriptions.get(*exp_id).ok_or_else(|| {
Report::new(ExperimentError)
.attach_printable(format!("experiment {exp_id} has no valid description"))
})?;
let experiment = parse_experiment(description)
.attach_printable(format!("experiment {exp_id} could not be parsed"))
.change_context(ExperimentError)?;
Ok(move || experiment.0 * experiment.1)
})
.collect::<Result<Vec<_>, Report<ExperimentError>>>()
.attach_printable("unable to set up experiments")?;
Ok(experiments.iter().map(|experiment| experiment()).collect())
}
fn main() -> Result<(), Report<ExperimentError>> {
let experiment_ids = &[0, 2];
let experiment_descriptions = &["10", "20", "3o"];
start_experiments(experiment_ids, experiment_descriptions)?;
Ok(())
}
```
This will most likely result in an error and print
<pre>
Error: <b>experiment error: could not run experiment</b>
├╴at <i>examples/demo.rs:50:18</i>
├╴unable to set up experiments
│
├─▶ <b>invalid experiment description</b>
│ ├╴at <i>examples/demo.rs:20:10</i>
│ ╰╴experiment 2 could not be parsed
│
╰─▶ <b>invalid digit found in string</b>
├╴at <i>examples/demo.rs:19:10</i>
├╴backtrace with 31 frames (1)
╰╴"3o" could not be parsed as experiment
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
backtrace no. 1
0: std::backtrace_rs::backtrace::libunwind::trace
at /rustc/f3623871cfa0763c95ebd6ceafaa6dc2e44ca68f/library/std/src/../../backtrace/src/backtrace/libunwind.rs:93:5
1: std::backtrace_rs::backtrace::trace_unsynchronized
at /rustc/f3623871cfa0763c95ebd6ceafaa6dc2e44ca68f/library/std/src/../../backtrace/src/backtrace/mod.rs:66:5
2: std::backtrace::Backtrace::create
at /rustc/f3623871cfa0763c95ebd6ceafaa6dc2e44ca68f/library/std/src/backtrace.rs:331:13
3: core::ops::function::FnOnce::call_once
at /rustc/f3623871cfa0763c95ebd6ceafaa6dc2e44ca68f/library/core/src/ops/function.rs:250:5
4: core::bool::<impl bool>::then
at /rustc/f3623871cfa0763c95ebd6ceafaa6dc2e44ca68f/library/core/src/bool.rs:60:24
5: anystack::report::Report<C>::from_frame
at ./src/report.rs:286:25
6: anystack::report::Report<C>::new
at ./src/report.rs:272:9
7: anystack::context::<impl core::convert::From<C< for anystack::report::Report<C>>::from
at ./src/context.rs:83:9
8: <core::result::Result<T,C< as anystack::result::ResultExt<::attach_printable_lazy
at ./src/result.rs:158:31
9: demo::parse_experiment
at demo.rs:17:17
10: demo::start_experiments::{{closure}}
at demo.rs:48:30
(<b>For this example:</b> additional frames have been removed)
</pre>
## Usage
Please see the [documentation].
For more examples of `anystack` in use, please check out the [examples](https://github.com/zakstucke/anystack/examples) folder.
<br>
#### License
<sup>
Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
</sup>
<br>
<sub>
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
be dual licensed as above, without any additional terms or conditions.
</sub>