termosaic 0.2.2

Semantic, structured output for human, machine-text, and opaque-byte destinations
Documentation
use std::borrow::Cow;
use std::fmt;
use std::num::{NonZeroU8, NonZeroU32};

use unicode_width::{UnicodeWidthChar, UnicodeWidthStr};

use crate::{HumanText, TokenId, tokens};

/// A semantic human-output document.
#[derive(Clone, Eq, PartialEq)]
pub struct Doc(laidout::Doc<TokenId>);

impl fmt::Debug for Doc {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.debug_tuple("Doc").field(&self.0).finish()
    }
}

/// A reusable dense document prepared for either layout strategy.
#[derive(Clone)]
pub struct PreparedDoc(laidout::PreparedDoc<TokenId>);

impl Doc {
    pub fn empty() -> Self {
        Self(laidout::Doc::empty())
    }

    pub fn text(value: impl AsRef<str>) -> Self {
        Self::from_human_text(HumanText::sanitize(value))
    }

    pub fn from_text(value: impl AsRef<str>, layout: TextLayout) -> Self {
        let normalized = normalize_line_endings(value.as_ref());
        match layout {
            TextLayout::Prose => prose_doc(&normalized),
            TextLayout::Preformatted { tab_width } => preformatted_doc(&normalized, tab_width),
        }
    }

    pub fn line() -> Self {
        Self(laidout::Doc::line())
    }

    pub fn soft_line() -> Self {
        Self(laidout::Doc::soft_line())
    }

    pub fn hard_line() -> Self {
        Self(laidout::Doc::hard_line())
    }

    pub fn token(token: TokenId, doc: Self) -> Self {
        Self(laidout::Doc::annotate(token, doc.0))
    }

    /// Attach a semantic token stack, with the first token outermost.
    pub fn tokens(tokens: impl IntoIterator<Item = TokenId>, mut doc: Self) -> Self {
        let tokens = tokens.into_iter().collect::<Vec<_>>();
        for token in tokens.into_iter().rev() {
            doc = Self::token(token, doc);
        }
        doc
    }

    /// Construct sanitized text with one semantic token.
    pub fn token_text(token: TokenId, value: impl AsRef<str>) -> Self {
        Self::token(token, Self::text(value))
    }

    pub fn group(doc: Self) -> Self {
        Self(laidout::Doc::group(doc.0))
    }

    pub fn fill(docs: impl IntoIterator<Item = Self>) -> Self {
        Self(laidout::Doc::fill(docs.into_iter().map(|doc| doc.0)))
    }

    pub fn nest(indent: u16, doc: Self) -> Self {
        Self(laidout::Doc::nest(u32::from(indent), doc.0))
    }

    pub fn align(doc: Self) -> Self {
        Self(laidout::Doc::align(doc.0))
    }

    pub fn concat(docs: impl IntoIterator<Item = Self>) -> Self {
        Self(laidout::Doc::concat(docs.into_iter().map(|doc| doc.0)))
    }

    pub fn join(separator: Self, docs: impl IntoIterator<Item = Self>) -> Self {
        Self(laidout::Doc::join(
            separator.0,
            docs.into_iter().map(|doc| doc.0),
        ))
    }

    pub fn choice(preferred: Self, alternative: Self) -> Self {
        Self(laidout::Doc::choice(preferred.0, alternative.0))
    }

    pub fn penalize(amount: u32, doc: Self) -> Self {
        Self(laidout::Doc::penalize(amount, doc.0))
    }

    pub fn prepare(&self) -> Result<PreparedDoc, HumanPrepareError> {
        // The outer default annotation makes unannotated and explicitly
        // default-token text resolve to the same prepared annotation identity.
        let root = laidout::Doc::annotate(tokens::TEXT, self.0.clone());
        root.prepare()
            .map(PreparedDoc)
            .map_err(HumanPrepareError::from)
    }

    fn from_human_text(value: HumanText) -> Self {
        let value = value.as_str();
        if value.is_empty() {
            return Self(
                laidout::Doc::try_text("")
                    .expect("sanitized empty human text is valid single-line text"),
            );
        }

        let mut chunks = Vec::new();
        let mut chunk_start = 0usize;
        let mut columns = 0u32;
        for (byte_offset, character) in value.char_indices() {
            let width = u32::try_from(UnicodeWidthChar::width(character).unwrap_or(0))
                .expect("one scalar display width fits u32");
            if columns.checked_add(width).is_none() {
                chunks.push(
                    laidout::Doc::try_text(&value[chunk_start..byte_offset])
                        .expect("sanitized human text chunk is valid"),
                );
                chunk_start = byte_offset;
                columns = 0;
            }
            columns = columns
                .checked_add(width)
                .expect("fresh human text chunk fits u32 display columns");
        }
        chunks.push(
            laidout::Doc::try_text(&value[chunk_start..])
                .expect("sanitized human text chunk is valid"),
        );
        Self(laidout::Doc::concat(chunks))
    }
}

impl PreparedDoc {
    pub(crate) fn inner(&self) -> &laidout::PreparedDoc<TokenId> {
        &self.0
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum TextLayout {
    Prose,
    Preformatted { tab_width: NonZeroU8 },
}

#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub enum HumanPreparedResource {
    Nodes,
    Edges,
    Texts,
    Annotations,
    TextBytes,
    DisplayColumns,
    OutputBytes,
    LineCount,
    Indentation,
    AnnotationDepth,
    SpanOccurrences,
    PlanNodes,
}

#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub enum HumanCostComponent {
    Overflow,
    Burden,
}

