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}