hb_error/
lib.rs

1//! This crate defines from error related traits and generic implementations
2//! used by other hb projects.
3//! # ConvertFrom and ConvertTo
4//! The [ConvertFrom] and [ConvertInto] traits as well as the default implementations
5//! are used to allow easy handling of Result objects. See hb_macro for use cases.
6//! ## Example
7//! ```
8//! use hb_error::*;
9//!
10//! #[hberror]
11//! struct ExampleError {
12//!     #[Source]
13//!     IoError: std::io::Error,
14//! }
15//! // Convert from IO Error into a ParseError as ParseError implements the From<std::io::Error> trait
16//! let er: Result<(),ExampleError> = Result::<(),std::io::Error>::Err(std::io::Error::new(std::io::ErrorKind::AlreadyExists, "Example IO Error.")).convert();
17//! ```
18//! # Context and Context Documentation
19//! the [context] and [context_doc] macros allow a simplified way to add context into errors that are
20//! generated within the functions. The example below shows how simple it is to set up a error type
21//! that can support auto-conversion and adding context via the [context] and [context_doc] macros.
22//! See [context], [context_doc] and [hberror] for more information on what that macro scaffolds for
23//! the error types.
24//!
25//! ```
26//! use hb_error::*;
27//!
28//! #[hberror]
29//! struct ExampleError {
30//!     #[Source]
31//!     IoError: std::io::Error,
32//! }
33//!
34//! //Some functions to generate errors for the examples
35//! fn io_error() -> std::io::Result<()> {
36//! Err(std::io::Error::new(
37//! std::io::ErrorKind::AlreadyExists,
38//! "Example IO Error.",
39//! ))
40//! }
41//!
42//! fn example_error() -> Result<(), ExampleError> {
43//! Err(ExampleError::new().msg("Generated ExampleError."))
44//! }
45//!
46//! // Example
47//! // Add context onto a fall through Err object of type ExampleError
48//! // The fall through Err before the macro adds context will be:
49//! // ExampleError {
50//! //   msg: "Generated ExampleError.",
51//! //   inner_error: vec![]
52//! // }
53//! //
54//! // The err returned from this function (ie after the context macro changes it) will be:
55//! // ExampleError {
56//! //   msg: "additional context - basic example",
57//! //   inner_error: vec!["Generated ExampleError."]
58//! // }
59//! #[context("addition context - basic example")]
60//! fn basic_exampleerror() -> Result<(), ExampleError> {
61//! example_error()
62//! }
63//!
64//! // Example
65//! // Convert from an io::Error into a ExampleError and add context
66//! // The io::Error before conversion will be
67//! // std::io::Error::new(
68//! //     std::io::ErrorKind::AlreadyExists,
69//! //     "Example IO Error.",
70//! // )
71//! //
72//! // after conversion but before the context is added the ExampleError will be:
73//! // ExampleError {
74//! //   msg: "encountered an IO Error",
75//! //   inner_error: vec![]
76//! // }
77//! //
78//! // The final error will be:
79//! // ExampleError {
80//! //   msg: "additional context - basic example" ,
81//! //   inner_error: vec!["encountered an IO Error"]
82//! // }
83//! #[context("addition context - basic example")]
84//! fn basic5_exampleerror() -> Result<(), ExampleError> {
85//! return io_error();
86//! }
87//! ```
88//! See examples\error_example.rs for more examples.
89
90pub use hb_macros::*;
91mod convert;
92pub use convert::*;
93mod context;
94pub use context::*;
95
96// TODO when documenting features comes to stable rust then add appropriate flags so the
97// example docs are displayed.
98//#[hberror("{self.code}: {self.msg}{self.inner_msgs.join(\"\n...because...\")}")]
99//pub struct exampleerror {
100//#[default(0)]
101//code: i32,
102//#[source]
103//ioerror: std::io::error,
104//}
hb_error/lib.rs

hb_error/
lib.rs
