mathra 1.2.0

Equation converter: math LaTeX to a tree of meaning and accessible SVG, with locale rules (English and pt-BR).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218

//! mathra: equations as a tree of meaning, drawn with explicit rules.
//!
//! ```
//! let svg = mathra::tex_to_svg("3.14").unwrap();
//! assert!(svg.contains("-speech\">3.14</title>"));
//! ```

pub mod font;
pub mod input;
pub mod layout;
pub mod locale;
pub mod output;
pub mod rules;
pub mod tree;

use std::fmt;

pub use locale::Locale;
pub use output::braille::BrailleCode;
pub use rules::Applied;
pub use tree::{Class, Node};

pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// The notation the equation is written in.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Input {
    /// Math LaTeX. MathML pasted here (starting with `<math`) is recognized and read as MathML (L-ENT-4).
    #[default]
    Latex,
    /// Presentation MathML: what Word, Google Docs, MathType and MathJax export.
    MathMl,
    /// AsciiMath (asciimath.org): `sum_(i=1)^n i^2`.
    AsciiMath,
}

impl Input {
    pub const ALL: [Input; 3] = [Input::Latex, Input::MathMl, Input::AsciiMath];

    pub fn code(self) -> &'static str {
        match self {
            Input::Latex => "latex",
            Input::MathMl => "mathml",
            Input::AsciiMath => "asciimath",
        }
    }
}

impl fmt::Display for Input {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.code())
    }
}

impl std::str::FromStr for Input {
    type Err = String;

    /// `latex` (or `tex`), `mathml` (or `mml`), `asciimath` (or `am`), in any case.
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.to_ascii_lowercase().as_str() {
            "latex" | "tex" => Ok(Input::Latex),
            "mathml" | "mml" => Ok(Input::MathMl),
            "asciimath" | "am" => Ok(Input::AsciiMath),
            other => Err(format!("unknown input format: {other} (use latex, mathml or asciimath)")),
        }
    }
}

#[derive(Debug, Clone)]
pub struct Options {
    pub locale: Locale,
    /// Display equation (like `$$…$$`), or inline with the text (like `$…$`).
    pub display: bool,
    /// Refuse invalid LaTeX, like TeX does. Without it, mathra recovers what it can and returns warnings.
    pub strict: bool,
    /// The notation of the input. LaTeX by default.
    pub input: Input,
    /// The braille code of [`Output::braille`]. `None`: the language's (CMU in pt-BR and es, Nemeth elsewhere).
    pub braille: Option<BrailleCode>,
}

impl Default for Options {
    fn default() -> Self {
        Options { locale: Locale::default(), display: true, strict: false, input: Input::Latex, braille: None }
    }
}

/// The tree of meaning of an equation, in the notation `options.input` says.
fn read(source: &str, options: &Options, registry: &mut rules::Registry) -> Result<(Node, Input), Error> {
    let input = match options.input {
        Input::Latex if input::mathml::looks_like_mathml(source) => {
            registry.note(rules::L_ENT_4, "MathML pasted as LaTeX: read as MathML");
            Input::MathMl
        }
        other => other,
    };
    let tree = match input {
        Input::Latex => input::latex::read_with(source, options.locale, registry, options.strict)?,
        Input::MathMl => input::mathml::read_with(source, options.locale, registry, options.strict)?,
        Input::AsciiMath => input::asciimath::read_with(source, options.locale, registry, options.strict)?,
    };
    Ok((tree, input))
}

#[derive(Debug, Clone)]
pub struct Output {
    pub svg: String,
    pub tree: Node,
    pub speech: String,
    pub text: String,
    /// The equation in braille (Unicode braille cells), in the code of `braille_code`.
    pub braille: String,
    pub braille_code: BrailleCode,
    /// Rules that changed something in this equation, in the order they acted.
    pub applied: Vec<Applied>,
    /// Input problems the tolerant mode worked around (empty in strict mode).
    pub warnings: Vec<Applied>,
}

