basic — Luau Binding

The require("basic") API: read and edit the AntBASIC program, run it, inspect its variables, save/load in either form, and spawn parallel BASIC contexts. Every function here is [antos] — the whole library is an AntOS addition with no standard-Lua equivalent.

Status: design. Not built yet. Signatures below are the intended surface, settled against the AntBASIC model; expect refinement during implementation. The library reference / native core is on antos_basic.

local basic = require("basic")

All calls act on the global main space unless given a context handle (see Contexts). All are [antos].

Program store

The tokenised line list — what LIST, RENUMBER, DELETE and an editor work over. Luau sees text by default; raw tokens are available via tokens.

-- renumber.lua  (renumber [start] [step])   — pure script over the library
local basic = require("basic")
local a, done = os.arguments{ name = "renumber",
    { "+Start", type = "number", default = 10 },
    { "+Step",  type = "number", default = 10 } }
if done then return end

local snapshot = {}                       -- read old lines first
for _, l in basic.lines() do snapshot[#snapshot+1] = l end

basic.clear()
local n = a.start
for _, l in ipairs(snapshot) do
    basic.insert(n, l.text)               -- (a real renumber also fixes GOTO/GOSUB targets)
    n += a.step
end

Renumbering that rewrites GOTO/GOSUB/THEN line targets is the script's job, not the engine's — walk basic.tokens(line) to find line-number references. This is exactly the kind of policy AntBASIC keeps out of the core.

A one-line style change turns the same iterator into a cruncher — writing the most compact .bas the program can be typed as (crunched listing), a nice demonstration of the "tight" rendering:

-- crunch.lua   (crunch <file.bas>)   — save the program in its shortest typed form
local basic = require("basic")
local a, done = os.arguments{ name = "crunch", { "*File", required = true } }
if done then return end

local f = io.open(a.file, "w")
for _, l in basic.lines("tight") do          -- shortest abbreviations, spaces dropped
    f:write(`{l.line} {l.text}\n`)
end
f:close()
-- re-tokenises to the identical program; the stored tokens were never touched

Validating a line

basic.check(text) parses a line the way the tokeniser does but stores nothing, so the console's entry handler, an editor, a linter, or a paste-importer all validate through one path (see AntBASIC → errors caught at entry).

It returns a three-way status, which is what lets live syntax colouring stay calm rather than flashing red on every half-typed line:

local status, err = basic.check(line)
if status == "invalid" then
    -- err = { col = 12, message = "unterminated string", line = <n>? }
    print(`? {err.message} at column {err.col}`)   -- reason + place the cursor at err.col
elseif status == "incomplete" then
    -- unfinished but not yet wrong (open string, half-typed statement) — render pending, not red
end

col is a character column (1-based) — exactly what positions the cursor on the offending character, and the same column where live colouring turns red. err.line is present only when the text carried its own line number (a program line, or a line from a bulk load). The check is line-local: it catches lexical and single-statement errors, not cross-line ones like NEXT without FOR, which surface at RUN.

Syntax spans

basic.spans(text) returns the colour projection of a line — a list of { col, len, class } spans (1-based col) — so one call feeds both LIST colouring and the live per-keystroke editor. class is "keyword", "variable", "string", "number", "comment", "operator", "label", … — or "error" for the trailing span from the first un-parseable column to end of line when the line is "invalid". See AntBASIC → syntax colouring.

-- colour one line: the editor maps class -> theme colour and applies terminal attributes
for _, sp in basic.spans(line) do
    term.colour(theme[sp.class] or theme.default)
    term.write(line:sub(sp.col, sp.col + sp.len - 1))
end

The engine emits spans; the terminal applies the attributes, and the class→colour map is a Settings theme — so colouring turns off cleanly on a mono console with the listing still readable.

Keyword help

The grammar entry behind each keyword is queryable, so an editor hint, a completion popup, and the HELP command all read the one source the checker validates against.

-- help.lua   (help [name])   — the HELP command, over keywords and commands
local basic = require("basic")
local a, done = os.arguments{ name = "help", { "Name" } }
if done then return end
if a.name then
    local h = basic.help(a.name)
    if h then print(`{h.template}   {h.brief}   ({h.abbrev})`)
    else print(`? no help for {a.name}`) end
else
    for k in basic.keywords() do print(k.name) end       -- commands listed too
end

Because basic.help renders the same grammar basic.check validates against, the help can never drift from what the interpreter accepts.

Execution

-- run.lua
local basic = require("basic")
local ok, err = basic.run()
if not ok then print(`? {err}`) end

Variables

Inspect and poke the running / last-run environment — the basis of a vars command or a debugger.

-- let a Luau script read a BASIC result
basic.eval("LET RESULT = 6 * 7")
print(basic.get_var("result"))            --> 42

Storage — SAVE / CSAVE / LOAD

Both forms round-trip through DBFS and are auto-catalogued; see AntBASIC → storage.

-- save.lua / csave.lua / load.lua are three-line wrappers:
local basic = require("basic")
local a, done = os.arguments{ name = "save", { "*File", required = true } }
if done then return end
local ok, err = basic.save(a.file)
if not ok then print(`? {err}`) end

Building executables

Export an assembly-only program (nothing but [ ] / { } blocks) as a standalone native executable. See AntBASIC → building executables.

-- build.lua   (build <file>)   — target inferred from the extension
local basic = require("basic")
local a, done = os.arguments{ name = "build", { "*File", required = true } }
if done then return end
local ok, err = basic.build(a.file)
if not ok then print(`? {err}`) end

Workspace and versioning

-- the banner line, composed exactly as the console does it
local basic = require("basic")
local function human(n)
    if n >= 2^30 then return `{string.format("%.2f", n/2^30)} GB`
    elseif n >= 2^20 then return `{string.format("%.2f", n/2^20)} MB`
    elseif n >= 2^10 then return `{string.format("%.2f", n/2^10)} KB`
    else return `{n} bytes` end
end
print(`AntBASIC v{basic.version()}   {human(basic.free())} free`)

Contexts

One global main space, plus parallel contexts on worker threads — isolated program store and variables each. See AntBASIC → contexts.

Every store / execution / variable call above accepts an optional context handle as its last argument, defaulting to main:

local job = basic.spawn("worker.bas")     -- runs in parallel
print(basic.state(job))                   -- inspect the spawned context
for _, l in basic.lines(job) do print(l.line, l.text) end

So list, renumber, a monitor or a debugger all work against a spawned context by passing its handle — the same script, the same verbs.

Tracing and debugging

The primitives a trace or debugger tool is built from — each takes an optional context handle, defaulting to the main space.

Because the tool sits in one context and steps another, a breakpoint or a runaway loop pauses the target, never the debugger. For the machine code inside a program, drop to the soft core's own hardware debug (see the EE CPU doc — one RV64 core on either machine).

Where to go next

• The engine, dispatch, banner, storage and versioning model → AntBASIC
• The library reference / native core → antos_basic
• Writing an AntOS command → Script Developer Quickstart
• Back to the AntOS libraries hub