1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

//! `oi` provides a location-annotated error type so you can display useful
//! error messages to your users.
//!
//! Error messages without location information are often not actionable,
//! especially when they come from a complex program with many potential
//! sources of errors.
//!
//! Compare an unannotated error:
//!
//! ```sh
//! $ foo
//! No such file or directory (os error 2)
//! ```
//!
//! …with an annotated error:
//!
//! ```sh
//! $ foo
//! Configuration.toml: No such file or directory (os error 2)
//! ```
//!
//! `oi` is named after the exclamation, as in [Oi! Oi! Oi!](https://youtu.be/XWLU76o5rEI).
//! Imagine alerting your users to the location of errors: "Oi! 1.2.3.4 is unreachable!"
//!
//! ## usage
//!
//! This crate provides an `Error` type that wraps an error and location, a `Location`
//! trait for error locations, an `ErrAt` trait that extends `Result` with an
//! `err_at` method to annotate err values with locations, and a `Result<T, E, L>`
//! type as an alias for the more cumbersome `Result<T, Error<E, L>>`:
//!
//! ```rust
//! pub struct Error<E: Fail, L: Location> {
//!   pub error: E,
//!   pub location: L,
//! }
//!
//! pub trait Location: Debug + Send + Sync + 'static {
//!   fn fmt_error(&self, f: &mut Formatter, error: &dyn Fail) -> fmt::Result;
//! }
//!
//! pub trait ErrAt<T, E: Fail> {
//!   fn err_at<L: Location, I: Into<L>>(self, location: I) -> Result<T, Error<E, L>>;
//! }
//!
//! pub type Result<T, E, L> = std::result::Result<T, Error<E, L>>;
//! ```
//!
//! `Location` is implemented for `PathBuf` and `SocketAddr`, and can easily be implemented
//! for custom location types. The one required method, `fmt_error`, gives custom types
//! control over how an error-annotated location will be rendered to an error message.

mod err_at;
mod error;
mod location;

/// Location that an `Error` can occur
pub use location::Location;

/// Location-annotated error
pub use error::Error;

/// Extension-trait providing `err_at` convenience method for location-annotating `Result`s
pub use err_at::ErrAt;

/// Location-annotated Result
pub type Result<T, E, L> = std::result::Result<T, Error<E, L>>;