ephemeris_documents/

format.rs

//! The output format of a structured document, its capabilities and its
//! dispatch to a backend.

use std::fmt;

use facet::Facet;

use crate::annotation::Annotated;
use crate::backend::Backend;
use crate::columns::Columns;
use crate::error::{ColumnsError, DocumentError, Feature, ValueError};
use crate::json::{Dialect, Json};
use crate::ownership::{ManagedPath, Ownership};
use crate::source::Source;
use crate::toml::Toml;
use crate::yaml::{LiteralBlock, Yaml};

/// Output syntax for a structured document.
#[derive(Debug, Clone, Copy, Facet, PartialEq, Eq)]
#[facet(tag = "type", deny_unknown_fields)]
#[repr(u8)]
pub enum Format {
    /// JSON.
    #[facet(rename = "json")]
    Json,
    /// JSON5, with unquoted keys, comments, and literal strings.
    #[facet(rename = "json5")]
    Json5,
    /// TOML.
    #[facet(rename = "toml")]
    Toml {
        /// Column limit for rendering a table as an inline table.
        inline_width: InlineWidth,
    },
    /// YAML.
    #[facet(rename = "yaml")]
    Yaml,
}

/// An operation that runs against the backend of a format.
trait Run {
    type Output;

    fn run(self, backend: &impl Backend) -> Self::Output;
}

struct Reconcile<'a> {
    desired: &'a Annotated,
    source: &'a Source<'a>,
    ownership: &'a Ownership,
}

impl Run for Reconcile<'_> {
    type Output = Result<Vec<u8>, DocumentError>;

    fn run(self, backend: &impl Backend) -> Self::Output {
        backend.reconcile(self.desired, self.source, self.ownership)
    }
}

struct ReadString<'a> {
    source: &'a str,
    path: &'a [String],
}

impl Run for ReadString<'_> {
    type Output = Result<Option<String>, DocumentError>;

    fn run(self, backend: &impl Backend) -> Self::Output {
        backend.read_string(self.source, self.path)
    }
}

impl Format {
    /// The format of a file with this extension, without the dot. TOML needs
    /// the inline width the caller wants.
    #[must_use]
    pub fn from_extension(extension: &str, inline_width: InlineWidth) -> Option<Self> {
        match extension {
            "toml" => Some(Self::Toml { inline_width }),
            "yaml" | "yml" => Some(Self::Yaml),
            "json" => Some(Self::Json),
            "json5" => Some(Self::Json5),
            _ => None,
        }
    }

    fn run<R: Run>(self, operation: R) -> R::Output {
        match self {
            Self::Toml { inline_width } => operation.run(&Toml::new(inline_width)),
            Self::Yaml => operation.run(&Yaml),
            Self::Json => operation.run(&Json::new(Dialect::Json)),
            Self::Json5 => operation.run(&Json::new(Dialect::Json5)),
        }
    }

    /// Reconcile a desired value against the current source.
    ///
    /// # Errors
    /// Returns an error for malformed source, values the format cannot
    /// represent, or an incompatible merge.
    pub(crate) fn reconcile(
        self,
        desired: &Annotated,
        source: &Source<'_>,
        ownership: &Ownership,
    ) -> Result<Vec<u8>, DocumentError> {
        self.run(Reconcile {
            desired,
            source,
            ownership,
        })
    }

    /// The string at `path` in `source`. A key that is absent on the way
    /// gives `None`.
    ///
    /// # Errors
    /// Returns an error for malformed source, and
    /// [`ValueError::NotString`] when the value at `path` is not a string.
    /// YAML returns the text of any scalar, including numbers and booleans.
    pub fn read_string(
        self,
        source: &str,
        path: &ManagedPath,
    ) -> Result<Option<String>, DocumentError> {
        self.run(ReadString {
            source,
            path: path.segments(),
        })
    }

    /// Whether the format can express `feature` at all.
    ///
    /// A literal string can still fail when the format cannot reproduce its
    /// text.
    pub(crate) const fn supports(self, feature: Feature) -> bool {
        match feature {
            Feature::Null | Feature::LargeInteger => {
                !matches!(self, Self::Toml { inline_width: _ })
            }
            Feature::InlineComment => matches!(self, Self::Json5 | Self::Yaml),
            Feature::DottedTable => matches!(self, Self::Toml { inline_width: _ }),
            Feature::Comment | Feature::LiteralString => !matches!(self, Self::Json),
        }
    }

    /// Whether the format can write `text` as a literal string.
    pub(crate) fn reproduces_literal(self, text: &str) -> bool {
        match self {
            Self::Yaml => LiteralBlock::new(text).is_representable(),
            Self::Json | Self::Json5 | Self::Toml { inline_width: _ } => true,
        }
    }

    /// The error for a `feature` this format cannot express.
    pub(crate) const fn reject(self, feature: Feature) -> ValueError {
        ValueError::Unsupported {
            format: self,
            feature,
        }
    }

    /// Check that the format supports `feature`.
    ///
    /// # Errors
    /// Returns [`ValueError::Unsupported`] when it does not.
    pub(crate) const fn require(self, feature: Feature) -> Result<(), ValueError> {
        if self.supports(feature) {
            Ok(())
        } else {
            Err(self.reject(feature))
        }
    }
}

impl fmt::Display for Format {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(match self {
            Self::Json => "JSON",
            Self::Json5 => "JSON5",
            Self::Toml { inline_width: _ } => "TOML",
            Self::Yaml => "YAML",
        })
    }
}

/// Widest `key = { ... }` line, in columns, that stays an inline table.
/// Wider tables are promoted to `[table]` sections.
#[derive(Debug, Clone, Copy, Facet, PartialEq, Eq)]
#[facet(proxy = usize)]
pub struct InlineWidth(#[facet(opaque)] Columns);

impl InlineWidth {
    /// An inline width of `columns`, or `None` for zero.
    #[must_use]
    pub const fn new(columns: usize) -> Option<Self> {
        match Columns::new(columns) {
            Some(columns) => Some(Self(columns)),
            None => None,
        }
    }

    /// The column count.
    #[must_use]
    pub const fn get(self) -> usize {
        self.0.get()
    }
}

impl TryFrom<usize> for InlineWidth {
    type Error = ColumnsError;

    fn try_from(columns: usize) -> Result<Self, Self::Error> {
        Columns::try_from(columns).map(Self)
    }
}

impl From<&InlineWidth> for usize {
    fn from(width: &InlineWidth) -> Self {
        width.get()
    }
}

#[cfg(test)]
mod tests;