uv_options_metadata/

lib.rs

//! Taken directly from Ruff.
//!
//! See: <https://github.com/astral-sh/ruff/blob/dc8db1afb08704ad6a788c497068b01edf8b460d/crates/ruff_workspace/sr.rs>

use serde::{Serialize, Serializer};
use std::collections::BTreeMap;

use std::fmt::{Debug, Display, Formatter};

/// Visits [`OptionsMetadata`].
///
/// An instance of [`Visit`] represents the logic for inspecting an object's options metadata.
pub trait Visit {
    /// Visits an [`OptionField`] value named `name`.
    fn record_field(&mut self, name: &str, field: OptionField);

    /// Visits an [`OptionSet`] value named `name`.
    fn record_set(&mut self, name: &str, group: OptionSet);
}

/// Returns metadata for its options.
pub trait OptionsMetadata {
    /// Visits the options metadata of this object by calling `visit` for each option.
    fn record(visit: &mut dyn Visit);

    fn documentation() -> Option<&'static str> {
        None
    }

    /// Returns the extracted metadata.
    fn metadata() -> OptionSet
    where
        Self: Sized + 'static,
    {
        OptionSet::of::<Self>()
    }
}

impl<T> OptionsMetadata for Option<T>
where
    T: OptionsMetadata,
{
    fn record(visit: &mut dyn Visit) {
        T::record(visit);
    }
}

/// A set of options.
///
/// It extracts the options by calling the [`OptionsMetadata::record`] of a type implementing
/// [`OptionsMetadata`].
#[derive(Copy, Clone)]
pub struct OptionSet {
    record: fn(&mut dyn Visit),
    doc: fn() -> Option<&'static str>,
}

impl PartialEq for OptionSet {
    fn eq(&self, other: &Self) -> bool {
        std::ptr::fn_addr_eq(self.record, other.record) && std::ptr::fn_addr_eq(self.doc, other.doc)
    }
}

impl Eq for OptionSet {}

impl OptionSet {
    pub fn of<T>() -> Self
    where
        T: OptionsMetadata + 'static,
    {
        Self {
            record: T::record,
            doc: T::documentation,
        }
    }

    /// Visits the options in this set by calling `visit` for each option.
    pub fn record(&self, visit: &mut dyn Visit) {
        let record = self.record;
        record(visit);
    }

    pub fn documentation(&self) -> Option<&'static str> {
        let documentation = self.doc;
        documentation()
    }
}

/// Visitor that writes out the names of all fields and sets.
struct DisplayVisitor<'fmt, 'buf> {
    f: &'fmt mut Formatter<'buf>,
    result: std::fmt::Result,
}

impl<'fmt, 'buf> DisplayVisitor<'fmt, 'buf> {
    fn new(f: &'fmt mut Formatter<'buf>) -> Self {
        Self { f, result: Ok(()) }
    }

    fn finish(self) -> std::fmt::Result {
        self.result
    }
}

impl Visit for DisplayVisitor<'_, '_> {
    fn record_set(&mut self, name: &str, _: OptionSet) {
        self.result = self.result.and_then(|()| writeln!(self.f, "{name}"));
    }

    fn record_field(&mut self, name: &str, field: OptionField) {
        self.result = self.result.and_then(|()| {
            write!(self.f, "{name}")?;

            if field.deprecated.is_some() {
                write!(self.f, " (deprecated)")?;
            }

            writeln!(self.f)
        });
    }
}

impl Display for OptionSet {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        let mut visitor = DisplayVisitor::new(f);
        self.record(&mut visitor);
        visitor.finish()
    }
}

struct SerializeVisitor<'a> {
    entries: &'a mut BTreeMap<String, OptionField>,
}

impl Visit for SerializeVisitor<'_> {
    fn record_set(&mut self, name: &str, set: OptionSet) {
        // Collect the entries of the set.
        let mut entries = BTreeMap::new();
        let mut visitor = SerializeVisitor {
            entries: &mut entries,
        };
        set.record(&mut visitor);

        // Insert the set into the entries.
        for (key, value) in entries {
            self.entries.insert(format!("{name}.{key}"), value);
        }
    }

    fn record_field(&mut self, name: &str, field: OptionField) {
        self.entries.insert(name.to_string(), field);
    }
}

impl Serialize for OptionSet {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        let mut entries = BTreeMap::new();
        let mut visitor = SerializeVisitor {
            entries: &mut entries,
        };
        self.record(&mut visitor);
        entries.serialize(serializer)
    }
}

impl Debug for OptionSet {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        Display::fmt(self, f)
    }
}

#[derive(Debug, Eq, PartialEq, Clone, Serialize)]
pub struct OptionField {
    pub doc: &'static str,
    /// Ex) `"false"`
    pub default: &'static str,
    /// Ex) `"bool"`
    pub value_type: &'static str,
    /// Ex) `"per-file-ignores"`
    pub scope: Option<&'static str>,
    pub example: &'static str,
    pub deprecated: Option<Deprecated>,
    pub possible_values: Option<Vec<PossibleValue>>,
    /// If true, this option is only available in `uv.toml`, not `pyproject.toml`.
    pub uv_toml_only: bool,
}

#[derive(Debug, Clone, Eq, PartialEq, Serialize)]
pub struct Deprecated {
    pub since: Option<&'static str>,
    pub message: Option<&'static str>,
}

impl Display for OptionField {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        writeln!(f, "{}", self.doc)?;
        writeln!(f)?;

        writeln!(f, "Default value: {}", self.default)?;

        if let Some(possible_values) = self
            .possible_values
            .as_ref()
            .filter(|values| !values.is_empty())
        {
            writeln!(f, "Possible values:")?;
            writeln!(f)?;
            for value in possible_values {
                writeln!(f, "- {value}")?;
            }
        } else {
            writeln!(f, "Type: {}", self.value_type)?;
        }

        if let Some(deprecated) = &self.deprecated {
            write!(f, "Deprecated")?;

            if let Some(since) = deprecated.since {
                write!(f, " (since {since})")?;
            }

            if let Some(message) = deprecated.message {
                write!(f, ": {message}")?;
            }

            writeln!(f)?;
        }

        writeln!(f, "Example usage:\n```toml\n{}\n```", self.example)
    }
}

/// A possible value for an enum, similar to Clap's `PossibleValue` type (but without a dependency
/// on Clap).
#[derive(Debug, Eq, PartialEq, Clone, Serialize)]
pub struct PossibleValue {
    pub name: String,
    pub help: Option<String>,
}

impl Display for PossibleValue {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        write!(f, "`\"{}\"`", self.name)?;
        if let Some(help) = &self.help {
            write!(f, ": {help}")?;
        }
        Ok(())
    }
}