mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! The shapes one published setting is described and read as.
//!
//! Nothing here knows which settings exist; it only states what a setting can
//! accept, where its value comes from when nothing was stored, and what a value
//! looks like once it passed.

use crate::error::Result;
use std::fmt;

/// The set of values one key accepts.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Domain {
    /// A truth value.
    Boolean,
    /// A whole number above zero.
    PositiveInteger,
    /// A whole number from zero upwards.
    NonNegativeInteger,
    /// A whole number inside a closed range, both ends accepted.
    ///
    /// Separate from [`Self::PositiveInteger`] because a ceiling that only the
    /// work knows about is a ceiling the caller is refused by at a distance.
    /// `conn.default_port` was stored as any positive number and read back as a
    /// port, so `99999` was accepted where it was written and refused where it
    /// was used — and then refused every unrelated command as well, since every
    /// destination reads that key. An order has to be answered where it is
    /// given.
    IntegerInRange(u64, u64),
    /// One of a closed list of words.
    Enumeration(&'static [&'static str]),
    /// Free text that may not be empty.
    Text,
}

impl Domain {
    /// The accepted values, in prose short enough for a hint.
    #[must_use]
    pub fn described(self) -> String {
        match self {
            Self::Boolean => "one of: true, false".to_owned(),
            Self::PositiveInteger => "a whole number above zero".to_owned(),
            Self::NonNegativeInteger => "a whole number from zero upwards".to_owned(),
            Self::IntegerInRange(low, high) => format!("a whole number from {low} to {high}"),
            Self::Enumeration(values) => format!("one of: {}", values.join(", ")),
            Self::Text => "text that is not empty".to_owned(),
        }
    }

    /// The stable identifier of this domain.
    ///
    /// A catalogue words the domain from this, so the reader of a refusal is
    /// told what is accepted in their own language rather than in the one the
    /// registry happens to be written in.
    #[must_use]
    pub const fn token(self) -> &'static str {
        match self {
            Self::Boolean => "boolean",
            Self::PositiveInteger => "positive-integer",
            Self::NonNegativeInteger => "non-negative-integer",
            Self::IntegerInRange(..) => "integer-in-range",
            Self::Enumeration(_) => "enumeration",
            Self::Text => "text",
        }
    }

    /// The accepted words, when the domain is a closed list of them.
    #[must_use]
    pub fn accepted(self) -> String {
        match self {
            Self::Enumeration(values) => values.join(", "),
            Self::Boolean => "true, false".to_owned(),
            // Written with a hyphen rather than with a word, because this text
            // is carried into a sentence the catalogue writes in the reader's
            // own language. A connective in English here would arrive inside a
            // Portuguese phrase, which is the shape of leak this project spent
            // a whole pass removing.
            Self::IntegerInRange(low, high) => format!("{low}-{high}"),
            _ => String::new(),
        }
    }
}

/// Where a key's value comes from when nothing was stored.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Fallback {
    /// A value built into this build.
    Builtin(&'static str),
    /// The server decides, so this build carries no value.
    Server,
    /// The host decides, so this build carries no value.
    Host,
    /// There is no default at all.
    Absent,
}

/// One published setting.
#[derive(Debug, Clone, Copy)]
pub struct KeySpec {
    /// The exact name a caller writes.
    pub name: &'static str,
    /// The values this key accepts.
    pub domain: Domain,
    /// What applies when nothing was stored.
    pub fallback: Fallback,
    /// One line saying what the key governs.
    pub about: &'static str,
}

impl KeySpec {
    /// The built-in value, when this build carries one.
    ///
    /// # Errors
    ///
    /// Returns a configuration failure when the built-in value does not pass
    /// its own domain, which is a defect in this table rather than caller input.
    pub fn default_value(&self) -> Result<Option<Value>> {
        match self.fallback {
            Fallback::Builtin(raw) => super::validate(self.name, raw).map(Some),
            Fallback::Server | Fallback::Host | Fallback::Absent => Ok(None),
        }
    }
}

/// A value that passed its domain.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Value {
    /// A truth value.
    Boolean(bool),
    /// A whole number.
    Integer(u64),
    /// One word of a closed list.
    Enumeration(&'static str),
    /// Free text.
    Text(String),
}

impl fmt::Display for Value {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Boolean(value) => write!(f, "{value}"),
            Self::Integer(value) => write!(f, "{value}"),
            Self::Enumeration(value) => write!(f, "{value}"),
            Self::Text(value) => write!(f, "{value}"),
        }
    }
}

impl From<&Value> for serde_json::Value {
    fn from(value: &Value) -> Self {
        match value {
            Value::Boolean(inner) => Self::Bool(*inner),
            Value::Integer(inner) => Self::from(*inner),
            Value::Enumeration(inner) => Self::from(*inner),
            Value::Text(inner) => Self::from(inner.clone()),
        }
    }
}