Parse -> AST -> Evaluate -> Workbook

Formualizer computes results as a staged pipeline:

1. Parse formula text into tokens.
2. Build an Abstract Syntax Tree (AST).
3. Evaluate AST nodes against context.
4. Persist values and dependencies in workbook state.

Why this model matters

• Each stage has clear responsibilities and test boundaries.
• Errors can be surfaced early (parse) or late (evaluation) with better diagnostics.
• The workbook remains the source of truth for cached values and recomputation.

Minimal example

Input formula: =SUM(A1:A3)
Parse: tokens [=, SUM, (, A1:A3, )]
AST: Call(SUM, [Range(A1:A3)])
Evaluate: Number(42)
Workbook: cell B1 stores value 42 and dependency edge B1 -> A1:A3

Common debugging checkpoints

• If parse fails, inspect tokenizer and parser diagnostics first.
• If parse succeeds but value is wrong, inspect AST shape before evaluator logic.
• If one cell updates but dependents do not, inspect workbook dependency bookkeeping.

Related

• Dependency Graph and Recalculation
• Values, Coercion, and Errors
• Workbook Edits and Batching

Real AST example

For =IF(A1>10, A1*2, 0):

{
  "type": "function",
  "name": "IF",
  "args": [
    {
      "type": "binaryOp",
      "op": ">",
      "left": { "type": "reference", "reference": { "rowStart": 1, "colStart": 1, "rowEnd": 1, "colEnd": 1 } },
      "right": { "type": "number", "value": 10 }
    },
    {
      "type": "binaryOp",
      "op": "*",
      "left": { "type": "reference", "reference": { "rowStart": 1, "colStart": 1, "rowEnd": 1, "colEnd": 1 } },
      "right": { "type": "number", "value": 2 }
    },
    { "type": "number", "value": 0 }
  ]
}

Context propagation during evaluation

Each evaluation call receives an immutable context containing the workbook state, current cell coordinates, and configuration (date system, volatile level, etc.). Functions read from context but never mutate it directly — mutations flow back through the workbook's value store after evaluation completes.