Goal: recover an evaluation structure from text
Computing 2 + 3 * 4 strictly from left to right produces 20, whereas JavaScript gives multiplication stronger binding and produces 14. A parser can encode that decision by placing the multiplication subtree on the right of the addition node. An evaluator then follows the tree instead of inventing a special case for the original string. The goal of this lesson is to explain which source range belongs to each expression and which operation is a child of another before looking at the numerical output. Read the existing lexing and parsing guide first, and make sure you can identify a tree root, a child, and a leaf.
The interactive JavaScript runtime is a declared teaching subset, not a complete JavaScript engine. Begin with arithmetic before adding bindings, conditionals, and functions. That makes whitespace, operators, parentheses, and the end of input separately testable boundaries. In the model, connect the highlighted source position to the current syntax-tree node. An unsupported character or construct produces a located error; it is never passed to the host JavaScript engine as a fallback. A successful result therefore means that the supported model completed its work, not that an unrelated execution mechanism happened to accept the input.
Keep the original range on every token
Lexing classifies characters into numbers, names, operators, and delimiters. For 12 + value, the first token is a two-character number, followed by an operator and an identifier. Keep start and end offsets alongside token values. They let an error point to the original text when a closing parenthesis is missing. Skipping whitespace must not renumber source positions. Quoted strings also require state: a plus sign inside quotes is string content rather than an addition token. Treating the whole input as a sequence of independently split symbols loses these distinctions.
The minus sign can be a unary operator or a binary operator. It introduces a negative expression in -2 * 3 but separates operands in 7 - 2. Emitting a minus token and letting the parser choose its role keeps lexical classification separate from expression structure. If comments, escapes, or Unicode identifiers are added later, add tests for their source ranges as well. Silently replacing difficult text with whitespace can turn an invalid program into a different accepted one. A teaching implementation should make its accepted language inspectable rather than depending on accidental string transformations.
Represent precedence through parser calls
A sum reads products, and a product reads primary expressions. After sum reads its left product and encounters +, it asks for another complete product. That call consumes 3 * 4 and returns one subtree, giving 2 + (3 * 4). Operators of equal precedence can be collected by updating the left subtree in a loop when they are left associative. For subtraction, 8 - 3 - 1 must not accidentally become 8 - (3 - 1). Test the tree structure as well as the final value so that errors are not concealed by an input whose operands happen to give the same answer.
| Stage | Consumed range | Resulting structure |
|---|---|---|
| Primary | 2 | Number(2) |
| Right product | 3 * 4 | Multiply(Number(3), Number(4)) |
| Whole sum | 2 + 3 * 4 | Add(Number(2), Multiply(...)) |
Parentheses change structure, not numerical magic
For (2 + 3) * 4, the primary-expression parser sees an opening parenthesis, parses the inner expression, and checks the closing delimiter. The returned addition becomes the left child of multiplication, yielding 20. A separate numerical operation for parentheses is unnecessary, although retaining their source range helps the interface explain the input. Compare expressions that differ only in parenthesis placement. A similar number of tokens can produce a different root node, and that structural difference is enough to explain the changed result.
Distinguish useful boundaries: a single number is a valid expression; whitespace alone contains no expression; a lone closing parenthesis has no matching opener. The input 2 + fails while reading its right operand. The input 2 3 can produce an initial node but leaves a token unconsumed. Parsing part of a program must never count as accepting the complete input. An error belongs to the current trial, and a previous successful value must not remain labeled as the current output. Re-running a valid input after an error should recreate the same tree as a fresh run.
Implementation: collect products before sums
This independent reference program accepts already tokenized numbers, +, and * only. It illustrates the parser-call relationship rather than reproducing every feature of the interactive runtime. Notice the shared cursor pos and the final check that every token was consumed. The assertions check both the output and the shape: the root is addition and its right child is multiplication. Running the program prints 14. Changing the displayed formatting of a tree must not alter the evaluator’s answer.
When extending this parser with subtraction or parentheses, preserve more than the original example. Test a single value, repeated operators, missing delimiters, and trailing input. Number conversion is checked so that an invalid operand cannot survive as an ordinary node containing NaN. A richer parser can return an error category and range instead of throwing, but it should not use zero or an empty string to stand for failure: both can be legitimate values in the surrounding language. This is a contract between the parser and its caller, not merely a choice of error-message wording.
const tokens = ['2', '+', '3', '*', '4'];
let pos = 0;
function primary() {
const value = Number(tokens[pos++]);
if (!Number.isFinite(value)) throw new Error('number expected');
return {type: 'Number', value};
}
function product() {
let node = primary();
while (tokens[pos] === '*') { pos++; node = {type: '*', left: node, right: primary()}; }
return node;
}
function sum() {
let node = product();
while (tokens[pos] === '+') { pos++; node = {type: '+', left: node, right: product()}; }
return node;
}
const tree = sum();
if (pos !== tokens.length) throw new Error('trailing token');
function run(n) {
if (n.type === 'Number') return n.value;
const left = run(n.left), right = run(n.right);
return n.type === '+' ? left + right : left * right;
}
console.assert(tree.type === '+' && tree.right.type === '*');
console.assert(run(tree) === 14);
console.log(run(tree));Syntactic success does not establish a runtime value
The parser may construct a tree for name + 1 without knowing whether a binding named name exists. Looking up that binding belongs to evaluation. Similarly, the structure of a call expression does not prove that its target value can be called. Putting every runtime condition into parsing would prevent the same tree from being evaluated in different environments. Keep the syntax tree, the environment mapping names to values, and the resulting output as distinct state. The next lesson uses that separation to follow one function body through different call environments and to distinguish lexical lookup from the order of calls.
Exercise: repair the structure instead of hard-coding the answer
In the JavaScript runtime, repair 2 + 3 * 4 so that it computes 20 using parentheses and the existing operands. Printing the literal 20 does not explain the original calculation. Then change the operands to 5, 2, and 6; the same grouping should compute 42. Passing both the repaired example and a different-operand regression case shows that the expression represents the intended operation rather than a single memorized answer. Explain the changed root and child relationships alongside the output.
Remove one closing parenthesis and record the point at which parsing stops. Restore valid input and compare the rebuilt tree with a fresh execution. In your notes, record the edited characters, the structural change, and the result for another operand set. Limits also belong to the contract: exceeding the model’s node count, operation budget, or call depth is an incomplete execution. A partial value obtained before that limit is not a successful solution. These checks make the model useful for reasoning about an implementation instead of merely animating an example.