math_core/
lib.rs

1//! Convert LaTeX math to MathML Core.
2//!
3//! For more background on what that means and on what to do with the resulting MathML code,
4//! see the repo's README: https://github.com/tmke8/math-core
5//!
6//! # Usage
7//!
8//! The main struct of this library is [`LatexToMathML`]. In order to use the library, create an
9//! instance of this struct and then call one of the convert functions. The constructor of the
10//! struct expects a config object in the form of an instance of [`MathCoreConfig`].
11//!
12//! Basic use looks like this:
13//!
14//! ```rust
15//! use math_core::{LatexToMathML, MathCoreConfig, MathDisplay};
16//!
17//! let latex = r#"\erf ( x ) = \frac{ 2 }{ \sqrt{ \pi } } \int_0^x e^{- t^2} \, dt"#;
18//! let config = MathCoreConfig::default();
19//! let converter = LatexToMathML::new(config).unwrap();
20//! let mathml = converter.convert_with_local_counter(latex, MathDisplay::Block).unwrap();
21//! println!("{}", mathml);
22//! ```
23//!
24//! # Features
25//!
26//! - `serde`: With this feature, `MathCoreConfig` implements serde's `Deserialize`.
27//!
28mod atof;
29mod character_class;
30mod color_defs;
31mod commands;
32mod environments;
33mod error;
34mod html_utils;
35mod lexer;
36mod parser;
37mod predefined;
38mod specifications;
39mod text_parser;
40mod token;
41mod token_queue;
42
43use std::num::NonZeroU16;
44
45use rustc_hash::{FxBuildHasher, FxHashMap};
46#[cfg(feature = "serde")]
47use serde::{Deserialize, Serialize};
48
49use mathml_renderer::{arena::Arena, ast::Node, fmt::new_line_and_indent};
50
51pub use self::error::LatexError;
52use self::{error::LatexErrKind, lexer::Lexer, parser::Parser, token::Token};
53
54/// Display mode for the LaTeX math equations.
55#[derive(Debug, Clone, Copy, PartialEq, Eq)]
56pub enum MathDisplay {
57    /// For inline equations, like those in `$...$` in LaTeX.
58    Inline,
59    /// For block equations (or "display style" equations), like those in `$$...$$` in LaTeX.
60    Block,
61}
62
63/// Configuration for pretty-printing the MathML output.
64///
65/// Pretty-printing means that newlines and indentation is added to the MathML output, to make it
66/// easier to read.
67#[derive(Debug, Clone, Copy, Default)]
68#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
69#[cfg_attr(feature = "serde", serde(rename_all = "kebab-case"))]
70#[non_exhaustive]
71pub enum PrettyPrint {
72    /// Never pretty print.
73    #[default]
74    Never,
75    /// Always pretty print.
76    Always,
77    /// Pretty print for block equations only.
78    Auto,
79}
80
81/// Configuration object for the LaTeX to MathML conversion.
82///
83/// # Example usage
84///
85/// ```rust
86/// use math_core::{MathCoreConfig, PrettyPrint};
87///
88/// // Default values
89/// let config = MathCoreConfig::default();
90///
91/// // Specifying pretty-print behavior
92/// let config = MathCoreConfig {
93///     pretty_print: PrettyPrint::Always,
94///     ..Default::default()
95///  };
96///
97/// // Specifying pretty-print behavior and custom macros
98/// let macros = vec![
99///     ("d".to_string(), r"\mathrm{d}".to_string()),
100///     ("bb".to_string(), r"\mathbb{#1}".to_string()), // with argument
101/// ];
102/// let config = MathCoreConfig {
103///     pretty_print: PrettyPrint::Auto,
104///     macros,
105///     ..Default::default()
106/// };
107/// ```
108///
109#[derive(Debug, Default)]
110#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
111#[cfg_attr(feature = "serde", serde(default, rename_all = "kebab-case"))]
112pub struct MathCoreConfig {
113    /// A configuration for pretty-printing the MathML output. See [`PrettyPrint`] for details.
114    pub pretty_print: PrettyPrint,
115    /// A list of LaTeX macros; each tuple contains (macro_name, macro_definition).
116    #[cfg_attr(feature = "serde", serde(with = "tuple_vec_map"))]
117    pub macros: Vec<(String, String)>,
118    /// If `true`, include `xmlns="http://www.w3.org/1998/Math/MathML"` in the `<math>` tag.
119    pub xml_namespace: bool,
120    /// If `true`, unknown commands will be rendered as red text in the output, instead of
121    /// returning an error.
122    pub ignore_unknown_commands: bool,
123    /// If `true`, wrap the MathML output in `<semantics>` tags with an
124    /// `<annotation encoding="application/x-tex">` child containing the original LaTeX source.
125    pub annotation: bool,
126}
127
128#[derive(Debug, Default)]
129struct CommandConfig {
130    custom_cmd_tokens: Vec<Token<'static>>,
131    custom_cmd_map: FxHashMap<String, (u8, (usize, usize))>,
132    ignore_unknown_commands: bool,
133}
134
135impl CommandConfig {
136    pub fn get_command<'config>(&'config self, command: &str) -> Option<Token<'config>> {
137        let (num_args, slice) = *self.custom_cmd_map.get(command)?;
138        let tokens = self.custom_cmd_tokens.get(slice.0..slice.1)?;
139        Some(Token::CustomCmd(num_args, tokens))
140    }
141}
142
143/// This struct contains those fields from `MathCoreConfig` that are simple flags.
144#[derive(Debug, Default)]
145struct Flags {
146    pretty_print: PrettyPrint,
147    xml_namespace: bool,
148    annotation: bool,
149}
150
151impl From<&MathCoreConfig> for Flags {
152    fn from(config: &MathCoreConfig) -> Self {
153        // TODO: can we use a macro here to avoid repeating the field names?
154        Self {
155            pretty_print: config.pretty_print,
156            xml_namespace: config.xml_namespace,
157            annotation: config.annotation,
158        }
159    }
160}
161
162/// A converter that transforms LaTeX math equations into MathML Core.
163#[derive(Debug, Default)]
164pub struct LatexToMathML {
165    flags: Flags,
166    /// This is used for numbering equations in the document.
167    equation_count: u16,
168    label_map: FxHashMap<Box<str>, NonZeroU16>,
169    cmd_cfg: Option<CommandConfig>,
170}
171
172impl LatexToMathML {
173    /// Create a new `LatexToMathML` converter with the given configuration.
174    ///
175    /// This function returns an error if the custom macros in the given configuration could not
176    /// be parsed. The error contains the parsing error, the macro index and the macro definition
177    /// that caused the error.
178    pub fn new(config: MathCoreConfig) -> Result<Self, (Box<LatexError>, usize, String)> {
179        Ok(Self {
180            flags: Flags::from(&config),
181            equation_count: 0,
182            label_map: FxHashMap::default(),
183            cmd_cfg: Some(parse_custom_commands(
184                config.macros,
185                config.ignore_unknown_commands,
186            )?),
187        })
188    }
189
190    /// Convert LaTeX text to MathML with a global equation counter.
191    ///
192    /// For basic usage, see the documentation of [`convert_with_local_counter`].
193    ///
194    /// This conversion function maintains state, in order to count equations correctly across
195    /// different calls to this function.
196    ///
197    /// The counter can be reset with [`reset_global_counter`].
198    pub fn convert_with_global_counter(
199        &mut self,
200        latex: &str,
201        display: MathDisplay,
202    ) -> Result<String, Box<LatexError>> {
203        convert(
204            latex,
205            display,
206            self.cmd_cfg.as_ref(),
207            &mut self.equation_count,
208            &mut self.label_map,
209            &self.flags,
210        )
211    }
212
213    /// Convert LaTeX text to MathML.
214    ///
215    /// The second argument specifies whether it is inline-equation or block-equation.
216    ///
217    /// ```rust
218    /// use math_core::{LatexToMathML, MathCoreConfig, MathDisplay};
219    ///
220    /// let latex = r#"(n + 1)! = \Gamma ( n + 1 )"#;
221    /// let config = MathCoreConfig::default();
222    /// let converter = LatexToMathML::new(config).unwrap();
223    /// let mathml = converter.convert_with_local_counter(latex, MathDisplay::Inline).unwrap();
224    /// println!("{}", mathml);
225    ///
226    /// let latex = r#"x = \frac{ - b \pm \sqrt{ b^2 - 4 a c } }{ 2 a }"#;
227    /// let mathml = converter.convert_with_local_counter(latex, MathDisplay::Block).unwrap();
228    /// println!("{}", mathml);
229    /// ```
230    ///
231    #[inline]
232    pub fn convert_with_local_counter(
233        &self,
234        latex: &str,
235        display: MathDisplay,
236    ) -> Result<String, Box<LatexError>> {
237        let mut equation_count = 0;
238        let mut label_map = FxHashMap::default();
239        convert(
240            latex,
241            display,
242            self.cmd_cfg.as_ref(),
243            &mut equation_count,
244            &mut label_map,
245            &self.flags,
246        )
247    }
248
249    /// Reset the equation counter to zero.
250    ///
251    /// This should normally be done at the beginning of a new document or section.
252    pub fn reset_global_counter(&mut self) {
253        self.equation_count = 0;
254    }
255}
256
257fn convert(
258    latex: &str,
259    display: MathDisplay,
260    cmd_cfg: Option<&CommandConfig>,
261    equation_count: &mut u16,
262    label_map: &mut FxHashMap<Box<str>, NonZeroU16>,
263    flags: &Flags,
264) -> Result<String, Box<LatexError>> {
265    let arena = Arena::new();
266    let ast = parse(latex, &arena, cmd_cfg, equation_count, label_map)?;
267
268    let mut output = String::new();
269    output.push_str("<math");
270    if flags.xml_namespace {
271        output.push_str(" xmlns=\"http://www.w3.org/1998/Math/MathML\"");
272    }
273    if matches!(display, MathDisplay::Block) {
274        output.push_str(" display=\"block\"");
275    }
276    output.push('>');
277
278    let pretty_print = matches!(flags.pretty_print, PrettyPrint::Always)
279        || (matches!(flags.pretty_print, PrettyPrint::Auto) && display == MathDisplay::Block);
280
281    let base_indent = if pretty_print { 1 } else { 0 };
282    if flags.annotation {
283        let children_indent = if pretty_print { 2 } else { 0 };
284        new_line_and_indent(&mut output, base_indent);
285        output.push_str("<semantics>");
286        let node = parser::node_vec_to_node(&arena, &ast, false);
287        let _ = node.emit(&mut output, children_indent);
288        new_line_and_indent(&mut output, children_indent);
289        output.push_str("<annotation encoding=\"application/x-tex\">");
290        html_utils::escape_html_content(&mut output, latex);
291        output.push_str("</annotation>");
292        new_line_and_indent(&mut output, base_indent);
293        output.push_str("</semantics>");
294    } else {
295        for node in ast {
296            // We ignore the result of `emit` here, because the only possible error is a formatting
297            // error when writing to the string, and that can only happen if the string's `write_str`
298            // implementation returns an error. Since `String`'s `write_str` implementation never
299            // returns an error, we can safely ignore the result of `emit`.
300            let _ = node.emit(&mut output, base_indent);
301        }
302    }
303    if pretty_print {
304        output.push('\n');
305    }
306    output.push_str("</math>");
307    Ok(output)
308}
309
310fn parse<'config, 'source, 'arena>(
311    latex: &'source str,
312    arena: &'arena Arena,
313    cmd_cfg: Option<&'config CommandConfig>,
314    equation_count: &'arena mut u16,
315    label_map: &'arena mut FxHashMap<Box<str>, NonZeroU16>,
316) -> Result<Vec<&'arena Node<'arena>>, Box<LatexError>>
317where
318    'config: 'source,
319    'source: 'arena,
320{
321    let lexer = Lexer::new(latex, false, cmd_cfg);
322    let mut p = Parser::new(lexer, arena, equation_count, label_map)?;
323    let nodes = p.parse()?;
324    Ok(nodes)
325}
326
327fn parse_custom_commands(
328    macros: Vec<(String, String)>,
329    ignore_unknown_commands: bool,
330) -> Result<CommandConfig, (Box<LatexError>, usize, String)> {
331    let mut map = FxHashMap::with_capacity_and_hasher(macros.len(), FxBuildHasher);
332    let mut tokens = Vec::new();
333    for (idx, (name, definition)) in macros.into_iter().enumerate() {
334        if !is_valid_macro_name(name.as_str()) {
335            return Err((
336                Box::new(LatexError(0..0, LatexErrKind::InvalidMacroName(name))),
337                idx,
338                definition,
339            ));
340        }
341
342        // In order to be able to return `definition` in case of an error, we need to ensure
343        // that the lexer (which borrows `definition`) is dropped before we return the error.
344        // Therefore, we put the whole lexing process into its own block.
345        let value = 'value: {
346            let mut lexer: Lexer<'static, '_> = Lexer::new(definition.as_str(), true, None);
347            let start = tokens.len();
348            loop {
349                match lexer.next_token_no_unknown_command() {
350                    Ok(tokloc) => {
351                        if matches!(tokloc.token(), Token::Eoi) {
352                            break;
353                        }
354                        tokens.push(tokloc.into_token());
355                    }
356                    Err(err) => {
357                        break 'value Err(err);
358                    }
359                }
360            }
361            let end = tokens.len();
362            let num_args = lexer.parse_cmd_args().unwrap_or(0);
363            Ok((num_args, (start, end)))
364        };
365
366        match value {
367            Err(err) => {
368                return Err((err, idx, definition));
369            }
370            Ok(v) => {
371                map.insert(name, v);
372            }
373        }
374    }
375    Ok(CommandConfig {
376        custom_cmd_tokens: tokens,
377        custom_cmd_map: map,
378        ignore_unknown_commands,
379    })
380}
381
382fn is_valid_macro_name(s: &str) -> bool {
383    if s.is_empty() {
384        return false;
385    }
386    let mut chars = s.chars();
387    match (chars.next(), chars.next()) {
388        // If the name contains only one character, any character is valid.
389        (Some(_), None) => true,
390        // If the name contains more than one character, all characters must be ASCII alphabetic.
391        _ => s.bytes().all(|b| b.is_ascii_alphabetic()),
392    }
393}
math_core/lib.rs

math_core/
lib.rs
