Math Expression Parser

A math expression parser and evaluator. Takes a string like "2 + 3 * (4 - 1)" and returns the numeric result (11).

When to use this skill

When you need to evaluate mathematical expressions from strings with correct operator precedence, parentheses, and error handling — without adding a dependency.

Node Graph

token-types ─────────────┬──→ tokenizer ──┐
                         │                │
ast-types ──┬────────────┤──→ parser ─────┤──→ evaluate (root: public API)
            │            │                │
            └────────────┴──→ evaluator ──┘

Nodes

Subset Extraction

You can translate any subset by following the depends-on edges:

• Just the evaluator (AST in, number out): ast-types + evaluator
• Parser only (tokens in, AST out): token-types + ast-types + parser
• Full pipeline: all 6 nodes

Supported Operations

Important: Unary minus binds tighter than exponentiation. -2 ** 2 = (-2)² = 4, NOT -(2²) = -4.

$ARGUMENTS

Format: <nodes> [--lang <language>]

• nodes: One or more node names from the table above, or all for the full pipeline. When specifying individual nodes, all transitive dependencies are included automatically.
• --lang: Target language for the translation. Defaults to typescript if omitted. Supported values include python, rust, go, and others for which translation hints exist in nodes/<name>/to-<lang>.md.

Examples:

• evaluate --lang python — full pipeline translated to Python
• evaluator --lang rust — evaluator + ast-types translated to Rust
• tokenizer parser --lang go — tokenizer + parser + leaf dependencies translated to Go
• all — all 6 nodes in TypeScript (identity, useful for validation)

How to Use This Skill

1. Parse $ARGUMENTS to determine which nodes and target language are requested
2. Read this file for overview, the node graph, and subset extraction rules
3. For each node you need (respecting dependency order), read nodes/<name>/spec.md for behavior and test vectors
4. Read nodes/<name>/to-<lang>.md for language-specific translation guidance
5. Generate implementation + tests for each node
6. If the spec is ambiguous or insufficient, consult the TypeScript reference at reference/src/<name>.ts for the canonical implementation

Generated Code Documentation

Every public function, class, type, and interface in generated code must have idiomatic doc comments in the target language's standard format:

Doc comments should describe what the function does, its parameters, return value, and error conditions. Derive content from the node spec — do not invent behavior not in the spec.

Each generated file must include a provenance header as the first comment, in the file's idiomatic comment style:

Generated by {agent} using {model}
From special:math-expression-parser (https://github.com/caryden/special)
Node: {node-name}

Replace {agent}, {model}, and {node-name} with actual values. The provenance trace makes generated code traceable back to the skill and model that produced it.

The per-node specs are self-contained — you can build nodes in parallel as long as their dependencies are satisfied.

Reference Implementation

The TypeScript reference lives at reference/src/<name>.ts with corresponding tests at reference/src/<name>.test.ts. The reference has 100% line and function coverage — every code path is tested and verified. Tests serve as the behavioral contract: if the spec and translation hints leave something ambiguous, the reference + its tests are the source of truth.

To run the reference tests:

cd reference && bun test --coverage

Error Handling

The parser and evaluator define several error cases that all translations must handle:

All errors should include enough context (position, character, or operator) for the caller to produce a useful diagnostic message. See individual node specs for exact error semantics and test vectors.