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

math_core/
lib.rs
