error_annotation/lib.rs
1#![doc = include_str!("../README.md")]
2
3//! Add useful diagnostic information to error values as they propagate.
4//!
5//! # Annotatable Error Types
6//!
7//! The most ergonomic usage is available for types that implement [`Annotatable`] via the
8//! [`AnnotateResult::annotate_err_into`] method, which is implemented for `Result`. In this case,
9//! diagnostic annotations can be built up without altering the resulting error types. An example
10//! using the `std::io::Error` impl of `Annotatable` clarifies these ergonomics:
11//!
12//! ## Example: Chaining Diagnostic Annotations on `std::io::Error`
13//!
14//! ```
15//! use std::path::{Path, PathBuf};
16//! use std::fs::Metadata;
17//! use error_annotation::{AnnotateResult, ErrorAnnotation};
18//!
19//! fn annotated_copy(src: &Path, dst: &Path) -> std::io::Result<u64> {
20//! std::fs::copy(src, dst)
21//! .annotate_err_into("source", || src.display())
22//! .annotate_err_into("destination", || dst.display())
23//! }
24//!
25//! let badsource = PathBuf::from("/this/path/does/not/exist");
26//! let dest = PathBuf::from("/tmp/woah-dude");
27//! let res = annotated_copy(&badsource, &dest);
28//! let err = res.err().unwrap();
29//!
30//! assert_eq!(&err.to_string(), "
31//!
32//! No such file or directory (os error 2)
33//! -with source: /this/path/does/not/exist
34//! -with destination: /tmp/woah-dude
35//!
36//! ".trim());
37//! ```
38//!
39//! # Annotating Other Error Types
40//!
41//! It is still possible to annotate an arbitrary error type `T` which does not implement [`Annotatable`]
42//! with annotation info type `I` by way of the [`ErrorAnnotation`]
43//! parameterized type. The downside being each annotation corresponds to a different
44//! parameterization, ie `ErrorAnnotation<T, I>`, which propagates out of interfaces and must be
45//! explicitly handled by consuming code.
46
47mod annotatable;
48mod annotate;
49mod annres;
50mod ea;
51
52pub use self::annotatable::Annotatable;
53pub use self::annotate::annotate;
54pub use self::annres::AnnotateResult;
55pub use self::ea::ErrorAnnotation;
56
57#[cfg(test)]
58mod tests;