apperr

Check-in Differences
Login

Check-in Differences

Hide Diff Invert Patch Path Side-by-Side Diff

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Difference From apperr-0.1.0 To apperr-0.2.0

2024-01-14
09:42
Cleanup changelog. Leaf check-in: 8b4c57bd25 user: jan tags: trunk
09:26
Release maintenance. check-in: dd1cb44b41 user: jan tags: trunk, apperr-0.2.0
09:18
Add a Blessed trait and make it, and std::error::Error, a requirement for the AppErr::new() constructor. check-in: 5300d25ee8 user: jan tags: trunk
2023-12-12
05:01
Release maintenance. check-in: 384535b834 user: jan tags: trunk, apperr-0.1.0
2023-12-11
15:55
Crate metadata. check-in: f36ab0b281 user: jan tags: trunk

Changes to Cargo.toml. 

1
2
3

4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

1
2

3
4
5
6
7
8
9
10
11
12
13
14
15
16


17
18
19



-
+













-
-




[package]
name = "apperr"
version = "0.1.0"
version = "0.2.0"
license = "0BSD"
keywords = [ "any", "error", "callback" ]
repository = "https://repos.qrnch.tech/pub/apperr"
description = "A thin special-purpose wrapper around Any."
rust-version = "1.0"
exclude = [
  ".fossil-settings",
  ".efiles",
  ".fslckout",
  "www",
  "rustfmt.toml"
]

[dependencies]

[package.metadata.docs.rs]
rustdoc-args = ["--generate-link-to-definition"]

Changes to src/lib.rs. 

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
105

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
105
106
107
108
109
110

111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170








+
+
+
+







+


+
+
+
+
















+
-
+

+



+
+
+
+
+
+
+
+
+
+
+
+




-
+







+
-
+

+



+
+
+
+
+
+
+
+
+
+
+
+


















+
-
+

+



+
+
+
+
+
+
+
+
+
+
+
+
















+
-
+

+



+
+
+
+
+
+
+
+
+
+
+
+








//! _AppErr_ is a wrapper object intended to hold application-specific errors.
//!
//! The archetypal use-case is to allow applications that call library
//! runtimes which call application callbacks to allow the application
//! callbacks to return application-specific errors back to itself through the
//! runtime.
//!
//! In order to lessen the risk of wrapping an unintended type, the [`AppErr`]
//! constructor only take in types that implement [`apperr::Blessed`](Blessed)
//! (which is a subtrait of [`std::error::Error`]).
//!
//! # Alternatives
//! There are other ways to solve the same problem, but they are not always
//! feasible.
//! - Traits can use associated types to declare the application-specific error
//!   types.
//! - A generic parameter can be used to declare the application-specific error
//!   type.
//! - Global variables can be used to store error information.

use std::any::Any;

/// Marker trait used to bless a type so that it can be used as a
/// application-specific error.
pub trait Blessed: std::error::Error {}

