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
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
//! ## Intro
//!
//! Key feature of the `error-rules` is chained error handling.
//!
//! Idea is simple, each module has own error handler.
//! Source error wrapped into error handler with configurable display text.
//!
//! ## Declaring error types
//!
//! Macro `error_rules!` implements `Error`, `Result` types and all necessary traits for `Error`.
//! All arguments should be comma-separated.
//!
//! To prevent types shadowing all errors from standard library and other crates should be used
//! with module name. For example: `io::Error`.
//!
//! ## Display format
//!
//! Error display text defines in tuple after `Error =>` keyword.
//! First tuple argument is a format string. Additional arguments:
//!
//! - `error` - chained error text
//!
//! ```
//! use error_rules::*;
//!
//! error_rules! {
//! Error => ("app error => {}", error)
//! }
//!
//! assert_eq!(
//! Error::from("error message").to_string().as_str(),
//! "app error => error message");
//! ```
//!
//! ## Error types
//!
//! After display text you could define error types for conversions into `Error` chain.
//! By the default implements conversion for: `&str`, `String`
//!
//! ```
//! use std::io;
//! use error_rules::*;
//!
//! error_rules! {
//! Error => ("app error => {}", error),
//! std::io::Error,
//! }
//!
//! let io_error = io::Error::new(io::ErrorKind::Other, "io-error");
//! assert_eq!(
//! Error::from(io_error).to_string().as_str(),
//! "app error => io-error");
//! ```
//!
//! ## Custom error types
//!
//! Custom errors is an additional error kind to use with `Error`.
//! Defines like `struct` with display arguments after `=>` keyword.
//! Could be defined without fields:
//!
//! ```
//! # use error_rules::*;
//! error_rules! {
//! Error => ("app error => {}", error),
//! CustomError => ("custom error"),
//! }
//!
//! assert_eq!(
//! Error::from(CustomError).to_string().as_str(),
//! "app error => custom error");
//! ```
//!
//! or with fields:
//!
//! ```
//! # use error_rules::*;
//! error_rules! {
//! Error => ("app error => {}", error),
//! CustomError(usize) => ("custom error value:{}", 0),
//! }
//!
//! assert_eq!(
//! Error::from(CustomError(100)).to_string().as_str(),
//! "app error => custom error value:100");
//! ```
//!
//! or with named fields:
//!
//! ```
//! # use error_rules::*;
//! error_rules! {
//! Error => ("app error => {}", error),
//! CustomError {
//! value: usize,
//! } => ("custom error value:{}", value),
//! }
//!
//! assert_eq!(
//! Error::from(CustomError { value: 100 }).to_string().as_str(),
//! "app error => custom error value:100");
//! ```