Architecture - CRT Basic

Converts source text into tokens. The lexer is deliberately tolerant of what real DOS-era .bas files look like:

• Files are read as CP437 (IBM437) with CRLF line endings — the charset is applied at file-read time in Main.
• Both newlines and : are statement separators (SEP tokens).
• ' comments and word-boundary-matched REM comments are dropped.
• Numbers: decimal with optional fraction and E=/=D exponents (1.5e3, 2D+10), hex &H…, octal &O…, and trailing type suffixes (1024&, 1.5#, 2!).
• Identifiers may carry the BASIC type suffixes % & ! # $ and may contain . and _; CP437 high characters pass through in strings and identifiers.
• A _ as the last non-blank character of a line joins physical lines into one logical statement (line continuation).

Keywords are not special at this stage: they are emitted as plain identifiers and the parser matches them by text, case-insensitively. This keeps the lexer small and makes the grammar easy to extend.

A hand-written recursive-descent parser builds the AST. Every node is an immutable record (sealed Ast.Stmt / Ast.Expr interfaces) that carries the 1-based source line, so runtime errors can quote the failing source line.

Statements that are not (yet) supported throw a ParseException naming the statement and the line. This is a feature: when a new vintage program fails to load, the error message is the work item.

Expression parsing follows the usual BASIC precedence (weakest to strongest): OR, AND, NOT, comparison (= = <> < <= > >= ), addition, multiplication ( * / \ MOD ), unary minus, power (=^), primaries.

Executes the AST directly (tree-walking). This is the interim execution engine: the target architecture compiles the AST to a compact stack-based bytecode and runs it on a small VM. The tree-walker exists so that whole programs run today and the verification workflow applies at program level; lexer, parser and AST carry over to the bytecode world unchanged.

The interpreter is where BASIC semantics live: float32 narrowing on store, type suffixes, true = -1, classic number formatting in PRINT, by-reference SUB parameters, module-wide DATA, the 24-bit RND generator. All of that is documented on the Interpreter semantics page.

A virtual VGA card: indexed-color framebuffer with multiple video pages, a text console that blits CP437 glyphs into the pixel buffer, mode table for SCREEN 0–13, default palettes, drawing primitives (PSET, LINE, CIRCLE, PAINT, GET=/=PUT) and the DAC palette ports reachable through OUT. Everything the program can see is recoverable: PNG screenshots of the visual page, or the raw indexed pixels of every page. Full details: Video subsystem.

KeyboardQueue is a thread-safe blocking queue of key presses: a KeyEvent VK code plus the typed character where one exists. Any driver pushes keys in — the Swing window, a JUnit test, an agent script — and the program consumes them through INKEY$ / INPUT$. The mapping from modern key codes to the BASIC byte sequences (printable character, or CHR$(0) + scancode for extended keys) happens at consumption time inside the interpreter.

SoundQueue models the timing of SOUND without producing audio: durations are in PC timer ticks (18.2 per second), the note queue is one note deep, and the next SOUND blocks until the previous note finishes. This preserves two classic idioms — SOUND 0, n as a delay and a single short SOUND per loop iteration as a frame-rate limiter — which is what game programs actually depend on.

SwingFrontend is deliberately dumb: it paints the visual page of the VgaDevice into a window (nearest-neighbor scaling, ~30 fps repaint timer) and pushes key presses into the KeyboardQueue. It owns no emulation state. Headless operation simply skips this class.

SCREEN 13 programs sit in tight pixel loops. A compact stack-based bytecode keeps interpretation overhead low and gives a natural "execute N instructions" granularity for deterministic stepping. The tree-walking interpreter is a deliberate interim: it made whole programs runnable (and verifiable) from day one. When the compiler and VM land, only interp is replaced.

The interpreter exposes the executed-statement counter, variable values from the global scope, and the raw framebuffer. An agent can therefore assert on program state — "after 1000 statements, score% must be 3 and pixel (10,10) must be color 4" — instead of guessing from prose output.

Unsupported statements raise errors that name the statement and the source line. Silent misinterpretation would poison debugging and verification: a wrong behavior must mean a wrong implementation, never a skipped feature.

Because frontends share VgaDevice and KeyboardQueue, there is no "headless build" and no behavioral drift between interactive and automated runs. The --headless flag only skips window creation and input blocking.