Skip to main content

mariadb_cli/config/keys/
types.rs

1//! The shapes one published setting is described and read as.
2//!
3//! Nothing here knows which settings exist; it only states what a setting can
4//! accept, where its value comes from when nothing was stored, and what a value
5//! looks like once it passed.
6
7use crate::error::Result;
8use std::fmt;
9
10/// The set of values one key accepts.
11#[derive(Debug, Clone, Copy, PartialEq, Eq)]
12pub enum Domain {
13    /// A truth value.
14    Boolean,
15    /// A whole number above zero.
16    PositiveInteger,
17    /// A whole number from zero upwards.
18    NonNegativeInteger,
19    /// A whole number inside a closed range, both ends accepted.
20    ///
21    /// Separate from [`Self::PositiveInteger`] because a ceiling that only the
22    /// work knows about is a ceiling the caller is refused by at a distance.
23    /// `conn.default_port` was stored as any positive number and read back as a
24    /// port, so `99999` was accepted where it was written and refused where it
25    /// was used — and then refused every unrelated command as well, since every
26    /// destination reads that key. An order has to be answered where it is
27    /// given.
28    IntegerInRange(u64, u64),
29    /// One of a closed list of words.
30    Enumeration(&'static [&'static str]),
31    /// Free text that may not be empty.
32    Text,
33}
34
35impl Domain {
36    /// The accepted values, in prose short enough for a hint.
37    #[must_use]
38    pub fn described(self) -> String {
39        match self {
40            Self::Boolean => "one of: true, false".to_owned(),
41            Self::PositiveInteger => "a whole number above zero".to_owned(),
42            Self::NonNegativeInteger => "a whole number from zero upwards".to_owned(),
43            Self::IntegerInRange(low, high) => format!("a whole number from {low} to {high}"),
44            Self::Enumeration(values) => format!("one of: {}", values.join(", ")),
45            Self::Text => "text that is not empty".to_owned(),
46        }
47    }
48
49    /// The stable identifier of this domain.
50    ///
51    /// A catalogue words the domain from this, so the reader of a refusal is
52    /// told what is accepted in their own language rather than in the one the
53    /// registry happens to be written in.
54    #[must_use]
55    pub const fn token(self) -> &'static str {
56        match self {
57            Self::Boolean => "boolean",
58            Self::PositiveInteger => "positive-integer",
59            Self::NonNegativeInteger => "non-negative-integer",
60            Self::IntegerInRange(..) => "integer-in-range",
61            Self::Enumeration(_) => "enumeration",
62            Self::Text => "text",
63        }
64    }
65
66    /// The accepted words, when the domain is a closed list of them.
67    #[must_use]
68    pub fn accepted(self) -> String {
69        match self {
70            Self::Enumeration(values) => values.join(", "),
71            Self::Boolean => "true, false".to_owned(),
72            // Written with a hyphen rather than with a word, because this text
73            // is carried into a sentence the catalogue writes in the reader's
74            // own language. A connective in English here would arrive inside a
75            // Portuguese phrase, which is the shape of leak this project spent
76            // a whole pass removing.
77            Self::IntegerInRange(low, high) => format!("{low}-{high}"),
78            _ => String::new(),
79        }
80    }
81}
82
83/// Where a key's value comes from when nothing was stored.
84#[derive(Debug, Clone, Copy, PartialEq, Eq)]
85pub enum Fallback {
86    /// A value built into this build.
87    Builtin(&'static str),
88    /// The server decides, so this build carries no value.
89    Server,
90    /// The host decides, so this build carries no value.
91    Host,
92    /// There is no default at all.
93    Absent,
94}
95
96/// One published setting.
97#[derive(Debug, Clone, Copy)]
98pub struct KeySpec {
99    /// The exact name a caller writes.
100    pub name: &'static str,
101    /// The values this key accepts.
102    pub domain: Domain,
103    /// What applies when nothing was stored.
104    pub fallback: Fallback,
105    /// One line saying what the key governs.
106    pub about: &'static str,
107}
108
109impl KeySpec {
110    /// The built-in value, when this build carries one.
111    ///
112    /// # Errors
113    ///
114    /// Returns a configuration failure when the built-in value does not pass
115    /// its own domain, which is a defect in this table rather than caller input.
116    pub fn default_value(&self) -> Result<Option<Value>> {
117        match self.fallback {
118            Fallback::Builtin(raw) => super::validate(self.name, raw).map(Some),
119            Fallback::Server | Fallback::Host | Fallback::Absent => Ok(None),
120        }
121    }
122}
123
124/// A value that passed its domain.
125#[derive(Debug, Clone, PartialEq, Eq)]
126pub enum Value {
127    /// A truth value.
128    Boolean(bool),
129    /// A whole number.
130    Integer(u64),
131    /// One word of a closed list.
132    Enumeration(&'static str),
133    /// Free text.
134    Text(String),
135}
136
137impl fmt::Display for Value {
138    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
139        match self {
140            Self::Boolean(value) => write!(f, "{value}"),
141            Self::Integer(value) => write!(f, "{value}"),
142            Self::Enumeration(value) => write!(f, "{value}"),
143            Self::Text(value) => write!(f, "{value}"),
144        }
145    }
146}
147
148impl From<&Value> for serde_json::Value {
149    fn from(value: &Value) -> Self {
150        match value {
151            Value::Boolean(inner) => Self::Bool(*inner),
152            Value::Integer(inner) => Self::from(*inner),
153            Value::Enumeration(inner) => Self::from(*inner),
154            Value::Text(inner) => Self::from(inner.clone()),
155        }
156    }
157}