ephemeris_documents/

yaml.rs

//! YAML support: canonical rendering of a whole tree, the source tree that
//! edits existing YAML, and the backend.

mod backend;
mod literal;
mod node;
mod scalar_text;
mod source;
mod string;

use std::fmt::{self, Write as _};

pub(crate) use self::backend::Yaml;
pub(crate) use self::literal::LiteralBlock;
use self::scalar_text::ScalarText;
use self::string::YamlString;
use crate::annotation::{Annotated, AnnotatedValue};
use crate::entries::Entries;
use crate::scalar::Scalar;
use crate::text::CommentSyntax;

/// Columns per nesting level in canonical output, and the step assumed for
/// source with nothing to measure.
const CANONICAL_STEP: usize = 2;

/// A validated tree the canonical renderer writes.
pub(crate) struct YamlDocument<'a>(&'a Annotated);

impl<'a> YamlDocument<'a> {
    pub(crate) const fn new(root: &'a Annotated) -> Self {
        Self(root)
    }
}

impl fmt::Display for YamlDocument<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut writer = Writer { out: f, indent: 0 };
        if self.0.comment.is_some() {
            writer.comment(self.0)?;
            writer.line("")?;
        }
        match &self.0.value {
            AnnotatedValue::Scalar(scalar) => writer.scalar(scalar),
            AnnotatedValue::Array(items) if items.is_empty() => writer.line("[]"),
            AnnotatedValue::Object(entries) if entries.is_empty() => writer.line("{}"),
            AnnotatedValue::Array(items) => writer.sequence(items, Lead::Pending),
            AnnotatedValue::Object(entries) => writer.mapping(entries, Lead::Pending),
        }
    }
}

/// Whether the indent of the first entry or item is already written.
#[derive(Clone, Copy)]
enum Lead {
    Written,
    Pending,
}

impl Lead {
    /// Whether the entry at `index` needs its own indent.
    const fn pads(self, index: usize) -> bool {
        matches!(self, Self::Pending) || index > 0
    }
}

/// The marker a child follows.
#[derive(Clone, Copy)]
enum Marker {
    Key,
    Dash,
}

struct Writer<'a, 'f> {
    out: &'a mut fmt::Formatter<'f>,
    indent: usize,
}

impl Writer<'_, '_> {
    fn line(&mut self, text: &str) -> fmt::Result {
        writeln!(self.out, "{text}")
    }

    fn pad(&mut self) -> fmt::Result {
        write!(self.out, "{:1$}", "", self.indent)
    }

    fn nested(&mut self, write: impl FnOnce(&mut Self) -> fmt::Result) -> fmt::Result {
        let outer = self.indent;
        self.indent = outer.saturating_add(CANONICAL_STEP);
        let result = write(self);
        self.indent = outer;
        result
    }

    fn comment(&mut self, node: &Annotated) -> fmt::Result {
        let Some(comment) = &node.comment else {
            return Ok(());
        };
        let pad = format_args!("{:1$}", "", self.indent);
        CommentSyntax::Hash.write_lines(self.out, comment, pad)
    }

    /// Write the entries at the current indent. The `lead` tells whether the
    /// caller has already written the indent of the first entry.
    fn mapping(&mut self, entries: &Entries, lead: Lead) -> fmt::Result {
        for (index, (key, value)) in entries.into_iter().enumerate() {
            if lead.pads(index) {
                self.comment(value)?;
                self.pad()?;
            }
            write!(self.out, "{}:", ScalarText::key(key))?;
            self.after_marker(value, Marker::Key)?;
        }
        Ok(())
    }

    /// Write the items at the current indent. The `lead` tells whether the
    /// caller has already written the indent of the first item.
    fn sequence(&mut self, items: &[Annotated], lead: Lead) -> fmt::Result {
        for (index, item) in items.iter().enumerate() {
            if lead.pads(index) {
                self.comment(item)?;
                self.pad()?;
            }
            self.out.write_str("-")?;
            self.after_marker(item, Marker::Dash)?;
        }
        Ok(())
    }

    /// Write what follows a `key:` or `-` marker and end the line.
    ///
    /// A container under a dash starts on the dash line unless its first
    /// child has a comment. Under a key it starts on the next line.
    fn after_marker(&mut self, node: &Annotated, marker: Marker) -> fmt::Result {
        match &node.value {
            AnnotatedValue::Scalar(scalar) => {
                self.out.write_str(" ")?;
                self.scalar(scalar)
            }
            AnnotatedValue::Array(items) if items.is_empty() => self.line(" []"),
            AnnotatedValue::Object(entries) if entries.is_empty() => self.line(" {}"),
            AnnotatedValue::Array(items) => {
                let lead = Self::lead(marker, items.first());
                self.block(lead, |writer, lead| writer.sequence(items, lead))
            }
            AnnotatedValue::Object(entries) => {
                let first = entries.into_iter().next().map(|(_, value)| value);
                let lead = Self::lead(marker, first);
                self.block(lead, |writer, lead| writer.mapping(entries, lead))
            }
        }
    }

    /// Whether a container starts on the line of its marker.
    fn lead(marker: Marker, first: Option<&Annotated>) -> Lead {
        match marker {
            Marker::Dash if first.is_some_and(|node| node.comment.is_none()) => Lead::Written,
            Marker::Dash | Marker::Key => Lead::Pending,
        }
    }

    fn block(
        &mut self,
        lead: Lead,
        write: impl FnOnce(&mut Self, Lead) -> fmt::Result,
    ) -> fmt::Result {
        self.nested(|writer| {
            writer.out.write_str(match lead {
                Lead::Written => " ",
                Lead::Pending => "\n",
            })?;
            write(writer, lead)
        })
    }

    /// Write a scalar and end the line.
    fn scalar(&mut self, scalar: &Scalar) -> fmt::Result {
        match scalar {
            Scalar::Null => self.line("null"),
            Scalar::Bool(value) => writeln!(self.out, "{value}"),
            Scalar::Integer(value) => writeln!(self.out, "{value}"),
            Scalar::Unsigned(value) => writeln!(self.out, "{value}"),
            Scalar::Float(value) => writeln!(self.out, "{value}"),
            Scalar::String { text, style } => match YamlString::select(text, *style) {
                YamlString::Block(block) => self.literal(&block),
                YamlString::Text(plain) => writeln!(self.out, "{plain}"),
            },
        }
    }

    fn literal(&mut self, block: &LiteralBlock<'_>) -> fmt::Result {
        self.line(&block.header())?;
        self.nested(|writer| {
            for line in block.lines() {
                if !line.is_empty() {
                    writer.pad()?;
                    writer.out.write_str(line)?;
                }
                writer.out.write_char('\n')?;
            }
            Ok(())
        })
    }
}

#[cfg(test)]
mod tests;