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>>;