#[derive(Clone, Debug, Eq, PartialEq, thiserror::Error)]
pub enum HumanPrepareError {
    #[error("prepared {resource:?} representation requires {required:?}, maximum {maximum}")]
    RepresentationExceeded {
        resource: HumanPreparedResource,
        required: Option<u128>,
        maximum: u128,
    },
    #[error("prepared {component:?} cost requires {required:?}, maximum {maximum}")]
    CostDomainExceeded {
        component: HumanCostComponent,
        required: Option<u128>,
        maximum: u128,
    },
}

impl From<laidout::PrepareError> for HumanPrepareError {
    fn from(error: laidout::PrepareError) -> Self {
        match error {
            laidout::PrepareError::RepresentationExceeded {
                resource,
                required,
                maximum,
            } => Self::RepresentationExceeded {
                resource: map_prepared_resource(resource),
                required,
                maximum,
            },
            laidout::PrepareError::CostDomainExceeded {
                component,
                required,
                maximum,
            } => Self::CostDomainExceeded {
                component: map_cost_component(component),
                required,
                maximum,
            },
            _ => unreachable!("the exact Laidout 0.3.0 prepare-error vocabulary is pinned"),
        }
    }
}

fn map_prepared_resource(resource: laidout::PreparedResource) -> HumanPreparedResource {
    match resource {
        laidout::PreparedResource::Nodes => HumanPreparedResource::Nodes,
        laidout::PreparedResource::Edges => HumanPreparedResource::Edges,
        laidout::PreparedResource::Texts => HumanPreparedResource::Texts,
        laidout::PreparedResource::Annotations => HumanPreparedResource::Annotations,
        laidout::PreparedResource::TextBytes => HumanPreparedResource::TextBytes,
        laidout::PreparedResource::DisplayColumns => HumanPreparedResource::DisplayColumns,
        laidout::PreparedResource::OutputBytes => HumanPreparedResource::OutputBytes,
        laidout::PreparedResource::LineCount => HumanPreparedResource::LineCount,
        laidout::PreparedResource::Indentation => HumanPreparedResource::Indentation,
        laidout::PreparedResource::AnnotationDepth => HumanPreparedResource::AnnotationDepth,
        laidout::PreparedResource::SpanOccurrences => HumanPreparedResource::SpanOccurrences,
        laidout::PreparedResource::PlanNodes => HumanPreparedResource::PlanNodes,
        _ => unreachable!("the exact Laidout 0.3.0 prepared-resource vocabulary is pinned"),
    }
}

fn map_cost_component(component: laidout::CostComponent) -> HumanCostComponent {
    match component {
        laidout::CostComponent::Overflow => HumanCostComponent::Overflow,
        laidout::CostComponent::Burden => HumanCostComponent::Burden,
        _ => unreachable!("the exact Laidout 0.3.0 cost-component vocabulary is pinned"),
    }
}

fn normalize_line_endings(value: &str) -> Cow<'_, str> {
    if !value.contains('\r') {
        return Cow::Borrowed(value);
    }
    let mut normalized = String::with_capacity(value.len());
    let mut characters = value.chars().peekable();
    while let Some(character) = characters.next() {
        if character == '\r' {
            if characters.peek() == Some(&'\n') {
                characters.next();
            }
            normalized.push('\n');
        } else {
            normalized.push(character);
        }
    }
    Cow::Owned(normalized)
}

fn prose_doc(normalized: &str) -> Doc {
    let mut paragraphs = Vec::new();
    let mut words = Vec::new();
    for line in normalized.split('\n') {
        if line.trim().is_empty() {
            if !words.is_empty() {
                paragraphs.push(Doc::fill(std::mem::take(&mut words)));
            }
        } else {
            words.extend(line.split_whitespace().map(Doc::text));
        }
    }
    if !words.is_empty() {
        paragraphs.push(Doc::fill(words));
    }
    Doc::join(
        Doc::concat([Doc::hard_line(), Doc::hard_line()]),
        paragraphs,
    )
}

fn preformatted_doc(normalized: &str, tab_width: NonZeroU8) -> Doc {
    if normalized.is_empty() {
        return Doc::empty();
    }
    let mut docs = Vec::new();
    for (index, line) in normalized.split('\n').enumerate() {
        if index > 0 {
            docs.push(Doc::hard_line());
        }
        docs.push(Doc::text(expand_tabs(line, tab_width)));
    }
    Doc::concat(docs)
}

fn expand_tabs(line: &str, tab_width: NonZeroU8) -> String {
    let tab_width = usize::from(tab_width.get());
    let mut expanded = String::with_capacity(line.len());
    let mut column = 0usize;
    for character in line.chars() {
        if character == '\t' {
            let spaces = tab_width - (column % tab_width);
            expanded.extend(std::iter::repeat_n(' ', spaces));
            column += spaces;
        } else {
            expanded.push(character);
            column += UnicodeWidthChar::width(character).unwrap_or(0);
        }
    }
    expanded
}

pub(crate) fn display_width(value: &str) -> usize {
    UnicodeWidthStr::width(value)
}

pub(crate) fn render_options(
    width: NonZeroU32,
    options: crate::HumanLayoutOptions,
) -> laidout::RenderOptions {
    laidout::RenderOptions::new(width)
        .with_strategy(match options.strategy() {
            crate::LayoutStrategy::Fast => laidout::LayoutStrategy::Fast,
            crate::LayoutStrategy::Exact => laidout::LayoutStrategy::Exact,
        })
        .with_newline_cost(options.newline_cost())
        .with_indent_policy(laidout::IndentPolicy::ClampToWidthMinusOne)
}