Tex2math 🚀

A blazing fast, zero-copy Rust library and CLI tool designed to parse LaTeX mathematical formulas and compile them into perfectly structured MathML XML.

Inspired by the robust AST designs of texmath and the rich symbol dictionaries of KaTeX, tex2math is built to be a lightweight, JavaScript-free alternative for generating native MathML directly on the backend (or via WebAssembly).

💡 Why `tex2math`?

Most lightweight Markdown parsers use fragile regular expressions to handle math, which fails catastrophically on nested structures like \sqrt{\frac{a}{b}}. On the other hand, full-blown engines like KaTeX require shipping a massive JavaScript runtime.

tex2math sits in the sweet spot:

True Parsing: It builds a complete Abstract Syntax Tree (AST) using parser combinators.
Native MathML: Outputs standard MathML that modern browsers (Chrome 109+, Safari, Firefox) render natively at 60fps without any client-side scripts.
Zero Overhead: Written in pure Rust. Memory allocations are kept to an absolute minimum.

✨ Key Features

⚡️ Blazing Fast & Zero-Copy: Built on top of the winnow parser combinator library, the lexer reads directly from string slices.
🎓 Academic-Grade Typography:
- Smart rendering of limits based on contexts (Inline vs Display).
- Multi-dimensional matrix alignments (\begin{align}).
- Dynamically stretchy braces (\left( \right]).
📚 Huge Symbol Dictionary: Natively supports over 450+ mathematical symbols, Greek letters, relational operators, and logic arrows—extracted directly from KaTeX source specs.
🛡️ Tolerant Parsing & Error Recovery: Designed to be indestructible. A missing } or unclosed environment will NOT crash the engine, but gracefully emit a red <merror> block while salvaging the rest of the formula.
🎨 Advanced Ecosystem Support: Out-of-the-box support for text modes (\text{...}), inline styling (\mathbf, \color), math accents (\vec, \overbrace), and complex tensor prescripts ({}_a^b X).

🛠️ Installation

As a Library (Crate)

Add this to your Cargo.toml. Note: The CLI dependencies are fully optional, keeping the library footprint incredibly small (~30KB).

[dependencies]
tex2math = "1.0"
winnow = "0.6"

As a CLI Tool

You can install the CLI tool directly using Cargo:

cargo install tex2math --features cli

🚀 Usage

💻 Using the CLI

The CLI is simple and easily integrated into bash pipelines (e.g., passing output directly to Pandoc or HTML generators).

# Direct argument evaluation
tex2math "\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}"

# Display mode evaluation (forces \sum limits to render top/bottom)
tex2math --display "\sum_{i=1}^n x_i"

# Pipe via stdin
echo "\int_0^\infty f(x) \, dx" | tex2math

🦀 Using the Library

use tex2math::{parse_row, MathMLRenderer, MathRenderer, RenderMode};
use winnow::Parser; 

fn main() {
    let latex_input = "\\underbrace{a+b}_{=X} \\times \\mathbf{R}";
    
    // The parser requires a mutable reference to the string slice (cursor)
    let mut input = latex_input;

    // 1. Parse the LaTeX string into an AST
    match parse_row.parse_next(&mut input) {
        Ok(ast) => {
            // 2. Initialize the backend renderer
            let renderer = MathMLRenderer::new();
            
            // 3. Generate MathML (Choose Inline or Display mode)
            let mathml = renderer.render(&ast, RenderMode::Display);
            println!("<math>{}</math>", mathml);
        }
        Err(e) => {
            eprintln!("Parse error: {}", e);
        }
    }
}

🏗️ Architecture

Parser Combinators (winnow): Transforms string slices into a highly structured MathNode enum.
AST Folding Pass: Post-processes the AST to handle complex semantic overrides, such as converting empty-based scripts into true MathML <mmultiscripts> (tensor prescripts).
Pluggable Renderers: The abstract MathRenderer trait decouples AST generation from final presentation mapping, allowing future expansions (e.g., Typst or HTML/CSS backends).

🧪 Development & Testing

This project strictly follows Test-Driven Development (TDD). It includes over 50 rigorous regression tests inspired by KaTeX and texmath to ensure edge cases (e.g., nested roots, empty environments, infinite recursions) are perfectly handled.

# Run tests without verbose trace outputs
cargo test --no-default-features

If you need to debug a failing parser, enable the debug-trace feature in Cargo.toml to see a colorful, interactive trace of the parser execution tree.

📄 License

This project is licensed under the MIT License.

tex2math 1.0.4