/// An error type used to pass an application-specific error through a library
/// runtime.
///
/// Application callbacks can return this type for the `Err()` case in order
/// to allow application-defined errors to be passed back to the application
/// through a library runtime.
#[repr(transparent)]
#[derive(Debug)]
pub struct AppErr(Box<dyn Any + Send + 'static>);

impl AppErr {
  /// Create a new application callback error object that can be converted back
  /// into to its original type (as long as it is [`Any`] compatible).
  ///
  /// ```
  /// use std::fmt;
  /// use apperr::AppErr;
  /// use apperr::{AppErr, Blessed};
  ///
  /// #[derive(Debug)]
  /// enum MyErr {
  ///   Something(String)
  /// }
  /// impl fmt::Display for MyErr {
  ///   fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  ///     match self {
  ///       MyErr::Something(s) => {
  ///         write!(f, "Some error; {}", s)
  ///       }
  ///     }
  ///   }
  /// }
  /// impl std::error::Error for MyErr { }
  /// impl Blessed for MyErr { }
  ///
  /// let apperr = AppErr::new(MyErr::Something("hello".into()));
  /// ```
  pub fn new<E>(e: E) -> Self
  where
    E: Send + 'static
    E: Blessed + Send + 'static
  {
    Self(Box::new(e))
  }

  /// Inspect error type wrapped by the `AppErr`.
  ///
  /// ```
  /// use std::fmt;
  /// use apperr::AppErr;
  /// use apperr::{AppErr, Blessed};
  ///
  /// #[derive(Debug)]
  /// enum MyErr {
  ///   Something(String)
  /// }
  /// impl fmt::Display for MyErr {
  ///   fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  ///     match self {
  ///       MyErr::Something(s) => {
  ///         write!(f, "Some error; {}", s)
  ///       }
  ///     }
  ///   }
  /// }
  /// impl std::error::Error for MyErr { }
  /// impl Blessed for MyErr { }
  ///
  /// let apperr = AppErr::new(MyErr::Something("hello".into()));
  ///
  /// assert!(apperr.is::<MyErr>());
  /// assert_eq!(apperr.is::<String>(), false);
  /// ```
  pub fn is<T>(&self) -> bool
  where
    T: Any
  {
    self.0.is::<T>()
  }

  /// Attempt to unpack and cast the inner error type.
  ///
  /// If it can't be downcast to `E`, the `AppErr` will be returned back to the
  /// caller in the `Err()` case.
  ///
  /// ```
  /// use std::fmt;
  /// use apperr::AppErr;
  /// use apperr::{AppErr, Blessed};
  ///
  /// #[derive(Debug)]
  /// enum MyErr {
  ///   Something(String)
  /// }
  /// impl fmt::Display for MyErr {
  ///   fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  ///     match self {
  ///       MyErr::Something(s) => {
  ///         write!(f, "Some error; {}", s)
  ///       }
  ///     }
  ///   }
  /// }
  /// impl std::error::Error for MyErr { }
  /// impl Blessed for MyErr { }
  ///
  /// let apperr = AppErr::new(MyErr::Something("hello".into()));
  ///
  /// let Ok(e) = apperr.try_into_inner::<MyErr>() else {
  ///   panic!("Unexpectedly not MyErr");
  /// };
  /// ```
  pub fn try_into_inner<E: 'static>(self) -> Result<E, AppErr> {
    match self.0.downcast::<E>() {
      Ok(e) => Ok(*e),
      Err(e) => Err(AppErr(e))
    }
  }

  /// Unwrap application-specific error.
  ///
  /// ```
  /// use std::fmt;
  /// use apperr::AppErr;
  /// use apperr::{AppErr, Blessed};
  ///
  /// #[derive(Debug)]
  /// enum MyErr {
  ///   Something(String)
  /// }
  /// impl fmt::Display for MyErr {
  ///   fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  ///     match self {
  ///       MyErr::Something(s) => {
  ///         write!(f, "Some error; {}", s)
  ///       }
  ///     }
  ///   }
  /// }
  /// impl std::error::Error for MyErr { }
  /// impl Blessed for MyErr { }
  ///
  /// let apperr = AppErr::new(MyErr::Something("hello".into()));
  ///
  /// let MyErr::Something(e) = apperr.unwrap_inner::<MyErr>() else {
  ///   panic!("Unexpectedly not MyErr::Something");
  /// };
  /// assert_eq!(e, "hello");
  /// ```
︙

Changes to www/changelog.md. 

1
2
3
4
5
6



7





8
9
10


















11
12
13
14
15
16

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







+
+
+

+
+
+
+
+



+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+







# Change Log

## [Unreleased]

### Added

- Add a `Blessed` trait used to mark types as allowed to be wrapped by
  `AppErr`.

### Changed

- The `AppErr::new()` constructor's input now must implement
  `std::error::Error` and `apperr::Blessed` to lessen the risk that wrong type
  is passed by accident (avoid things like the `Result` being passed instead of
  the error type).

### Removed

---

## [0.2.0] - 2024-01-14

[Details](/vdiff?from=apperr-0.1.0&to=apperr-0.2.0)

### Added

- Add a `Blessed` trait used to mark types as allowed to be wrapped by
  `AppErr`.

### Changed

- The `AppErr::new()` constructor's input now must implement
  `std::error::Error` and `apperr::Blessed` to lessen the risk that wrong type
  is passed by accident (avoid things like the `Result` being passed instead of
  the error type).

---

## [0.1.0] - 2023-12-12

- Initial release.

Changes to www/index.md. 

1
2
3

4
5
6
7
8
9
10
11

1
2

3

4
5
6
7
8
9
10



-
+
-








# AppErr

A very thin `Any` wrapper which does nothing more than state its intended
A very thin `Any` wrapper which is meant to store an error.
use-case.


## Change log

The details of changes can always be found in the timeline, but for a
high-level view of changes between released versions there's a manually
maintained [Change Log](./changelog.md).
︙