tier 0.1.17

Rust configuration library for layered TOML, env, and CLI settings
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
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

use crate::{ConfigError, Layer};

use super::PatchLayerBuilder;

/// Sparse patch field wrapper used by typed override structs.
///
/// `Patch<T>` makes intent explicit:
///
/// - `Patch::Unset` means "do not touch this field"
/// - `Patch::Set(value)` means "override this field with `value`"
///
/// For optional config fields, use `Patch<Option<T>>` when the patch needs to
/// distinguish "unset" from "set this field to null".
///
/// # Examples
///
/// ```
/// use tier::Patch;
///
/// let port = Patch::set(8080);
/// assert!(port.is_set());
///
/// let untouched: Patch<u16> = Patch::Unset;
/// assert_eq!(untouched.into_option(), None);
/// ```
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub enum Patch<T> {
    /// Do not override this field.
    #[default]
    Unset,
    /// Override this field with the contained value.
    Set(T),
}

impl<T> Patch<T> {
    /// Creates a patch that overrides a field with `value`.
    #[must_use]
    pub fn set(value: T) -> Self {
        Self::Set(value)
    }

    /// Returns the contained value by reference when the patch is set.
    #[must_use]
    pub fn as_ref(&self) -> Option<&T> {
        match self {
            Self::Unset => None,
            Self::Set(value) => Some(value),
        }
    }

    /// Returns `true` when this patch carries an override value.
    #[must_use]
    pub fn is_set(&self) -> bool {
        matches!(self, Self::Set(_))
    }

    /// Consumes the patch and returns the override value, when present.
    #[must_use]
    pub fn into_option(self) -> Option<T> {
        match self {
            Self::Unset => None,
            Self::Set(value) => Some(value),
        }
    }
}

impl<T> From<T> for Patch<T> {
    fn from(value: T) -> Self {
        Self::Set(value)
    }
}

/// Trait implemented by typed sparse override structures.
///
/// The easiest way to implement this trait is `#[derive(TierPatch)]` with the
/// `derive` feature enabled. A `TierPatch` value can then be turned into a
/// [`Layer`] or applied directly to a [`crate::ConfigLoader`].
///
/// Fields are sparse by default:
///
/// - `Option<T>` fields only write when they are `Some(...)`
/// - nested patch structs can be connected with `#[tier(nested)]`
/// - CLI-only fields can be ignored with `#[tier(skip)]`
/// - enums can be used for subcommand-like patch models
/// - use [`Patch<Option<T>>`] when the patch must distinguish "unset" from
///   "explicitly clear this optional config field"
///
/// # Examples
///
/// ```no_run
/// # #[cfg(feature = "derive")] {
/// # fn main() -> Result<(), tier::ConfigError> {
/// use serde::{Deserialize, Serialize};
/// use tier::{Layer, Patch, TierPatch};
///
/// #[derive(Debug, Clone, Serialize, Deserialize)]
/// struct ServerConfig {
///     port: u16,
///     tls: TlsConfig,
/// }
///
/// #[derive(Debug, Clone, Serialize, Deserialize)]
/// struct TlsConfig {
///     cert: Option<String>,
/// }
///
/// #[derive(Debug, TierPatch, Default)]
/// struct ServerPatch {
///     port: Option<u16>,
///     #[tier(path_expr = tier::path!(ServerConfig.tls.cert))]
///     cert_path: Patch<Option<String>>,
/// }
///
/// let patch = ServerPatch {
///     port: Some(8443),
///     cert_path: Patch::set(None),
/// };
///
/// let _layer = Layer::from_patch("typed-cli", &patch)?;
/// # Ok(())
/// # }
/// # }
/// ```
pub trait TierPatch {
    /// Writes sparse overrides into the provided layer builder.
    fn write_layer(&self, builder: &mut PatchLayerBuilder, prefix: &str)
    -> Result<(), ConfigError>;

    /// Converts the patch into a custom configuration layer.
    ///
    /// This is useful when the patch is built separately from the loader and
    /// should be applied with [`crate::ConfigLoader::layer`].
    fn to_layer(&self, name: impl Into<String>) -> Result<Layer, ConfigError>
    where
        Self: Sized,
    {
        Layer::from_patch(name, self)
    }
}