impl Output {
    /// Every output as one JSON object: `svg`, `speech`, `text`, `tree`, `applied` and `warnings`, the
    /// last two as lists of `{"rule", "description"}`. What the JavaScript and Python packages return.
    pub fn to_json(&self) -> String {
        let rules = |list: &[Applied]| -> Vec<serde_json::Value> { list.iter().map(|a| serde_json::json!({ "rule": a.rule, "description": a.description })).collect() };
        let tree: serde_json::Value = serde_json::from_str(&self.tree.to_json()).expect("the tree serializes to valid JSON");
        serde_json::json!({
            "svg": self.svg,
            "speech": self.speech,
            "text": self.text,
            "braille": self.braille,
            "braille_code": self.braille_code.code(),
            "tree": tree,
            "applied": rules(&self.applied),
            "warnings": rules(&self.warnings),
        })
        .to_string()
    }
}

#[derive(Debug, Clone, PartialEq)]
pub enum Error {
    Syntax { column: usize, message: String },
    MissingGlyph { character: char },
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Error::Syntax { column, message } => write!(f, "column {column}: {message}"),
            Error::MissingGlyph { character } => {
                write!(f, "the {} font has no '{character}' character (U+{:04X})", font::NAME, *character as u32)
            }
        }
    }
}

impl std::error::Error for Error {}

/// Converts an equation (LaTeX by default; see [`Options::input`]) to SVG, speech, text and tree.
pub fn convert(tex: &str, options: &Options) -> Result<Output, Error> {
    convert_in_font(tex, options, font::MathFont::default())
}

/// [`convert`], with the equation set in `font`.
pub fn convert_in_font(tex: &str, options: &Options, font: font::MathFont) -> Result<Output, Error> {
    let mut registry = rules::Registry::default();
    let (tree, input) = read(tex, options, &mut registry)?;
    let style = if options.display { layout::Style::display() } else { layout::Style::text() }.in_font(font);
    let math_box = {
        let mut ctx = layout::Context { locale: options.locale, registry: &mut registry, strict: options.strict };
        layout::compose(&tree, style, &mut ctx)?
    };
    let speech = output::speech::speak(&tree, options.locale);
    let text = output::text::linear(&tree, options.locale);
    let braille_code = options.braille.unwrap_or(BrailleCode::for_locale(options.locale));
    let braille = output::braille::transcribe(&tree, braille_code);
    for c in &braille.missing {
        registry.note(rules::S_BRL_1, format!("no {braille_code} braille sign for '{c}' (U+{:04X}): written as the full cell ⠿", *c as u32));
    }
    let tree_json = tree.to_json();
    registry.dedup();
    let svg = output::svg::generate(&output::svg::Content {
        math_box: &math_box,
        source: tex,
        input,
        tree_json: &tree_json,
        speech: &speech,
        text: &text,
        braille: &braille.text,
        braille_code,
        locale: options.locale,
        warnings: &registry.warnings,
        font,
    });
    Ok(Output { svg, tree, speech, text, braille: braille.text, braille_code, applied: registry.applied, warnings: registry.warnings })
}

/// The composed box, without generating SVG: for callers that draw the equation inside something
/// else (tikra's figure labels). Also returns the tolerant mode's warnings.
pub fn typeset(tex: &str, options: &Options) -> Result<(layout::MathBox, Vec<Applied>), Error> {
    typeset_in_font(tex, options, font::MathFont::default())
}

/// [`typeset`], with the equation set in `font` (its glyph ids are that font's).
pub fn typeset_in_font(tex: &str, options: &Options, font: font::MathFont) -> Result<(layout::MathBox, Vec<Applied>), Error> {
    let mut registry = rules::Registry::default();
    let (tree, _) = read(tex, options, &mut registry)?;
    let style = if options.display { layout::Style::display() } else { layout::Style::text() }.in_font(font);
    let mut ctx = layout::Context { locale: options.locale, registry: &mut registry, strict: options.strict };
    let math_box = layout::compose(&tree, style, &mut ctx)?;
    registry.dedup();
    Ok((math_box, registry.warnings))
}

/// Shortcut with the default locale (English).
pub fn tex_to_svg(tex: &str) -> Result<String, Error> {
    convert(tex, &Options::default()).map(|r| r.svg)
}