lib.rs

//! suki - a library that typesets LaTeX formulas into HTML and SVG
//!
//! Reading (parse), typesetting (layout) and output (html, svg) are kept separate.
//! Positions and dimensions are decided once in layout, and HTML and SVG only write them out.
//!
//! The font decides how formulas are typeset. From the OpenType MATH table, the library reads
//! the height of the math axis, the rule thickness, how much scripts are scaled down and shifted
//! up, and the spaces in radicals. A stretchy delimiter is not made by scaling a glyph. It is
//! made from the font's glyphs of different sizes, or assembled from the font's glyph parts.
//! When the typeface changes, the typesetting changes with it.
//!
//! ```
//! use suki::{Mode, Shape};
//!
//! let data = std::fs::read("font/latinmodern-math.otf").unwrap();
//! let font = suki::load_font(data).unwrap();
//! let html = suki::render_html(r"\frac{a}{b}", &font, Mode::Inline).unwrap();
//! let svg = suki::render_svg(r"\sum_{k=1}^{n} k", &font, Mode::Display, Shape::Outline).unwrap();
//! ```
//!
//! HTML places characters, so put the CSS returned by [`style`] in a style element, and provide
//! the same font where the HTML is displayed. SVG written with [`Shape::Outline`] needs no font.

pub mod cff;
pub mod error;
pub mod font;
pub mod glyf;
pub mod html;
pub mod layout;
pub mod math;
pub mod metric;
pub mod node;
pub mod opentype;
pub mod outline;
pub mod parse;
pub mod svg;
pub mod symbol;
pub mod text;
pub mod token;
#[cfg(target_arch = "wasm32")]
pub mod wasm;

pub use error::Error;
pub use font::{Font, load as load_font};
pub use html::style;
pub use layout::Shape;
pub use node::{Align, Class, Node, Spacing, Style};
pub use parse::{Wrapper, parse};
pub use text::escape;


/// The style. Display is on a line of its own, and Inline is within text
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Mode {
    Inline,
    Display,
}


/// Prefers the style the wrapper indicates, and uses the given style if there is no wrapper
fn choose(wrapper: Wrapper, mode: Mode) -> Mode {
    if parse::display_of(wrapper, mode == Mode::Display) {
        Mode::Display
    } else {
        Mode::Inline
    }
}


fn build(node: &Node, font: &Font, mode: Mode) -> layout::Layout {
    layout::layout(node, font, 1.0, Style::Auto, mode == Mode::Display)
}


/// Turns a syntax tree into HTML. Glyphs are placed as characters
pub fn to_html(node: &Node, font: &Font, mode: Mode) -> String {
    html::render(&build(node, font, mode), font)
}


/// Turns a syntax tree into SVG. label becomes the alternative text
pub fn to_svg(node: &Node, font: &Font, mode: Mode, shape: Shape, label: &str) -> String {
    svg::render(&build(node, font, mode), font, shape, label)
}


/// Turns a LaTeX string into HTML
///
/// If the string has a wrapper such as `$…$` or `\[…\]`, the wrapper decides the style.
/// Otherwise mode is used as it is
pub fn render_html(source: &str, font: &Font, mode: Mode) -> Result<String, Error> {
    let (node, wrapper) = parse::parse_wrapped(source)?;

    Ok(to_html(&node, font, choose(wrapper, mode)))
}


/// Turns a LaTeX string into SVG
pub fn render_svg(
    source: &str,
    font: &Font,
    mode: Mode,
    shape: Shape,
) -> Result<String, Error> {
    let (node, wrapper) = parse::parse_wrapped(source)?;

    Ok(to_svg(&node, font, choose(wrapper, mode), shape, source))
}


#[cfg(test)]
mod tests {
    use super::*;

    fn sample() -> Font {
        let data = std::fs::read("font/latinmodern-math.otf").expect("cannot read the test font");

        load_font(data).unwrap()
    }

    #[test]
    fn renders_both_shapes() {
        let font = sample();
        let source = r"x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}";
        let html = render_html(source, &font, Mode::Inline).unwrap();
        assert!(html.starts_with("<span class=\"suki\""));
        assert!(html.ends_with("</span>"));

        for shape in [Shape::Text, Shape::Outline] {
            let svg = render_svg(source, &font, Mode::Display, shape).unwrap();
            assert!(svg.starts_with("<svg"));
            assert!(svg.ends_with("</svg>"));
        }
    }

