Parsers and evaluators in BBC BASIC II: who reads text, and how the language reaches them

Scope. This article maps the BBC BASIC II text-reading machinery — the tokeniser, the statement dispatcher, the expression evaluator and its factor-level readers, the lvalue parser, and the two string→value front doors VAL and EVAL. Every routine address is specific to this version and was read from the disassembly (which reassembles byte-identically to the ROM). It is a road-map: the deep dives on tokenising, control-flow stacks, floating point and indirection lvalues cover the individual pieces.

A recurring source of confusion about BBC BASIC — why does VAL("&FF") give 0 but EVAL("&FF") give 255? why is TOP not TO+P here but is there? why can an indirection be a procedure parameter? — dissolves once you see that BASIC II is not one parser. It is several distinct text-reading machines, each reached from the language in different places. Knowing which machine runs where is the whole game.

The machines at a glance

The rest of this article walks the three layers that most often surprise people: the evaluator ladder, the factor-level readers (where the number/hex/string/variable splits live), and the two front doors.

The expression evaluator: a precedence ladder

eval_expr (&9B1D) is the single entry point. It copies the program pointer PtrA into the working pointer PtrB and enters the lowest-precedence level. Each level evaluates a higher-precedence operand, then loops consuming its own operators — a classic recursive-descent precedence climb:

eval_factor (&ADEC) is "level 1" — the highest-precedence rung and the one that actually reads things. It handles unary -, + and NOT; a parenthesised sub-expression; the ?, !, $ and | indirection operators; string literals; and the built-in functions. Unlike the higher levels it does not read the trailing operator — its caller does. Everything below is a sub-reader dispatched from here.

The factor readers — where the splits live

This is the layer that explains the surface quirks. eval_factor looks at the first character of the atom and dispatches:

• Decimal / floating-point numbers → parse_number (&A07B). Reads digits, a . and an E exponent, choosing integer or real (a point or exponent forces real). It is decimal only — there is no & branch in it, and a non-digit first character yields 0.
• Hex constants → factor_hex (&AE6D), dispatched on a leading &. Folds 0-9 and uppercase A-F into a 32-bit cell as a bit pattern, with no overflow check (a 9th digit drops the top nibble; &FFFFFFFF = −1) and the sole error Bad HEX when no hex digit follows. Lowercase a-f ends the scan.
• String literals ("...") → read_string_literal (&ADAD).
• Variables, array elements and indirection as values → the scanner shared with the lvalue path (parse_var_ref (&95C9)).
• Built-in functions → the per-token fn_* handlers, reached through the action-address table (action_table_lo (&836D)) by token value. This is how SIN, LEN, VAL, EVAL, and the TO-token's fn_to (&AEDC) (which reads TOP) are dispatched.

The decisive fact: the decimal reader and the hex reader are different routines, and & is reachable only through eval_factor. parse_number never sees a &. That single split is the root of the VAL/EVAL difference below.

The lvalue parser: one routine, four exposures

Assignment targets are read by a separate machine, parse_lvalue (&9582) (via parse_var_ref (&95C9)). It returns a storage address plus a type byte, and — crucially — it is shared verbatim by four language constructs: the left of LET, the FOR control variable, each LOCAL, and each PROC/FN formal parameter. Because they all call the same routine they accept the same grammar, which is why a ?/!/$ indirection or an array element is a legal FOR variable, LOCAL, and formal parameter — see indirection lvalues as parameters.

Two string→value front doors: VAL and EVAL

Both turn a string into a value, but through completely different machines:

• VAL (fn_val (&AC2F)) runs the decimal reader on the raw string: ascii_to_number (&AC34) handles an optional leading sign, then defers to parse_number (&A07B). No tokenising, no operators, no &. It reads a number from the start of the string and stops at the first non-numeric character.
• EVAL (fn_eval (&ABE9)) tokenises the string and runs the full evaluator on it: it copies the argument to the stack, appends a CR, crunches it in place (in mid-statement state, so PTR/TIME etc. tokenise as functions), and calls eval_expr (&9B1D). So it accepts everything an expression can contain — & hex, E exponents, operators, parentheses, functions and in-scope variables.

That is the entire reason for the classic contrast:

VAL is "read a literal"; EVAL is "be the interpreter". A compiler matching the ROM must model them as two readers, not one with a flag.

Surface consequences, and where they're documented

Most of BASIC II's "vexing parse" folklore is just the machine boundaries showing through:

• VAL vs EVAL on hex — the two-readers split above.
• TOP is not a token — the crunch emits TO+'P'; the pseudo-variable is resolved at factor time by fn_to (&AEDC), only when the TO token is in operand position immediately followed by a bare P. See tokeniser §1.7.
• Indirection as a parameter — parse_lvalue being shared by the PROC/FN binder. See indirection lvalues.
• & is uppercase-only and wraps at 32 bits — a property of factor_hex, not of "numbers" in general.

Appendix: routine cross-reference