Metadata-Version: 2.4
Name: asciimath2mathml
Version: 0.2.0
Summary: Convert AsciiMath strings to MathML markup
Author: asciimath2mathml contributors
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lark>=1.1.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# asciimath2mathml

Convert AsciiMath strings to MathML markup.

## Overview

`asciimath2mathml` is a zero-dependency Python library that compiles AsciiMath notation into semantically accurate MathML. It's optimized for fast, stateless, in-memory execution and works in both standard Python environments and browser-based WebAssembly contexts via Pyodide.

## Features

- **Zero runtime dependencies** - Only uses Python's standard library plus Lark parser
- **Stateless functional API** - No class instantiation required
- **WebAssembly compatible** - Runs in Pyodide without compiled extensions
- **Graceful degradation** - Falls back to escaped text on parse errors
- **Formal EBNF grammar** - Lark-based Earley parser for predictable handling
- **Comprehensive coverage** - Implements all core mathematical symbols, matrix styles, and delimiters. See [`COVERAGE_CHECKLIST.md`](./COVERAGE_CHECKLIST.md) and [`ROADMAP.md`](./ROADMAP.md) for full specification plans.

## Installation

```bash
pip install asciimath2mathml
```

Or for development:

```bash
pip install -e ".[dev]"
```

## Usage

```python
from asciimath2mathml import convert

# Inline formula
result = convert("x^2 + y^2 = z^2")
# <math xmlns="http://www.w3.org"><mrow>...</mrow></math>

# Display block (centered, larger)
result = convert("sum_(i=1)^n i^2", display_block=True)
# <math xmlns="http://www.w3.org"><mstyle displaystyle="true">...</mstyle></math>
```

## API Reference

### `convert(asciimath_string: str, display_block: bool = False) -> str`

Compiles an AsciiMath string into valid presentational MathML markup.

**Parameters:**
- `asciimath_string` (str): Raw text formula notation input string
- `display_block` (bool): If True, wraps output in `<mstyle displaystyle="true">` for block-level display

**Returns:**
- str: Validated XML/XHTML string with MathML namespace declarations

## Examples

### Basic Operations

```python
convert("x + 42")
# <math xmlns="http://www.w3.org"><mrow><mi>x</mi><mo>+</mo><mn>42</mn></mrow></math>

convert("x^2")
# <math xmlns="http://www.w3.org"><msup><mi>x</mi><mn>2</mn></msup></math>

convert("x_1")
# <math xmlns="http://www.w3.org"><msub><mi>x</mi><mn>1</mn></msub></math>
```

### Complex Expressions

```python
convert("(a + b) / (c - d)")
# <math xmlns="http://www.w3.org"><mfrac>...</mfrac></math>

convert("sqrt(x^2 + y^2)")
# <math xmlns="http://www.w3.org"><msqrt>...</msqrt></math>

convert("x_1^2 + y_1^2 = z_1^2")
# <math xmlns="http://www.w3.org"><mrow><msubsup>...</msubsup>...</mrow></math>
```

## Element Mapping

| AsciiMath | MathML Element | Description |
|-----------|----------------|-------------|
| Numbers | `<mn>` | Numeric literals |
| Identifiers | `<mi>` | Variables, function names |
| Operators | `<mo>` | Mathematical operators |
| Text in quotes | `<mtext>` | Plain text |
| `x^y` | `<msup>` | Superscript |
| `x_y` | `<msub>` | Subscript |
| `x_a^b` | `<msubsup>` | Combined sub/superscript |
| `a / b` | `<mfrac>` | Fraction |
| `sqrt(x)` | `<msqrt>` | Square root |
| `(...)` | `<mrow>` | Grouped expression |

## Development

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"   # editable install — required before running tests
```

## Testing

```bash
# Unit tests
pytest tests/ --ignore=tests/performance -v

# Performance benchmarks
pytest tests/performance/ -v
```

## Performance

The library targets sub-2.5ms conversion time per formula on standard hardware.
See [`tests/performance/`](./tests/performance/) for benchmark profiles.

## License

MIT

## Project Structure

```
asciimath2mathml/
├── src/
│   └── asciimath2mathml/
│       ├── __init__.py      # Public API
│       ├── core.py          # Compiler execution loop
│       ├── grammar.lark     # EBNF grammar definition
│       └── transformer.py   # AST to MathML transformer
└── tests/
    ├── unit/                # Unit tests
    └── performance/         # Performance benchmarks
```