    #[test]
    fn outlines_need_no_font_at_the_other_end() {
        let font = sample();
        let svg = render_svg(r"\sqrt{x}", &font, Mode::Display, Shape::Outline).unwrap();
        assert!(!svg.contains("font-family"));
        assert!(!svg.contains("<text"));
    }

    #[test]
    fn display_and_inline_differ() {
        let font = sample();
        let source = r"\sum_{k=1}^{n} k";
        let inline = render_svg(source, &font, Mode::Inline, Shape::Outline).unwrap();
        let display = render_svg(source, &font, Mode::Display, Shape::Outline).unwrap();
        assert_ne!(inline, display);
    }

    #[test]
    fn every_supported_shape_renders() {
        let font = sample();
        let sources = [
            r"x^2 + y^2 = r^2",
            r"e^{i\pi} + 1 = 0",
            r"\sum_{k=1}^{n} k = \frac{n(n+1)}{2}",
            r"\int_0^1 x^2 \, dx = \frac{1}{3}",
            r"\lim_{x \to \infty} \frac{1}{x} = 0",
            r"\sqrt[3]{x + 1}",
            r"\left( \frac{a}{b} \right)^{n}",
            r"\left\{ x \in \mathbb{R} \mid x > 0 \right\}",
            r"\binom{n}{k} = \frac{n!}{k!(n-k)!}",
            r"\begin{pmatrix} a & b \\ c & d \end{pmatrix}",
            r"\begin{array}{lr} \hline a & b \\ \hline \end{array}",
            r"\begin{cases} 1 & x > 0 \\ 0 & x \leq 0 \end{cases}",
            r"\overline{AB} \ne \underline{CD}",
            r"\hat{x} + \vec{v} + \bar{y} + \dot{z}",
            r"\mathbf{A} \mathrm{d} \mathbb{Z} \mathit{f}",
            r"\text{ここは文章です}",
        ];

        for source in sources {
            assert!(render_html(source, &font, Mode::Display).is_ok(), "HTML: {source}");

            for shape in [Shape::Text, Shape::Outline] {
                assert!(
                    render_svg(source, &font, Mode::Display, shape).is_ok(),
                    "SVG: {source}"
                );
            }
        }
    }

    #[test]
    fn both_outputs_name_the_same_fallback() {
        let font = sample();
        let source = r"\text{固有値}";
        let html = render_html(source, &font, Mode::Inline).unwrap();
        let svg = render_svg(source, &font, Mode::Inline, Shape::Outline).unwrap();
        // A character the typeface lacks falls back to the same typeface in both outputs
        assert!(style(&font).contains(font::FALLBACK));
        assert!(svg.contains(font::FALLBACK), "{svg}");
        assert!(html.contains("固"));
        assert!(svg.contains("固"));
    }

    /// Returns only the dimensions of the output. The alternative text differs even for the
    /// same formula, so it is not compared
    fn frame(markup: &str) -> &str {
        let at = markup.find("viewBox=\"").expect("viewBox is missing") + 9;
        let end = markup[at..].find('"').expect("viewBox is not closed");

        &markup[at..at + end]
    }

    #[test]
    fn a_wrapper_decides_the_shape() {
        let font = sample();
        let source = r"\sum_{k=1}^{n}";
        let display = render_svg(source, &font, Mode::Display, Shape::Outline).unwrap();
        let inline = render_svg(source, &font, Mode::Inline, Shape::Outline).unwrap();
        assert_ne!(frame(&display), frame(&inline), "the dimensions do not change with the style");

        // A wrapper, when present, takes priority over the given style
        for (wrapped, wanted) in [
            (r"$$\sum_{k=1}^{n}$$", &display),
            (r"\[\sum_{k=1}^{n}\]", &display),
            (r"$\sum_{k=1}^{n}$", &inline),
            (r"\(\sum_{k=1}^{n}\)", &inline),
        ] {
            let opposite = if std::ptr::eq(wanted, &display) {Mode::Inline} else {Mode::Display};
            let out = render_svg(wrapped, &font, opposite, Shape::Outline).unwrap();
            assert_eq!(frame(&out), frame(wanted), "the wrapper has no effect: {wrapped}");
        }
    }

    #[test]
    fn errors_point_at_the_source() {
        let font = sample();
        let error = render_html(r"\frac{a}{b", &font, Mode::Inline).unwrap_err();
        assert!(error.to_string().contains("at character"));
    }
}