module 0.3.1

Modular NixOS-style configuration crate.
Documentation 
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

use core::fmt::Display;

use super::Error;
use super::error::Trace;

mod private {
    pub trait Sealed {}
}
use self::private::Sealed;

/// Extension trait for [`Result`].
///
/// Adds methods for adding context to an [`Error`].
///
/// This trait is **sealed** and cannot be implemented for any other types.
///
/// [`Error`]: super::Error
pub trait Context: Sealed {
    /// Add the name of this module to the context of the error.
    ///
    /// This method adds context to the [`Error`] so that it knows in which
    /// module the error occurred. It is perfectly fine to never use it, as long
    /// as you don't mind cryptic errors.
    ///
    /// Modules should be added in the following order, from the module where
    /// the error occured and then its parent module up until the root module.
    fn module<D>(self, name: D) -> Self
    where
        D: Display,
        Self: Sized;

    /// The same as [`Context::module`] but lazily-evaluated.
    fn with_module<D>(self, f: impl FnOnce() -> D) -> Self
    where
        D: Display;

    /// Set the trace of the error.
    ///
    /// This method overwrites the module trace completely with `trace`.
    fn trace(self, trace: Trace) -> Self;

    /// Set the trace of the error.
    ///
    /// The same as [`Context::trace`] but lazily-evaluated.
    fn with_trace(self, f: impl FnOnce() -> Trace) -> Self;

    /// Add the name of the value to the context of the error.
    ///
    /// This method adds context to the [`Error`] so that it knows in which
    /// value the error occurred. It is perfectly fine to never use it, as long
    /// as you don't mind cryptic errors.
    fn value<D>(self, name: D) -> Self
    where
        D: Display,
        Self: Sized;

    /// The same as [`Context::value`] but lazily-evaluated.
    fn with_value<D>(self, f: impl FnOnce() -> D) -> Self
    where
        D: Display,
        Self: Sized;
}

impl<T> Sealed for core::result::Result<T, Error> {}

impl<T> Context for core::result::Result<T, Error> {
    fn module<D>(self, name: D) -> Self
    where
        D: Display,
        Self: Sized,
    {
        self.with_module(|| name)
    }

    fn with_module<D>(self, f: impl FnOnce() -> D) -> Self
    where
        D: Display,
    {
        self.map_err(|mut e| {
            e.trace.push_front(f());
            e
        })
    }

    fn trace(self, trace: Trace) -> Self {
        self.with_trace(|| trace)
    }

    fn with_trace(self, f: impl FnOnce() -> Trace) -> Self {
        self.map_err(|mut e| {
            e.trace = f();
            e
        })
    }

    fn value<D>(self, name: D) -> Self
    where
        D: Display,
        Self: Sized,
    {
        self.with_value(|| name)
    }

    fn with_value<D>(self, f: impl FnOnce() -> D) -> Self
    where
        D: Display,
        Self: Sized,
    {
        self.map_err(|mut e| {
            e.value.push_front(f());
            e
        })
    }
}