AntOS `basic` Library

The library that exposes the AntBASIC engine to Luau — the program store, tokeniser, interpreter, variable space, and parallel contexts — so the whole classic command set (RUN, LIST, RENUMBER, SAVE) can be ordinary AntOS scripts rather than baked-in built-ins.

Status: design. The engine and this library are not built yet. This page describes the native core and its responsibilities; the exact script API is on luau_basic. See AntBASIC for the language, dispatch, storage and versioning model this library serves.

This is the reference page (design + native core). Script authors want the binding page, luau_basic. For the two-layer pattern all AntOS libraries follow, see the AntOS libraries hub.

The shape of it

Like every AntOS library, basic is a native core (libantos_basic) plus a thin Luau binding. The native core is the BASIC engine: the tokeniser, the tokenised program store, the interpreter, the variable space, the workspace arena, and the context/thread machinery. The binding turns each of those into a require("basic") call.

The design inverts the usual retro arrangement. BASIC is not the top of the stack commanding the machine — it is a service the OS offers, and the experience of BASIC (the Ready. prompt behaviour, RUN, LIST, RENUMBER, SAVE/CSAVE/LOAD) is Luau on top of the library. That is what lets a user add renumber.lua or a smarter list without going near the tokeniser.

What the native core owns

Responsibility	Notes
Tokeniser / detokeniser	keywords → token bytes on entry; back to canonical source for `LIST`. Case-insensitive keywords and variables; the numeric-literal grammar, the `$`/`%` suffix-vs-prefix rule, and Atari-style `p.` abbreviations resolved by token-table order all live here (see AntBASIC)
Program store	the linked list of `(link, line#, tokens, 0)` records — the tokenised line list, ordered by line number
Interpreter	executes the token stream directly (`RUN`), plus single-statement evaluation (`eval`) for tools to call
Variable space	numeric and string variables of the running / last-run program, inspectable and settable
Workspace arena	program + variables in a bounded arena; the source of `free()` for the boot banner
Contexts + threads	the global main space, plus spawned contexts each on their own worker thread (isolated store + vars)
Token-table registry	the current table and retained older versions, keyed by version, for loading and upgrading old images. Its order is load-bearing twice over — token assignment and abbreviation precedence — so it is append-only (why)

Everything above is engine work that must be native for speed and for the direct token-stream execution model. Nothing above is policy — the policy (what RUN prints, how LIST formats, how RENUMBER steps) is deliberately left to scripts.

The program store and the main space

There is one global main space — the program at the console's Ready. prompt — and the native core holds it as the tokenised line list described above. Edits (insert, remove, clear) mutate it in place; execution walks it. This single-global model is what keeps the retro banner/Ready. experience coherent: there is the program.

Isolated contexts are the exception that makes the platform interesting: spawn allocates a separate program store, variable space and workspace, bound to a new worker thread, so a BASIC program can run another in parallel without shared state. Contexts reuse the same AntOS worker-lane task model the Luau runtime uses, so isolation and scheduling are the system's, not a bespoke BASIC mechanism. Every store/exec/inspect entry point accepts an optional context handle; omitting it means main.

Storage and versioning are engine concerns, exposed

The native core writes and reads both on-disk forms — detokenised text (save) and the tokenised image (csave) — and does the auto-detecting load. Because the tokenised image carries a token-table version and the core retains old tables, load of an old image detokenises against the table that wrote it and re-materialises it in the current form; a subsequent save/csave writes the current version, so use upgrades the file. The core also emits the token-table version as DBFS catalogue metadata on tokenised saves, which is what makes "find every stale image" an indexed fs.query rather than a crawl. The full model — including the basupgrade batch script — is in AntBASIC → versioning.

Where to go next