citum_engine/render/

latex.rs

/*
SPDX-License-Identifier: MIT OR Apache-2.0
SPDX-FileCopyrightText: © 2023-2026 Bruce D'Arcus and Citum contributors
*/

//! LaTeX output format.

use super::format::{OutputFormat, QuoteMarks};
use citum_schema::template::WrapPunctuation;

/// LaTeX renderer.
#[derive(Debug, Clone, Default)]
pub struct Latex;

impl Latex {
    /// Escapes characters that break a LaTeX `\href{...}` URL argument.
    ///
    /// Minimal set for the audit finding: a bare `%` starts a LaTeX comment
    /// and truncates the rest of the line, `#` breaks `{}`-grouping (macro
    /// parameter syntax), and `\` would otherwise be read as a control
    /// sequence. `\` is escaped first so the backslash-introducing escapes
    /// for `%`/`#` are not themselves re-escaped.
    fn escape_href_target(url: &str) -> String {
        url.replace('\\', r"\textbackslash{}")
            .replace('%', r"\%")
            .replace('#', r"\#")
    }
}

impl OutputFormat for Latex {
    type Output = String;

    fn text(&self, s: &str) -> Self::Output {
        let mut res = String::with_capacity(s.len() + 10);
        for c in s.chars() {
            match c {
                '\\' => res.push_str(r"\textbackslash{}"),
                '{' => res.push_str(r"\{"),
                '}' => res.push_str(r"\}"),
                '$' => res.push_str(r"\$"),
                '&' => res.push_str(r"\&"),
                '#' => res.push_str(r"\#"),
                '_' => res.push_str(r"\_"),
                '%' => res.push_str(r"\%"),
                '~' => res.push_str(r"\textasciitilde{}"),
                '^' => res.push_str(r"\textasciicircum{}"),
                _ => res.push(c),
            }
        }
        res
    }

    fn join(&self, items: Vec<Self::Output>, delimiter: &str) -> Self::Output {
        items.join(&self.text(delimiter))
    }

    fn finish(&self, output: Self::Output) -> String {
        // Escape any bare & not already preceded by backslash.
        // Locale terms (e.g. the & from AndOptions::Symbol) bypass text() and
        // arrive here unescaped; this final pass makes the output valid LaTeX.
        let mut result = String::with_capacity(output.len() + 4);
        let mut prev = '\0';
        for c in output.chars() {
            if c == '&' && prev != '\\' {
                result.push_str(r"\&");
            } else {
                result.push(c);
            }
            prev = c;
        }
        result
    }

    fn emph(&self, content: Self::Output) -> Self::Output {
        format!(r"\emph{{{content}}}")
    }

    fn strong(&self, content: Self::Output) -> Self::Output {
        format!(r"\textbf{{{content}}}")
    }

    fn small_caps(&self, content: Self::Output) -> Self::Output {
        format!(r"\textsc{{{content}}}")
    }

    fn superscript(&self, content: Self::Output) -> Self::Output {
        format!(r"\textsuperscript{{{content}}}")
    }

    fn quote(&self, content: Self::Output, marks: &QuoteMarks) -> Self::Output {
        let (open, close) = marks.for_depth(0);
        format!("{open}{content}{close}")
    }

    fn affix(&self, prefix: &str, content: Self::Output, suffix: &str) -> Self::Output {
        format!("{}{}{}", self.text(prefix), content, self.text(suffix))
    }

    fn inner_affix(&self, prefix: &str, content: Self::Output, suffix: &str) -> Self::Output {
        format!("{}{}{}", self.text(prefix), content, self.text(suffix))
    }

    fn wrap_punctuation(
        &self,
        wrap: &WrapPunctuation,
        content: Self::Output,
        marks: &QuoteMarks,
    ) -> Self::Output {
        match wrap {
            WrapPunctuation::Parentheses => format!("({content})"),
            WrapPunctuation::Brackets => format!("[{content}]"),
            WrapPunctuation::Quotes => self.quote(content, marks),
        }
    }

    fn semantic(&self, _class: &str, content: Self::Output) -> Self::Output {
        // In LaTeX, we could use custom commands if we wanted semantic tagging
        // For now, just return content
        content
    }

    fn annotation(&self, content: Self::Output) -> Self::Output {
        if content.is_empty() {
            return content;
        }
        format!(
            "\n\\begin{{citumannotation}}\n{}\n\\end{{citumannotation}}",
            content
        )
    }

    fn link(&self, url: &str, content: Self::Output) -> Self::Output {
        let target = Self::escape_href_target(url);
        format!(r"\href{{{target}}}{{{content}}}")
    }

    // ── Block-level body markup methods ────────────────────────────────────

    fn paragraph(&self, content: Self::Output) -> Self::Output {
        if content.is_empty() {
            return content;
        }
        format!("{content}\n\n")
    }

    fn block_quote(&self, content: Self::Output) -> Self::Output {
        if content.is_empty() {
            return content;
        }
        let trimmed = content.trim_end();
        format!("\\begin{{quote}}\n{trimmed}\n\\end{{quote}}\n\n")
    }

    fn bullet_list(&self, items: Vec<Self::Output>) -> Self::Output {
        if items.is_empty() {
            return String::new();
        }
        let body = items
            .iter()
            .map(|item| format!("  \\item {}", item.trim()))
            .collect::<Vec<_>>()
            .join("\n");
        format!("\\begin{{itemize}}\n{body}\n\\end{{itemize}}\n\n")
    }

    fn ordered_list(&self, items: Vec<Self::Output>) -> Self::Output {
        if items.is_empty() {
            return String::new();
        }
        let body = items
            .iter()
            .map(|item| format!("  \\item {}", item.trim()))
            .collect::<Vec<_>>()
            .join("\n");
        format!("\\begin{{enumerate}}\n{body}\n\\end{{enumerate}}\n\n")
    }

    fn heading(&self, level: u8, content: Self::Output) -> Self::Output {
        let cmd = match level {
            1 => "\\section",
            2 => "\\subsection",
            3 => "\\subsubsection",
            _ => "\\paragraph",
        };
        format!("{cmd}{{{content}}}\n\n")
    }

    fn unnumbered_heading(&self, level: u8, content: Self::Output) -> Self::Output {
        let cmd = match level {
            1 => "\\section*",
            2 => "\\subsection*",
            3 => "\\subsubsection*",
            _ => "\\paragraph*",
        };
        format!("{cmd}{{{content}}}\n\n")
    }

    fn code_block(&self, _lang: Option<&str>, content: Self::Output) -> Self::Output {
        format!("\\begin{{verbatim}}\n{content}\\end{{verbatim}}\n\n")
    }

    fn inline_code(&self, content: Self::Output) -> Self::Output {
        // \texttt is not verbatim; escape LaTeX specials in the raw code content.
        format!("\\texttt{{{}}}", self.text(&content))
    }

    fn strikeout(&self, content: Self::Output) -> Self::Output {
        if content.is_empty() {
            return content;
        }
        format!("\\sout{{{content}}}")
    }

    fn hard_break(&self) -> Self::Output {
        "\\\\\n".to_string()
    }

    fn bibliography(&self, entries: Vec<Self::Output>) -> Self::Output {
        entries.join("\\par\\vspace{0.5em}")
    }

    fn entry(
        &self,
        _id: &str,
        content: Self::Output,
        _url: Option<&str>,
        _metadata: &super::format::ProcEntryMetadata,
    ) -> Self::Output {
        format!("\\noindent\\hangindent=2em\\hangafter=1 {content}")
    }
}