2026-07-31 21:50:50 -04:00
# 11. Verb reference
Every statement, alphabetically. This list is generated from the interpreter's own
dispatch table, so it cannot drift out of step with what the program actually accepts.
A verb marked **Refused ** parses and then reports why it cannot run — see Chapter 13
for the reasoning in each case.
| Verb | Form | What it does |
|---|---|---|
| `APPEND` | `APPEND n, "name"` | Open a file on channel `n` for writing at its end. |
| `AUTO` | `AUTO n` | Number lines automatically in steps of `n` . `AUTO 0` turns it off. |
| `BACKUP` | `BACKUP` | **Refused. ** Duplicates one disk onto another; there are no disks. |
| `BEGIN` | `IF c THEN BEGIN` | Start a block that runs to `BEND` , so an `IF` can span lines. |
| `BEND` | `BEND` | End a `BEGIN` block. |
| `BLOAD` | `BLOAD "name", addr, len` | Read a file into memory. The length is required. |
| `BOOT` | `BOOT` | **Refused. ** Loads and runs a boot sector; there is none. |
| `BOX` | `BOX src, x1, y1, x2, y2 [,angle]` | Outline a rectangle, optionally rotated. |
| `BSAVE` | `BSAVE "name", from, to` | Write a range of memory to a file. |
| `CATALOG` | `CATALOG` | **Refused. ** The other name for `DIRECTORY` . |
Land a character written past a short row's terminator
A grid row is a NUL-terminated string, and `putchar_at()` wrote the character,
advanced and terminated -- so `CHAR 1, 40, 1, "#"` on an otherwise empty row
stored the `#` at column 40 with `text[1][0]` still `'\0'`, and the render loop,
which stops at the terminator, drew nothing at all.
The silent nothing is the trap. The write succeeded, the cursor moved, the
stdout mirror showed the character, and only the window stayed blank -- so the
program looked right everywhere except where it mattered. The documented
truncation on the way *back* is fine and is unaffected.
`putchar_at()` now fills the gap with spaces before storing.
**Padded there rather than in `sink_moveto()`**, which TODO.md proposed: this way
`moveto` stays read-only -- the objection that entry raised against its own
suggestion -- and a row is only ever padded when a character actually arrives.
The pad fills from the terminator rather than replacing it. The buffer is not
cleared between rows, so replacing only the terminator would expose the tail of
whatever longer row used to be there: writing "ABCDEFGHIJ", truncating it to
"ABCX", then writing at column 7 must give "ABCX Z" and not "ABCX FGZ".
tests/akgl_backends.c asserts all three cases, and the middle one keeps the
truncation pinned.
TODO.md section 6 item 32, struck.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-02 00:13:42 -04:00
| `CHAR` | `CHAR col, x, y, "text"` | Put text at a character cell. Needs a sink with a cursor. Terminates the row where it stops, so it erases whatever followed. |
2026-07-31 21:50:50 -04:00
| `CIRCLE` | `CIRCLE src, x, y, rx, ry [,...]` | Draw an ellipse, arc or polygon. |
| `CLR` | `CLR` | Drop every variable and function, keeping the program. |
| `COLLECT` | `COLLECT` | **Refused. ** Validates a disk's block allocation map. |
Collide sprites with rectangles that are not sprites
`SOLID id, x1, y1, x2, y2` registers static collision geometry; `SOLID id`
retires one and a bare `SOLID` retires them all, the way `TRAP`, `COLLISION` and
`DCLOSE` all read absence. `COLLISION 2` and `BUMP(2)` stop being refused and
mean *sprite met static geometry*.
**This is the thing eight sprite slots made impossible.** A wall of bricks wants
sixty, so until now a program could only collide with one by doing the
arithmetic itself against its own array -- which is exactly what both breakout
listings do, at about two hundred lines between them. A rectangle costs no sprite
slot.
The id is the **program's own number**, 1 to 64, not a minted handle. That is the
whole trick for "which brick did I hit": the id comes back out again, so a wall
built as `SOLID I#, ...` maps onto `B#(I#)` with no lookup, and retiring a broken
brick is `SOLID I#`.
`COLLISION 2` was refused with "sprite-to-background collision needs the screen
read back every frame", which was true of the question a C128 asks -- a sprite
against the bitmap's set pixels. `SOLID` gives this interpreter a background made
of rectangles instead, which is the same question in a form it can answer. Same
move `SPRSAV` made when it learned to take an image path.
`AKBASIC_INTERRUPT_BACKGROUND` has been sitting in the interrupt table commented
"COLLISION 2 -- sprite met background; refused" the whole time. Its accumulator is
separate, so a sprite hitting a wall never sets a bit in `BUMP(1)`.
**There is no `akgl_CollisionWorld` here, and that is deliberate.** libakgl's
uniform grid keeps its cell heads, cell size and origin in file-scope statics, so
it is one index per process -- and `akgl_collision_world_init()` ends in a
`reset()` that memsets those heads *and* calls
`akgl_heap_init_collision_cells()`. An interpreter embedded in a game with its
own collision world would have destroyed every registration that game had made,
on the first `SOLID` a script ran. So the geometry is indexed by an ordinary
array here and pairs go straight to `akgl_collision_test()`, which needs no
world. At sixty-four rectangles that is the right answer anyway; libakgl's own
numbers put a naive sweep at 0.7% of a frame at sixty-four objects.
**The scan now short-circuits when nothing has moved**, and that is what makes
any of it affordable. Its inputs are the sprites' boxes, which slots are
collidable, and the static geometry; if none changed the answer cannot have. A
frame runs one full scan and 255 cached ones. Eight sprites against sixty-four
rectangles is five hundred and twelve tests -- fine once a frame, ruinous 256
times.
The benchmark was rewritten to say which path it is timing, because with the
cache in place a loop that only calls the scan measures the short circuit and
nothing else. Breakout now costs 590.6 ns for its one full scan plus 255 cached
at 40.0, which is 10.8 us against a 1.19 ms frame -- **0.91%, less than the 2.0%
it cost before any of this work**, with static geometry and contacts added on
top.
`NEW` retires the rectangles, where it cannot undefine a sprite pattern: there
*is* an entry point for this one, so leaving them would be a choice, and the
wrong one -- a rectangle is invisible, so one left behind by a deleted program is
an unexplainable collision in the next. `CLR` leaves them alone.
`tests/sprite_verbs.c` gains the whole second path against the mock and its
`COLLISION 2` case is rewritten: it pinned the refusal, and now pins that type 2
arms its own handler without disturbing type 1's. `tests/akgl_backends.c` gains
the end-to-end version, including a full sixty-four-rectangle wall so the proxy
budget is exercised at its ceiling and the pool has to come back intact, and the
sixty-fifth refused by name.
A bare `SOLID` needed `akbasic_parse_optional_arglist` rather than
`akbasic_parse_arglist`, which `DCLOSE` already uses for the same shape.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-02 10:25:35 -04:00
| `COLLISION` | `COLLISION type [,target]` | Call a subroutine when sprites collide. No target disarms it. |
2026-07-31 21:50:50 -04:00
| `COLOR` | `COLOR src, index` | Bind a colour source to a palette index, 1 to 16. |
| `CONCAT` | `CONCAT "a", "b"` | Append file `a` to file `b` . |
| `CONT` | `CONT` | Resume a program stopped by `STOP` . |
| `COPY` | `COPY "a", "b"` | Copy file `a` to file `b` . |
| `DATA` | `DATA v [, ...]` | Declare values for `READ` . Collected before the program runs. |
| `DCLEAR` | `DCLEAR` | Close every open channel. The half of a drive reset that means something. |
| `DCLOSE` | `DCLOSE [n]` | Close channel `n` , or every channel. |
| `DEF` | `DEF NAME(args) = expr` | Define a function. Multi-line definitions end in `RETURN` . |
| `DELETE` | `DELETE [n][-n]` | Delete lines, with the same range forms as `LIST` . |
Give BASIC menus, dialogs and HUD labels over libakgl's UI helpers
Group K, and the first verbs to reach the akgl_ui subsystem 0.9.0 brought
in: MENU and GETMENU and RMENU, DIALOG, HUD and UISTYLE. A program that
wanted a title screen had to draw one out of CHAR and GETKEY, which is
what both breakout tutorials make a reader do.
The interesting part is the impedance mismatch. libakgl's UI is immediate
mode -- widgets are re-declared inside a frame bracket every frame and
clay borrows their text until the bracket closes -- and a BASIC program
says MENU 1, "START" on line 100 and expects it up on line 900, several
hundred frames later. So src/ui_akgl.c is retained on this side and
immediate on that one: the record's entry points are setters that copy
into akbasic_AkglUi, and akbasic_ui_akgl_render() replays the whole set
once a frame from the host's pump. No BASIC string, which lives in the
per-line value pool, is ever what clay is handed.
The shapes are borrowed rather than invented. MENU retires the way SOLID
does -- no entries retires one, no arguments retire them all. GETMENU
holds the step loop the way GETKEY does, so parking is not blocking: the
step still returns, the host keeps its frame rate, and the sprite, audio
and collision services keep running underneath because they run before
the blocking checks. RMENU(n,1) reads and clears the way BUMP() does.
Withdrawing the device or retiring the menu releases a holding GETMENU
with 0 rather than wedging the script, which is akbasic_input_service()'s
rule for a withdrawn keyboard.
One thing a program has to know, and docs/19-user-interface.md says it
twice: a menu that is up owns the cursor keys and Return. It has to, and
retiring it gives them back -- forget the MENU n before an INPUT and the
INPUT never sees the Return that ends it.
akbasic_runtime_set_ui() is its own function rather than a fifth argument
to akbasic_runtime_set_devices(), whose signature has twenty-eight call
sites in tests and documentation that are about something else.
deps/libakgl is not touched. akgl_UiAnchor has the four corners and dead
centre, so HUD offers exactly those five; TODO.md records what a
top-centre and bottom-centre would cost upstream, along with the three
other things this deliberately leaves out. No new error code either --
DEVICE, BOUNDS, SYNTAX and TYPE cover the group, and 520 stays free.
tools/screenshot.c had to learn that "needs a font" and "draws the text
grid" are two questions. They were one, and a UI figure came out black:
the text layer owns every pixel of the rows it covers and painted over
the widgets. The new ui=1 fence attribute asks for the first without the
second; MAINTENANCE.md documents it.
112/112 in both configurations, 112/112 under ASan and UBSan, coverage
94.1% against the 90% gate with src/runtime_ui.c at 99% of lines and
100% of functions, doxygen clean, and the four new figures byte-identical
on a re-render. TODO.md section 8's gate table was stale on several
counts besides these and is refreshed with measured numbers.
Co-Authored-By: Tachikoma (Claude Code Opus 5 1M) <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-02 18:37:10 -04:00
| `DIALOG` | `DIALOG ["text"]` | Show a text panel across the bottom of the screen. No argument takes it down. See Chapter 19. |
2026-07-31 21:50:50 -04:00
| `DIM` | `DIM A#(n [,...])` | Make an array. Subscripts start at zero; `n` is the count. |
Document structures: a chapter, the architecture, and the differences
docs/16-structures.md is the feature: records, nesting, copy-on-assign, strict
pointers, lists, what is checked and what is not, and how a host shares its own
C structs. Every example in it is executed by docs_examples and byte-compared,
including the refusals -- so a message that changes fails the suite rather than
quietly making the chapter wrong.
The chapter makes one contrast explicitly, because it is the question a reader
will actually have: a misspelled *field* is refused and a misspelled *variable*
still prints zero. The rule underneath is that what the program declared gets
checked and what it did not gets shrugged at -- a variable's name is never
declared, a TYPE's field list is. Structures end up the strictest thing in the
language, not from a higher standard but because they are the only named thing
whose valid spellings are written down.
Chapter 14 gains the layout: an instance is a contiguous run of value slots with
a diagram of where the fields sit, the three-pass prescan and why each pass
exists, why the copy cannot live in akbasic_value_clone(), and why the render
depth bound is four rather than eight. Chapter 3 gains the @ suffix, chapter 13
records that all of this is an addition BASIC 7.0 has nothing like, and the verb
reference gains TYPE, POINT and DIM ... AS.
MAINTENANCE.md gains the two rules that are on a maintainer rather than on a
test: a structure copy must not go through clone, and a field chain gets its own
leaf field. TODO.md section 5 records what was invented and the three limits
that are ours, and section 8 records the two defects the work exposed.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-01 12:03:02 -04:00
| `DIM` … `AS` | `DIM S@ AS T` , `DIM P@ AS PTR TO T` | Make a structure, or a strict pointer to one. See Chapter 16. |
Take libakerror 2.0.2, libakstdlib and libakgl 0.9.0
Bumps all three ak* submodules to their current main, applies what their
upgrade notes require, and retires the two workarounds they make obsolete.
libakerror 2.0.1 -> 2.0.2 (63 commits). Two of its fixes were this
repository's own filed issues, and both workarounds are gone:
- It namespaces its embedded `coverage` target now, the same
CMAKE_SOURCE_DIR test it already applied to `mutation` (its issue #15).
The add_custom_target() shadow that renamed it on the way past could
only ever fire on a name the dependency has stopped using, so it is
deleted rather than left as dead code.
- It installs akerrorConfigVersion.cmake at SameMajorVersion (its issue
#16). MAINTENANCE.md said to add a `1.0` floor to our find_dependency
calls when this landed; the floor is now `2.0`, and we have no
find_dependency calls to add it to, so the paragraph says that instead
of an instruction nobody can follow.
Its IGNORE context also changed shape: `__akerr_last_ignored` was an extern
pointer, and is now a per-translation-unit `static akerr_last_ignored` holding
a copy, so the pool slot can be released. Nothing here referenced the symbol,
but it costs us 1.35 MiB of thread-local storage -- 38 TUs x 37,296 bytes,
measured as the entire TLS segment of build/basic, where 2.0.1 produced no TLS
segment at all -- plus 84 -Wunused-variable warnings. Filed upstream as
libakerror issue #37 and recorded in MAINTENANCE.md rather than patched here,
because patching a submodule forks it.
libakstdlib gains directory and file-metadata wrappers with no version bump.
aksl_snprintf keeps its `int *count` -- an intermediate commit removed it and
the merge put it back -- but now reports the required length on truncation
rather than 0. Every call site here reads it only after a successful return,
so nothing moved.
The directory wrappers close the gap DIRECTORY was refused for (libakstdlib
issue #10). The verb is still unwritten, so it still refuses, but it no longer
blames a wrapper that exists: the message is "DIRECTORY is not implemented
yet" and tests/disk_verbs.c asserts both that it says so and that it does not
name libakstdlib. What writing it would need is akbasic issue #55.
libakgl moves to the current main at 0.9.0. It registers libccd and tg as
submodules, so a tree that only ran `git submodule update --init --recursive`
before the bump needs it again or the configure fails on a missing
libccd/src/ccd/config.h.cmake.in.
Verified: 114/114 default, 116/116 under -DAKBASIC_WITH_AKGL=ON, docs_examples
green in both. libakerror's UPGRADING.md documents a 2.0.3 that project()
never stamped, so the version tables read 2.0.2 -- libakerror issue #38.
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
Co-Authored-By: Claude Code (Claude Opus 5, claude-opus-5[1m]) <noreply@anthropic.com>
2026-08-05 23:26:15 -04:00
| `DIRECTORY` | `DIRECTORY` | **Refused. ** Not written yet; the standard-library wrapper it waited on has landed. |
2026-07-31 21:50:50 -04:00
| `DLOAD` | `DLOAD "name"` | Load a program from a file. |
Fix generator teardown leaks, add RETURN-in-GEN and LOOP conditions on DO EACH
Review findings and follow-ups from PR #61 review:
- runtime_generator.c: akbasic_runtime_release_generator() now releases the
forGeneratorEnv of every scope it walks through. Abandoning a generator
that was itself suspended inside a FOR EACH over another generator
stranded the inner generator's pool slot; a loop doing so exhausted the
twelve-slot pool and died far from the cause.
- runtime.c/runtime.h: new akbasic_runtime_unwind_to_environment(), the
shared teardown for the error unwinds in pump_generator() and
call_function() -- both previously bare prev_environment() loops with the
same suspended-generator blindness.
- runtime_commands.c: bare RETURN standing in a GEN's own frame ends the
generator exactly as END GEN does -- a GEN is a function at heart. RETURN
with a value there is refused (values leave a GEN only through EMIT). The
no-frame error message now says "GOSUB, DEF, or GEN".
- runtime_structure.c: LOOP WHILE/UNTIL composes with DO EACH -- checked
after each trip with the loop variable still holding that trip's value; a
condition that stops the loop abandons the generator exactly as EXIT
does. Previously the condition was silently ignored, while the verb
reference documented it as working.
- parser_commands.c: trailing tokens after the generator call on a FOR
EACH/DO EACH line are refused at parse. Previously they sat unparsed and
blew up only after the loop completed, when the parent scope resumed the
line mid-statement -- an error at the loop's end pointing at its start.
- tests/generators.c: pool-exhaustion tests for the nested-abandonment and
LOOP-condition paths, RETURN semantics tests, and a direct test of the
unwind primitive. Three new golden pairs cover RETURN, LOOP conditions
and the misplaced-condition parse error.
- docs: RETURN and LOOP-condition semantics in 04-control-flow.md and
11-verb-reference.md; corrected the self-recursion analogy (functions
are re-entrant here). TODO.md 1.10 records the generator design
decisions the code comments were already citing, plus the zero-arg
parameter-list limitation. MAINTENANCE.md gains the abandoned-generators
invariant those comments also cited.
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-06 11:29:17 -04:00
| `DO` | `DO [WHILE c | UNTIL c]` , `DO EACH V IN gen(args)` | Start a loop. The condition may be here, on the `LOOP` , or neither. `EACH` consumes a `GEN` instead, and takes its condition only on the `LOOP` ; see Chapter 4. |
2026-07-31 21:50:50 -04:00
| `DOPEN` | `DOPEN n, "name" [,W]` | Open a file on channel `n` . `W` opens it for writing. |
| `DRAW` | `DRAW src, x, y [TO x, y ...]` | Plot a point or draw a polyline. |
| `DSAVE` | `DSAVE "name"` | Save the program to a file. |
| `DVERIFY` | `DVERIFY "name"` | The other name for `VERIFY` . |
Implement generators: GEN, EMIT, END GEN, FOR EACH and DO EACH (issue 57)
Adds generator support per the plan in issue 57:
- environment.h: isGenerator/generatorFn on a GEN call's own environment,
isEachLoop and forGeneratorEnv on a FOR EACH/DO EACH loop's own
environment.
- runtime.c: splits akbasic_runtime_prev_environment() into
akbasic_runtime_detach_environment() (return to parent without releasing)
and akbasic_runtime_release_environment() (give variables and the pool
slot back, on any environment); prev_environment() is now the two in
sequence. akbasic_runtime_call_function() refuses to call a GEN like an
ordinary function.
- verbs.c/verbs.h/scanner: new keywords GEN, EMIT, EACH, IN and the compound
verb "END GEN" (built by a new akbasic_parse_end(), the same trick
akbasic_parse_print() uses for PRINT #).
- parser_commands.c: akbasic_parse_gen() (modelled on multi-line DEF),
akbasic_parse_end(), and EACH branches in akbasic_parse_for()/
akbasic_parse_do().
- runtime_generator.c (new): akbasic_cmd_gen, akbasic_cmd_emit,
akbasic_cmd_end_gen, and the invoke/pump/release machinery FOR EACH, DO
EACH, NEXT and LOOP share. EMIT walks up to the nearest isGenerator
ancestor rather than assuming it is standing directly in the GEN's own
call frame, because a GEN body may nest its own FOR/DO/GOSUB around an
EMIT -- the issue's own ROOMOBJECTS example does exactly that.
- runtime_commands.c/runtime_structure.c: EACH branches in cmd_for/cmd_do,
matching EACH branches in cmd_next/cmd_loop, and forGeneratorEnv release
on every path that can abandon a live generator (EXIT, a NEXT that pops
for a mismatched loop variable).
Deviates from the plan in one place: FunctionDef gained an isGenerator flag
(not in the plan's field list) because refusing a GEN called like a
function has to happen before anything is pushed. Relying on EMIT's own
isGenerator check for that case doesn't work: akbasic_runtime_call_function()
drives its own step loop the same way akbasic_runtime_pump_generator() does,
and a BASIC-level error inside that loop is swallowed by process_line_run()
as reported-but-not-propagated, so the call would silently "succeed" with a
meaningless return value instead of failing.
Also: a zero-argument parameter list is not supported by the DEF/GEN
parameter parser this reuses (a pre-existing limitation, not
generator-specific); every generator in the tests takes at least one
parameter as a result.
Tests: tests/generators.c (pool exhaustion under repeated EXIT, calling a
GEN like a function, EMIT outside a GEN, self-recursion, sibling/nested
invocations) and tests/language/flowcontrol/generators_*.bas -- the
issue's own ROOMOBJECTS example in both loop shapes, an empty generator,
non-numeric EMIT, nested/interleaved invocations, and three error-path
golden cases. Docs: control-flow chapter 4 gets a GEN/EMIT/FOR EACH/DO EACH
section, the verb reference gets GEN/EMIT/END GEN entries and updated
FOR/DO/NEXT/LOOP/EXIT rows, and architecture chapter 14 documents the
detach/release split and the two-environment generator invocation.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-06 10:02:43 -04:00
| `EMIT` | `EMIT expr` | Yield one value from a `GEN` body. Only valid inside one; see Chapter 4. |
2026-07-31 21:50:50 -04:00
| `END` | `END` | Stop the program. Does not arm `CONT` . |
Implement generators: GEN, EMIT, END GEN, FOR EACH and DO EACH (issue 57)
Adds generator support per the plan in issue 57:
- environment.h: isGenerator/generatorFn on a GEN call's own environment,
isEachLoop and forGeneratorEnv on a FOR EACH/DO EACH loop's own
environment.
- runtime.c: splits akbasic_runtime_prev_environment() into
akbasic_runtime_detach_environment() (return to parent without releasing)
and akbasic_runtime_release_environment() (give variables and the pool
slot back, on any environment); prev_environment() is now the two in
sequence. akbasic_runtime_call_function() refuses to call a GEN like an
ordinary function.
- verbs.c/verbs.h/scanner: new keywords GEN, EMIT, EACH, IN and the compound
verb "END GEN" (built by a new akbasic_parse_end(), the same trick
akbasic_parse_print() uses for PRINT #).
- parser_commands.c: akbasic_parse_gen() (modelled on multi-line DEF),
akbasic_parse_end(), and EACH branches in akbasic_parse_for()/
akbasic_parse_do().
- runtime_generator.c (new): akbasic_cmd_gen, akbasic_cmd_emit,
akbasic_cmd_end_gen, and the invoke/pump/release machinery FOR EACH, DO
EACH, NEXT and LOOP share. EMIT walks up to the nearest isGenerator
ancestor rather than assuming it is standing directly in the GEN's own
call frame, because a GEN body may nest its own FOR/DO/GOSUB around an
EMIT -- the issue's own ROOMOBJECTS example does exactly that.
- runtime_commands.c/runtime_structure.c: EACH branches in cmd_for/cmd_do,
matching EACH branches in cmd_next/cmd_loop, and forGeneratorEnv release
on every path that can abandon a live generator (EXIT, a NEXT that pops
for a mismatched loop variable).
Deviates from the plan in one place: FunctionDef gained an isGenerator flag
(not in the plan's field list) because refusing a GEN called like a
function has to happen before anything is pushed. Relying on EMIT's own
isGenerator check for that case doesn't work: akbasic_runtime_call_function()
drives its own step loop the same way akbasic_runtime_pump_generator() does,
and a BASIC-level error inside that loop is swallowed by process_line_run()
as reported-but-not-propagated, so the call would silently "succeed" with a
meaningless return value instead of failing.
Also: a zero-argument parameter list is not supported by the DEF/GEN
parameter parser this reuses (a pre-existing limitation, not
generator-specific); every generator in the tests takes at least one
parameter as a result.
Tests: tests/generators.c (pool exhaustion under repeated EXIT, calling a
GEN like a function, EMIT outside a GEN, self-recursion, sibling/nested
invocations) and tests/language/flowcontrol/generators_*.bas -- the
issue's own ROOMOBJECTS example in both loop shapes, an empty generator,
non-numeric EMIT, nested/interleaved invocations, and three error-path
golden cases. Docs: control-flow chapter 4 gets a GEN/EMIT/FOR EACH/DO EACH
section, the verb reference gets GEN/EMIT/END GEN entries and updated
FOR/DO/NEXT/LOOP/EXIT rows, and architecture chapter 14 documents the
detach/release split and the two-environment generator invocation.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-06 10:02:43 -04:00
| `END GEN` | `END GEN` | Close a `GEN` body, the way `RETURN` closes a multi-line `DEF` . |
2026-07-31 21:50:50 -04:00
| `ENVELOPE` | `ENVELOPE n, a, d, s, r` | Define one of `PLAY` 's ten envelope presets. |
Implement generators: GEN, EMIT, END GEN, FOR EACH and DO EACH (issue 57)
Adds generator support per the plan in issue 57:
- environment.h: isGenerator/generatorFn on a GEN call's own environment,
isEachLoop and forGeneratorEnv on a FOR EACH/DO EACH loop's own
environment.
- runtime.c: splits akbasic_runtime_prev_environment() into
akbasic_runtime_detach_environment() (return to parent without releasing)
and akbasic_runtime_release_environment() (give variables and the pool
slot back, on any environment); prev_environment() is now the two in
sequence. akbasic_runtime_call_function() refuses to call a GEN like an
ordinary function.
- verbs.c/verbs.h/scanner: new keywords GEN, EMIT, EACH, IN and the compound
verb "END GEN" (built by a new akbasic_parse_end(), the same trick
akbasic_parse_print() uses for PRINT #).
- parser_commands.c: akbasic_parse_gen() (modelled on multi-line DEF),
akbasic_parse_end(), and EACH branches in akbasic_parse_for()/
akbasic_parse_do().
- runtime_generator.c (new): akbasic_cmd_gen, akbasic_cmd_emit,
akbasic_cmd_end_gen, and the invoke/pump/release machinery FOR EACH, DO
EACH, NEXT and LOOP share. EMIT walks up to the nearest isGenerator
ancestor rather than assuming it is standing directly in the GEN's own
call frame, because a GEN body may nest its own FOR/DO/GOSUB around an
EMIT -- the issue's own ROOMOBJECTS example does exactly that.
- runtime_commands.c/runtime_structure.c: EACH branches in cmd_for/cmd_do,
matching EACH branches in cmd_next/cmd_loop, and forGeneratorEnv release
on every path that can abandon a live generator (EXIT, a NEXT that pops
for a mismatched loop variable).
Deviates from the plan in one place: FunctionDef gained an isGenerator flag
(not in the plan's field list) because refusing a GEN called like a
function has to happen before anything is pushed. Relying on EMIT's own
isGenerator check for that case doesn't work: akbasic_runtime_call_function()
drives its own step loop the same way akbasic_runtime_pump_generator() does,
and a BASIC-level error inside that loop is swallowed by process_line_run()
as reported-but-not-propagated, so the call would silently "succeed" with a
meaningless return value instead of failing.
Also: a zero-argument parameter list is not supported by the DEF/GEN
parameter parser this reuses (a pre-existing limitation, not
generator-specific); every generator in the tests takes at least one
parameter as a result.
Tests: tests/generators.c (pool exhaustion under repeated EXIT, calling a
GEN like a function, EMIT outside a GEN, self-recursion, sibling/nested
invocations) and tests/language/flowcontrol/generators_*.bas -- the
issue's own ROOMOBJECTS example in both loop shapes, an empty generator,
non-numeric EMIT, nested/interleaved invocations, and three error-path
golden cases. Docs: control-flow chapter 4 gets a GEN/EMIT/FOR EACH/DO EACH
section, the verb reference gets GEN/EMIT/END GEN entries and updated
FOR/DO/NEXT/LOOP/EXIT rows, and architecture chapter 14 documents the
detach/release split and the two-environment generator invocation.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-06 10:02:43 -04:00
| `EXIT` | `EXIT` | Leave the innermost `FOR` , `FOR EACH` , `DO` or `DO EACH` loop. |
2026-07-31 21:50:50 -04:00
| `FETCH` | `FETCH count, from, to` | Copy bytes. The same as `STASH` ; there is no expansion RAM. |
| `FILTER` | `FILTER ...` | **Refused. ** There is no filter stage in the audio backend. |
Implement generators: GEN, EMIT, END GEN, FOR EACH and DO EACH (issue 57)
Adds generator support per the plan in issue 57:
- environment.h: isGenerator/generatorFn on a GEN call's own environment,
isEachLoop and forGeneratorEnv on a FOR EACH/DO EACH loop's own
environment.
- runtime.c: splits akbasic_runtime_prev_environment() into
akbasic_runtime_detach_environment() (return to parent without releasing)
and akbasic_runtime_release_environment() (give variables and the pool
slot back, on any environment); prev_environment() is now the two in
sequence. akbasic_runtime_call_function() refuses to call a GEN like an
ordinary function.
- verbs.c/verbs.h/scanner: new keywords GEN, EMIT, EACH, IN and the compound
verb "END GEN" (built by a new akbasic_parse_end(), the same trick
akbasic_parse_print() uses for PRINT #).
- parser_commands.c: akbasic_parse_gen() (modelled on multi-line DEF),
akbasic_parse_end(), and EACH branches in akbasic_parse_for()/
akbasic_parse_do().
- runtime_generator.c (new): akbasic_cmd_gen, akbasic_cmd_emit,
akbasic_cmd_end_gen, and the invoke/pump/release machinery FOR EACH, DO
EACH, NEXT and LOOP share. EMIT walks up to the nearest isGenerator
ancestor rather than assuming it is standing directly in the GEN's own
call frame, because a GEN body may nest its own FOR/DO/GOSUB around an
EMIT -- the issue's own ROOMOBJECTS example does exactly that.
- runtime_commands.c/runtime_structure.c: EACH branches in cmd_for/cmd_do,
matching EACH branches in cmd_next/cmd_loop, and forGeneratorEnv release
on every path that can abandon a live generator (EXIT, a NEXT that pops
for a mismatched loop variable).
Deviates from the plan in one place: FunctionDef gained an isGenerator flag
(not in the plan's field list) because refusing a GEN called like a
function has to happen before anything is pushed. Relying on EMIT's own
isGenerator check for that case doesn't work: akbasic_runtime_call_function()
drives its own step loop the same way akbasic_runtime_pump_generator() does,
and a BASIC-level error inside that loop is swallowed by process_line_run()
as reported-but-not-propagated, so the call would silently "succeed" with a
meaningless return value instead of failing.
Also: a zero-argument parameter list is not supported by the DEF/GEN
parameter parser this reuses (a pre-existing limitation, not
generator-specific); every generator in the tests takes at least one
parameter as a result.
Tests: tests/generators.c (pool exhaustion under repeated EXIT, calling a
GEN like a function, EMIT outside a GEN, self-recursion, sibling/nested
invocations) and tests/language/flowcontrol/generators_*.bas -- the
issue's own ROOMOBJECTS example in both loop shapes, an empty generator,
non-numeric EMIT, nested/interleaved invocations, and three error-path
golden cases. Docs: control-flow chapter 4 gets a GEN/EMIT/FOR EACH/DO EACH
section, the verb reference gets GEN/EMIT/END GEN entries and updated
FOR/DO/NEXT/LOOP/EXIT rows, and architecture chapter 14 documents the
detach/release split and the two-environment generator invocation.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-06 10:02:43 -04:00
| `FOR` | `FOR V = a TO b [STEP c]` , `FOR EACH V IN gen(args)` | Start a counted loop, ended by `NEXT` . `EACH` consumes a `GEN` instead; see Chapter 4. |
| `GEN` | `GEN NAME(args) ... END GEN` | Define a generator: a subroutine that yields more than once via `EMIT` , consumed by `FOR EACH` /`DO EACH` . See Chapter 4. |
2026-07-31 21:50:50 -04:00
| `GET` | `GET V` | Take a keystroke if one is waiting, without stopping. |
| `GETKEY` | `GETKEY V` | Wait for a keystroke, holding the program but not the host. |
Give BASIC menus, dialogs and HUD labels over libakgl's UI helpers
Group K, and the first verbs to reach the akgl_ui subsystem 0.9.0 brought
in: MENU and GETMENU and RMENU, DIALOG, HUD and UISTYLE. A program that
wanted a title screen had to draw one out of CHAR and GETKEY, which is
what both breakout tutorials make a reader do.
The interesting part is the impedance mismatch. libakgl's UI is immediate
mode -- widgets are re-declared inside a frame bracket every frame and
clay borrows their text until the bracket closes -- and a BASIC program
says MENU 1, "START" on line 100 and expects it up on line 900, several
hundred frames later. So src/ui_akgl.c is retained on this side and
immediate on that one: the record's entry points are setters that copy
into akbasic_AkglUi, and akbasic_ui_akgl_render() replays the whole set
once a frame from the host's pump. No BASIC string, which lives in the
per-line value pool, is ever what clay is handed.
The shapes are borrowed rather than invented. MENU retires the way SOLID
does -- no entries retires one, no arguments retire them all. GETMENU
holds the step loop the way GETKEY does, so parking is not blocking: the
step still returns, the host keeps its frame rate, and the sprite, audio
and collision services keep running underneath because they run before
the blocking checks. RMENU(n,1) reads and clears the way BUMP() does.
Withdrawing the device or retiring the menu releases a holding GETMENU
with 0 rather than wedging the script, which is akbasic_input_service()'s
rule for a withdrawn keyboard.
One thing a program has to know, and docs/19-user-interface.md says it
twice: a menu that is up owns the cursor keys and Return. It has to, and
retiring it gives them back -- forget the MENU n before an INPUT and the
INPUT never sees the Return that ends it.
akbasic_runtime_set_ui() is its own function rather than a fifth argument
to akbasic_runtime_set_devices(), whose signature has twenty-eight call
sites in tests and documentation that are about something else.
deps/libakgl is not touched. akgl_UiAnchor has the four corners and dead
centre, so HUD offers exactly those five; TODO.md records what a
top-centre and bottom-centre would cost upstream, along with the three
other things this deliberately leaves out. No new error code either --
DEVICE, BOUNDS, SYNTAX and TYPE cover the group, and 520 stays free.
tools/screenshot.c had to learn that "needs a font" and "draws the text
grid" are two questions. They were one, and a UI figure came out black:
the text layer owns every pixel of the rows it covers and painted over
the widgets. The new ui=1 fence attribute asks for the first without the
second; MAINTENANCE.md documents it.
112/112 in both configurations, 112/112 under ASan and UBSan, coverage
94.1% against the 90% gate with src/runtime_ui.c at 99% of lines and
100% of functions, doxygen clean, and the four new figures byte-identical
on a re-render. TODO.md section 8's gate table was stale on several
counts besides these and is refreshed with measured numbers.
Co-Authored-By: Tachikoma (Claude Code Opus 5 1M) <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-02 18:37:10 -04:00
| `GETMENU` | `GETMENU n, V%` | Wait for a menu choice, holding the program but not the host. Assigns the entry number. See Chapter 19. |
2026-07-31 21:50:50 -04:00
| `GOSUB` | `GOSUB line` | Call a subroutine, returning on `RETURN` . |
| `GOTO` | `GOTO line` | Jump to a line or a label. |
| `GRAPHIC` | `GRAPHIC mode | CLR` | Choose a screen mode, or clear it. |
| `GSHAPE` | `GSHAPE A$, x, y` | Stamp a region saved by `SSHAPE` . |
| `HEADER` | `HEADER "name"` | **Refused. ** Formats a disk. |
| `HELP` | `HELP` | Re-list the line the last error happened on. |
Give BASIC menus, dialogs and HUD labels over libakgl's UI helpers
Group K, and the first verbs to reach the akgl_ui subsystem 0.9.0 brought
in: MENU and GETMENU and RMENU, DIALOG, HUD and UISTYLE. A program that
wanted a title screen had to draw one out of CHAR and GETKEY, which is
what both breakout tutorials make a reader do.
The interesting part is the impedance mismatch. libakgl's UI is immediate
mode -- widgets are re-declared inside a frame bracket every frame and
clay borrows their text until the bracket closes -- and a BASIC program
says MENU 1, "START" on line 100 and expects it up on line 900, several
hundred frames later. So src/ui_akgl.c is retained on this side and
immediate on that one: the record's entry points are setters that copy
into akbasic_AkglUi, and akbasic_ui_akgl_render() replays the whole set
once a frame from the host's pump. No BASIC string, which lives in the
per-line value pool, is ever what clay is handed.
The shapes are borrowed rather than invented. MENU retires the way SOLID
does -- no entries retires one, no arguments retire them all. GETMENU
holds the step loop the way GETKEY does, so parking is not blocking: the
step still returns, the host keeps its frame rate, and the sprite, audio
and collision services keep running underneath because they run before
the blocking checks. RMENU(n,1) reads and clears the way BUMP() does.
Withdrawing the device or retiring the menu releases a holding GETMENU
with 0 rather than wedging the script, which is akbasic_input_service()'s
rule for a withdrawn keyboard.
One thing a program has to know, and docs/19-user-interface.md says it
twice: a menu that is up owns the cursor keys and Return. It has to, and
retiring it gives them back -- forget the MENU n before an INPUT and the
INPUT never sees the Return that ends it.
akbasic_runtime_set_ui() is its own function rather than a fifth argument
to akbasic_runtime_set_devices(), whose signature has twenty-eight call
sites in tests and documentation that are about something else.
deps/libakgl is not touched. akgl_UiAnchor has the four corners and dead
centre, so HUD offers exactly those five; TODO.md records what a
top-centre and bottom-centre would cost upstream, along with the three
other things this deliberately leaves out. No new error code either --
DEVICE, BOUNDS, SYNTAX and TYPE cover the group, and 520 stays free.
tools/screenshot.c had to learn that "needs a font" and "draws the text
grid" are two questions. They were one, and a UI figure came out black:
the text layer owns every pixel of the rows it covers and painted over
the widgets. The new ui=1 fence attribute asks for the first without the
second; MAINTENANCE.md documents it.
112/112 in both configurations, 112/112 under ASan and UBSan, coverage
94.1% against the 90% gate with src/runtime_ui.c at 99% of lines and
100% of functions, doxygen clean, and the four new figures byte-identical
on a re-render. TODO.md section 8's gate table was stale on several
counts besides these and is refreshed with measured numbers.
Co-Authored-By: Tachikoma (Claude Code Opus 5 1M) <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-02 18:37:10 -04:00
| `HUD` | `HUD n [,anchor, "text"]` | Pin a line of text to a corner or the centre. No text retires the slot; no arguments retire them all. See Chapter 19. |
2026-07-31 21:50:50 -04:00
| `IF` | `IF c THEN s [ELSE s]` | Branch. Everything after `THEN` belongs to the condition. |
| `INPUT` | `INPUT ["prompt"] V` | Read a line from the user. |
| `INPUT#` | `INPUT #n, V` | Read a line from a channel. |
| `KEY` | `KEY [n, "text"]` | Define a function-key macro, or list them all. |
| `LABEL` | `LABEL NAME` | Mark this line with a name any branch can use. |
| `LET` | `LET V = expr` | Assign. Optional; assignment needs no verb. |
| `LIST` | `LIST [n][-n]` | List the program, or part of it. |
| `LOAD` | `LOAD "name"` | The other name for `DLOAD` . |
| `LOCATE` | `LOCATE x, y` | Move the pixel cursor. |
Implement generators: GEN, EMIT, END GEN, FOR EACH and DO EACH (issue 57)
Adds generator support per the plan in issue 57:
- environment.h: isGenerator/generatorFn on a GEN call's own environment,
isEachLoop and forGeneratorEnv on a FOR EACH/DO EACH loop's own
environment.
- runtime.c: splits akbasic_runtime_prev_environment() into
akbasic_runtime_detach_environment() (return to parent without releasing)
and akbasic_runtime_release_environment() (give variables and the pool
slot back, on any environment); prev_environment() is now the two in
sequence. akbasic_runtime_call_function() refuses to call a GEN like an
ordinary function.
- verbs.c/verbs.h/scanner: new keywords GEN, EMIT, EACH, IN and the compound
verb "END GEN" (built by a new akbasic_parse_end(), the same trick
akbasic_parse_print() uses for PRINT #).
- parser_commands.c: akbasic_parse_gen() (modelled on multi-line DEF),
akbasic_parse_end(), and EACH branches in akbasic_parse_for()/
akbasic_parse_do().
- runtime_generator.c (new): akbasic_cmd_gen, akbasic_cmd_emit,
akbasic_cmd_end_gen, and the invoke/pump/release machinery FOR EACH, DO
EACH, NEXT and LOOP share. EMIT walks up to the nearest isGenerator
ancestor rather than assuming it is standing directly in the GEN's own
call frame, because a GEN body may nest its own FOR/DO/GOSUB around an
EMIT -- the issue's own ROOMOBJECTS example does exactly that.
- runtime_commands.c/runtime_structure.c: EACH branches in cmd_for/cmd_do,
matching EACH branches in cmd_next/cmd_loop, and forGeneratorEnv release
on every path that can abandon a live generator (EXIT, a NEXT that pops
for a mismatched loop variable).
Deviates from the plan in one place: FunctionDef gained an isGenerator flag
(not in the plan's field list) because refusing a GEN called like a
function has to happen before anything is pushed. Relying on EMIT's own
isGenerator check for that case doesn't work: akbasic_runtime_call_function()
drives its own step loop the same way akbasic_runtime_pump_generator() does,
and a BASIC-level error inside that loop is swallowed by process_line_run()
as reported-but-not-propagated, so the call would silently "succeed" with a
meaningless return value instead of failing.
Also: a zero-argument parameter list is not supported by the DEF/GEN
parameter parser this reuses (a pre-existing limitation, not
generator-specific); every generator in the tests takes at least one
parameter as a result.
Tests: tests/generators.c (pool exhaustion under repeated EXIT, calling a
GEN like a function, EMIT outside a GEN, self-recursion, sibling/nested
invocations) and tests/language/flowcontrol/generators_*.bas -- the
issue's own ROOMOBJECTS example in both loop shapes, an empty generator,
non-numeric EMIT, nested/interleaved invocations, and three error-path
golden cases. Docs: control-flow chapter 4 gets a GEN/EMIT/FOR EACH/DO EACH
section, the verb reference gets GEN/EMIT/END GEN entries and updated
FOR/DO/NEXT/LOOP/EXIT rows, and architecture chapter 14 documents the
detach/release split and the two-environment generator invocation.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-06 10:02:43 -04:00
| `LOOP` | `LOOP [WHILE c | UNTIL c]` | End a `DO` loop, including a `DO EACH` . |
Give BASIC menus, dialogs and HUD labels over libakgl's UI helpers
Group K, and the first verbs to reach the akgl_ui subsystem 0.9.0 brought
in: MENU and GETMENU and RMENU, DIALOG, HUD and UISTYLE. A program that
wanted a title screen had to draw one out of CHAR and GETKEY, which is
what both breakout tutorials make a reader do.
The interesting part is the impedance mismatch. libakgl's UI is immediate
mode -- widgets are re-declared inside a frame bracket every frame and
clay borrows their text until the bracket closes -- and a BASIC program
says MENU 1, "START" on line 100 and expects it up on line 900, several
hundred frames later. So src/ui_akgl.c is retained on this side and
immediate on that one: the record's entry points are setters that copy
into akbasic_AkglUi, and akbasic_ui_akgl_render() replays the whole set
once a frame from the host's pump. No BASIC string, which lives in the
per-line value pool, is ever what clay is handed.
The shapes are borrowed rather than invented. MENU retires the way SOLID
does -- no entries retires one, no arguments retire them all. GETMENU
holds the step loop the way GETKEY does, so parking is not blocking: the
step still returns, the host keeps its frame rate, and the sprite, audio
and collision services keep running underneath because they run before
the blocking checks. RMENU(n,1) reads and clears the way BUMP() does.
Withdrawing the device or retiring the menu releases a holding GETMENU
with 0 rather than wedging the script, which is akbasic_input_service()'s
rule for a withdrawn keyboard.
One thing a program has to know, and docs/19-user-interface.md says it
twice: a menu that is up owns the cursor keys and Return. It has to, and
retiring it gives them back -- forget the MENU n before an INPUT and the
INPUT never sees the Return that ends it.
akbasic_runtime_set_ui() is its own function rather than a fifth argument
to akbasic_runtime_set_devices(), whose signature has twenty-eight call
sites in tests and documentation that are about something else.
deps/libakgl is not touched. akgl_UiAnchor has the four corners and dead
centre, so HUD offers exactly those five; TODO.md records what a
top-centre and bottom-centre would cost upstream, along with the three
other things this deliberately leaves out. No new error code either --
DEVICE, BOUNDS, SYNTAX and TYPE cover the group, and 520 stays free.
tools/screenshot.c had to learn that "needs a font" and "draws the text
grid" are two questions. They were one, and a UI figure came out black:
the text layer owns every pixel of the rows it covers and painted over
the widgets. The new ui=1 fence attribute asks for the first without the
second; MAINTENANCE.md documents it.
112/112 in both configurations, 112/112 under ASan and UBSan, coverage
94.1% against the 90% gate with src/runtime_ui.c at 99% of lines and
100% of functions, doxygen clean, and the four new figures byte-identical
on a re-render. TODO.md section 8's gate table was stale on several
counts besides these and is refreshed with measured numbers.
Co-Authored-By: Tachikoma (Claude Code Opus 5 1M) <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-02 18:37:10 -04:00
| `MENU` | `MENU [n [,"item", ...]]` | Show a menu the player picks from. No entries retires it; no arguments retire them all. See Chapter 19. |
2026-07-31 21:50:50 -04:00
| `MOVSPR` | `MOVSPR n, ...` | Move a sprite. Four forms; see Chapter 8. |
| `NEW` | `NEW` | Erase the program and every variable. |
Implement generators: GEN, EMIT, END GEN, FOR EACH and DO EACH (issue 57)
Adds generator support per the plan in issue 57:
- environment.h: isGenerator/generatorFn on a GEN call's own environment,
isEachLoop and forGeneratorEnv on a FOR EACH/DO EACH loop's own
environment.
- runtime.c: splits akbasic_runtime_prev_environment() into
akbasic_runtime_detach_environment() (return to parent without releasing)
and akbasic_runtime_release_environment() (give variables and the pool
slot back, on any environment); prev_environment() is now the two in
sequence. akbasic_runtime_call_function() refuses to call a GEN like an
ordinary function.
- verbs.c/verbs.h/scanner: new keywords GEN, EMIT, EACH, IN and the compound
verb "END GEN" (built by a new akbasic_parse_end(), the same trick
akbasic_parse_print() uses for PRINT #).
- parser_commands.c: akbasic_parse_gen() (modelled on multi-line DEF),
akbasic_parse_end(), and EACH branches in akbasic_parse_for()/
akbasic_parse_do().
- runtime_generator.c (new): akbasic_cmd_gen, akbasic_cmd_emit,
akbasic_cmd_end_gen, and the invoke/pump/release machinery FOR EACH, DO
EACH, NEXT and LOOP share. EMIT walks up to the nearest isGenerator
ancestor rather than assuming it is standing directly in the GEN's own
call frame, because a GEN body may nest its own FOR/DO/GOSUB around an
EMIT -- the issue's own ROOMOBJECTS example does exactly that.
- runtime_commands.c/runtime_structure.c: EACH branches in cmd_for/cmd_do,
matching EACH branches in cmd_next/cmd_loop, and forGeneratorEnv release
on every path that can abandon a live generator (EXIT, a NEXT that pops
for a mismatched loop variable).
Deviates from the plan in one place: FunctionDef gained an isGenerator flag
(not in the plan's field list) because refusing a GEN called like a
function has to happen before anything is pushed. Relying on EMIT's own
isGenerator check for that case doesn't work: akbasic_runtime_call_function()
drives its own step loop the same way akbasic_runtime_pump_generator() does,
and a BASIC-level error inside that loop is swallowed by process_line_run()
as reported-but-not-propagated, so the call would silently "succeed" with a
meaningless return value instead of failing.
Also: a zero-argument parameter list is not supported by the DEF/GEN
parameter parser this reuses (a pre-existing limitation, not
generator-specific); every generator in the tests takes at least one
parameter as a result.
Tests: tests/generators.c (pool exhaustion under repeated EXIT, calling a
GEN like a function, EMIT outside a GEN, self-recursion, sibling/nested
invocations) and tests/language/flowcontrol/generators_*.bas -- the
issue's own ROOMOBJECTS example in both loop shapes, an empty generator,
non-numeric EMIT, nested/interleaved invocations, and three error-path
golden cases. Docs: control-flow chapter 4 gets a GEN/EMIT/FOR EACH/DO EACH
section, the verb reference gets GEN/EMIT/END GEN entries and updated
FOR/DO/NEXT/LOOP/EXIT rows, and architecture chapter 14 documents the
detach/release split and the two-environment generator invocation.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-06 10:02:43 -04:00
| `NEXT` | `NEXT V` | End a `FOR` loop and advance its counter, or resume a `FOR EACH` for its next value. |
2026-07-31 21:50:50 -04:00
| `ON` | `ON e GOTO|GOSUB t [,...]` | Branch to the `e` th target, counting from one. |
| `PAINT` | `PAINT src, x, y` | Flood-fill the region containing a point. |
| `PLAY` | `PLAY "notes"` | Queue notes. Does not block. |
Document structures: a chapter, the architecture, and the differences
docs/16-structures.md is the feature: records, nesting, copy-on-assign, strict
pointers, lists, what is checked and what is not, and how a host shares its own
C structs. Every example in it is executed by docs_examples and byte-compared,
including the refusals -- so a message that changes fails the suite rather than
quietly making the chapter wrong.
The chapter makes one contrast explicitly, because it is the question a reader
will actually have: a misspelled *field* is refused and a misspelled *variable*
still prints zero. The rule underneath is that what the program declared gets
checked and what it did not gets shrugged at -- a variable's name is never
declared, a TYPE's field list is. Structures end up the strictest thing in the
language, not from a higher standard but because they are the only named thing
whose valid spellings are written down.
Chapter 14 gains the layout: an instance is a contiguous run of value slots with
a diagram of where the fields sit, the three-pass prescan and why each pass
exists, why the copy cannot live in akbasic_value_clone(), and why the render
depth bound is four rather than eight. Chapter 3 gains the @ suffix, chapter 13
records that all of this is an addition BASIC 7.0 has nothing like, and the verb
reference gains TYPE, POINT and DIM ... AS.
MAINTENANCE.md gains the two rules that are on a maintainer rather than on a
test: a structure copy must not go through clone, and a field chain gets its own
leaf field. TODO.md section 5 records what was invented and the three limits
that are ours, and section 8 records the two defects the work exposed.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-01 12:03:02 -04:00
| `POINT` | `POINT P@ AT s@` | Aim a strict pointer at a structure. See Chapter 16. |
2026-07-31 21:50:50 -04:00
| `POKE` | `POKE addr, byte` | Write a byte to a real address. |
| `PRINT` | `PRINT [expr]` | Print a value and a newline. |
| `PRINT#` | `PRINT #n, expr` | Write a line to a channel. |
| `PUDEF` | `PUDEF "chars"` | Redefine what `PRINT USING` pads and punctuates with. |
| `QUIT` | `QUIT` | End the interpreter. |
| `READ` | `READ V [,...]` | Fill variables from the next `DATA` items. |
| `RECORD` | `RECORD n, r [,pos]` | Position a channel at record `r` . Records are lines. |
| `RENAME` | `RENAME "a", "b"` | Rename a file. |
| `RENUMBER` | `RENUMBER [start [,step [,from]]]` | Renumber lines, rewriting every branch to match. |
| `RESTORE` | `RESTORE [line]` | Reset the `READ` cursor, optionally to a line. |
| `RESUME` | `RESUME [NEXT | line]` | Return from a `TRAP` handler. |
Fix generator teardown leaks, add RETURN-in-GEN and LOOP conditions on DO EACH
Review findings and follow-ups from PR #61 review:
- runtime_generator.c: akbasic_runtime_release_generator() now releases the
forGeneratorEnv of every scope it walks through. Abandoning a generator
that was itself suspended inside a FOR EACH over another generator
stranded the inner generator's pool slot; a loop doing so exhausted the
twelve-slot pool and died far from the cause.
- runtime.c/runtime.h: new akbasic_runtime_unwind_to_environment(), the
shared teardown for the error unwinds in pump_generator() and
call_function() -- both previously bare prev_environment() loops with the
same suspended-generator blindness.
- runtime_commands.c: bare RETURN standing in a GEN's own frame ends the
generator exactly as END GEN does -- a GEN is a function at heart. RETURN
with a value there is refused (values leave a GEN only through EMIT). The
no-frame error message now says "GOSUB, DEF, or GEN".
- runtime_structure.c: LOOP WHILE/UNTIL composes with DO EACH -- checked
after each trip with the loop variable still holding that trip's value; a
condition that stops the loop abandons the generator exactly as EXIT
does. Previously the condition was silently ignored, while the verb
reference documented it as working.
- parser_commands.c: trailing tokens after the generator call on a FOR
EACH/DO EACH line are refused at parse. Previously they sat unparsed and
blew up only after the loop completed, when the parent scope resumed the
line mid-statement -- an error at the loop's end pointing at its start.
- tests/generators.c: pool-exhaustion tests for the nested-abandonment and
LOOP-condition paths, RETURN semantics tests, and a direct test of the
unwind primitive. Three new golden pairs cover RETURN, LOOP conditions
and the misplaced-condition parse error.
- docs: RETURN and LOOP-condition semantics in 04-control-flow.md and
11-verb-reference.md; corrected the self-recursion analogy (functions
are re-entrant here). TODO.md 1.10 records the generator design
decisions the code comments were already citing, plus the zero-arg
parameter-list limitation. MAINTENANCE.md gains the abandoned-generators
invariant those comments also cited.
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-06 11:29:17 -04:00
| `RETURN` | `RETURN [expr]` | Return from a `GOSUB` or a multi-line `DEF` . Inside a `GEN` , a bare `RETURN` ends the generator early; `RETURN expr` there is an error. |
2026-07-31 21:50:50 -04:00
| `RUN` | `RUN [line]` | Run the program, optionally from a line. |
| `SAVE` | `SAVE "name"` | The other name for `DSAVE` . |
| `SCALE` | `SCALE on [,xmax, ymax]` | Turn user coordinates on or off. |
| `SCNCLR` | `SCNCLR` | Clear the text screen. |
| `SCRATCH` | `SCRATCH "name"` | Delete a file. |
| `SLEEP` | `SLEEP seconds` | Pause. Holds the program, not the host. |
Collide sprites with rectangles that are not sprites
`SOLID id, x1, y1, x2, y2` registers static collision geometry; `SOLID id`
retires one and a bare `SOLID` retires them all, the way `TRAP`, `COLLISION` and
`DCLOSE` all read absence. `COLLISION 2` and `BUMP(2)` stop being refused and
mean *sprite met static geometry*.
**This is the thing eight sprite slots made impossible.** A wall of bricks wants
sixty, so until now a program could only collide with one by doing the
arithmetic itself against its own array -- which is exactly what both breakout
listings do, at about two hundred lines between them. A rectangle costs no sprite
slot.
The id is the **program's own number**, 1 to 64, not a minted handle. That is the
whole trick for "which brick did I hit": the id comes back out again, so a wall
built as `SOLID I#, ...` maps onto `B#(I#)` with no lookup, and retiring a broken
brick is `SOLID I#`.
`COLLISION 2` was refused with "sprite-to-background collision needs the screen
read back every frame", which was true of the question a C128 asks -- a sprite
against the bitmap's set pixels. `SOLID` gives this interpreter a background made
of rectangles instead, which is the same question in a form it can answer. Same
move `SPRSAV` made when it learned to take an image path.
`AKBASIC_INTERRUPT_BACKGROUND` has been sitting in the interrupt table commented
"COLLISION 2 -- sprite met background; refused" the whole time. Its accumulator is
separate, so a sprite hitting a wall never sets a bit in `BUMP(1)`.
**There is no `akgl_CollisionWorld` here, and that is deliberate.** libakgl's
uniform grid keeps its cell heads, cell size and origin in file-scope statics, so
it is one index per process -- and `akgl_collision_world_init()` ends in a
`reset()` that memsets those heads *and* calls
`akgl_heap_init_collision_cells()`. An interpreter embedded in a game with its
own collision world would have destroyed every registration that game had made,
on the first `SOLID` a script ran. So the geometry is indexed by an ordinary
array here and pairs go straight to `akgl_collision_test()`, which needs no
world. At sixty-four rectangles that is the right answer anyway; libakgl's own
numbers put a naive sweep at 0.7% of a frame at sixty-four objects.
**The scan now short-circuits when nothing has moved**, and that is what makes
any of it affordable. Its inputs are the sprites' boxes, which slots are
collidable, and the static geometry; if none changed the answer cannot have. A
frame runs one full scan and 255 cached ones. Eight sprites against sixty-four
rectangles is five hundred and twelve tests -- fine once a frame, ruinous 256
times.
The benchmark was rewritten to say which path it is timing, because with the
cache in place a loop that only calls the scan measures the short circuit and
nothing else. Breakout now costs 590.6 ns for its one full scan plus 255 cached
at 40.0, which is 10.8 us against a 1.19 ms frame -- **0.91%, less than the 2.0%
it cost before any of this work**, with static geometry and contacts added on
top.
`NEW` retires the rectangles, where it cannot undefine a sprite pattern: there
*is* an entry point for this one, so leaving them would be a choice, and the
wrong one -- a rectangle is invisible, so one left behind by a deleted program is
an unexplainable collision in the next. `CLR` leaves them alone.
`tests/sprite_verbs.c` gains the whole second path against the mock and its
`COLLISION 2` case is rewritten: it pinned the refusal, and now pins that type 2
arms its own handler without disturbing type 1's. `tests/akgl_backends.c` gains
the end-to-end version, including a full sixty-four-rectangle wall so the proxy
budget is exercised at its ceiling and the pool has to come back intact, and the
sixty-fifth refused by name.
A bare `SOLID` needed `akbasic_parse_optional_arglist` rather than
`akbasic_parse_arglist`, which `DCLOSE` already uses for the same shape.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-02 10:25:35 -04:00
| `SOLID` | `SOLID [id [,x1, y1, x2, y2]]` | Register static collision geometry a sprite can hit. No rectangle retires it; no arguments retires them all. See Chapter 8. |
2026-07-31 21:50:50 -04:00
| `SOUND` | `SOUND v, freq, dur [,...]` | Play a tone on a voice. Does not block. |
| `SPRCOLOR` | `SPRCOLOR [c1] [,c2]` | Set the two shared multicolour registers. |
Let a program say what part of a sprite collides
`SPRHIT n, kind [,x1, y1, x2, y2]` gives a sprite a collision shape: a box, a
circle inscribed in it, or a capsule. `RSPHIT(n, f)` reads it back in SPRHIT's
own argument order, the way RSPRITE and RSPPOS already do, and needs no device
because it answers from interpreter state.
The rectangle is two corners measured from the sprite's top-left, in device
pixels -- the same `x1, y1, x2, y2` that `BOX` and `SSHAPE` take. A dialect with
two spellings for a rectangle is one nobody can write from memory. Omit it and
the shape fits whatever the picture turned out to be, which is what a sprite
loaded from a file needs: `SPRSAV "ship.png", 1` takes the image's own size and
the program never learns what that was.
**A sprite nobody has shaped collides with its whole frame, expansion bits
included, exactly as before.** That is a promise rather than a convenience, and
it has its own test: the same two sprites in the same two places, once with no
SPRHIT and once with a four-pixel box, reporting a collision and then not.
Named SPRHIT rather than SPRSHAPE because "shape" already means "a region SSHAPE
saved" in this dialect, in this very chapter -- `SPRSAV A$, 1` takes one -- and a
reader who typed `SPRSHAPE A$, 1` would have had every reason to. Both names, and
RSPHIT, were grepped against every label in docs/, examples/ and both corpora
first: a bare word is a label here, so a verb and a label share one namespace and
taking a name a checked-in listing already uses would break it silently.
`SPRHIT n, 0` takes a sprite out of collision while leaving it on the screen --
the ghost, the flashing invulnerable player, the pickup already taken. Hiding it
with `SPRITE n, 0` stops it colliding too, and is what you want when it should
not be seen either.
The circle answers the complaint chapter 8 already ships a figure of. That figure
shows two discs whose *boxes* touch at a corner while the artwork is nowhere
near, and `BUMP(1)` reporting a collision; two `SPRHIT n, 2` and it stops. The
test asserts both halves so the figure's caption stays true.
`tests/verbs_table.c` caught RSPHIT filed after RSPPOS rather than before it,
which is the sorted-table test doing exactly the job it exists for.
Docs: a new section in chapter 8, rows in the verb and function references in
alphabetical order, and chapter 13's "collision is by bounding box" becomes
"collision is by shape" with the addition named. 111 with akgl, 110 without, and
the artwork breakout still runs clean.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-02 10:01:33 -04:00
| `SPRHIT` | `SPRHIT n, kind [,x1, y1, x2, y2]` | Give a sprite a collision shape. Kind 0 none, 1 box, 2 circle, 3 or 4 capsule. No rectangle fits the frame. See Chapter 8. |
2026-07-31 21:50:50 -04:00
| `SPRITE` | `SPRITE n [,on] [,col] [,...]` | Configure a sprite. Omitted arguments are left alone. |
| `SPRSAV` | `SPRSAV source, n` | Give sprite `n` a picture. Three source forms; see Chapter 8. |
| `SSHAPE` | `SSHAPE A$, x1, y1 [,x2, y2]` | Save a screen region; `A$` receives a handle. |
| `STASH` | `STASH count, from, to` | Copy bytes. The same as `FETCH` . |
| `STOP` | `STOP` | Stop the program; `CONT` resumes it. |
| `SWAP` | `SWAP A, B` | Exchange two variables of the same type. |
| `SYS` | `SYS addr` | **Refused. ** There is no 6502 and no ROM to call. |
| `TEMPO` | `TEMPO n` | How fast `PLAY` releases its queue. |
| `TRAP` | `TRAP [target]` | Send errors to a handler. No target disarms it. |
| `TROFF` | `TROFF` | Turn line tracing off. |
| `TRON` | `TRON` | Turn line tracing on; each line prints its number in brackets. |
Document structures: a chapter, the architecture, and the differences
docs/16-structures.md is the feature: records, nesting, copy-on-assign, strict
pointers, lists, what is checked and what is not, and how a host shares its own
C structs. Every example in it is executed by docs_examples and byte-compared,
including the refusals -- so a message that changes fails the suite rather than
quietly making the chapter wrong.
The chapter makes one contrast explicitly, because it is the question a reader
will actually have: a misspelled *field* is refused and a misspelled *variable*
still prints zero. The rule underneath is that what the program declared gets
checked and what it did not gets shrugged at -- a variable's name is never
declared, a TYPE's field list is. Structures end up the strictest thing in the
language, not from a higher standard but because they are the only named thing
whose valid spellings are written down.
Chapter 14 gains the layout: an instance is a contiguous run of value slots with
a diagram of where the fields sit, the three-pass prescan and why each pass
exists, why the copy cannot live in akbasic_value_clone(), and why the render
depth bound is four rather than eight. Chapter 3 gains the @ suffix, chapter 13
records that all of this is an addition BASIC 7.0 has nothing like, and the verb
reference gains TYPE, POINT and DIM ... AS.
MAINTENANCE.md gains the two rules that are on a maintainer rather than on a
test: a structure copy must not go through clone, and a field chain gets its own
leaf field. TODO.md section 5 records what was invented and the three limits
that are ours, and section 8 records the two defects the work exposed.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-01 12:03:02 -04:00
| `TYPE` | `TYPE NAME` … `END TYPE` | Declare a record, its fields one per line. See Chapter 16. |
Give BASIC menus, dialogs and HUD labels over libakgl's UI helpers
Group K, and the first verbs to reach the akgl_ui subsystem 0.9.0 brought
in: MENU and GETMENU and RMENU, DIALOG, HUD and UISTYLE. A program that
wanted a title screen had to draw one out of CHAR and GETKEY, which is
what both breakout tutorials make a reader do.
The interesting part is the impedance mismatch. libakgl's UI is immediate
mode -- widgets are re-declared inside a frame bracket every frame and
clay borrows their text until the bracket closes -- and a BASIC program
says MENU 1, "START" on line 100 and expects it up on line 900, several
hundred frames later. So src/ui_akgl.c is retained on this side and
immediate on that one: the record's entry points are setters that copy
into akbasic_AkglUi, and akbasic_ui_akgl_render() replays the whole set
once a frame from the host's pump. No BASIC string, which lives in the
per-line value pool, is ever what clay is handed.
The shapes are borrowed rather than invented. MENU retires the way SOLID
does -- no entries retires one, no arguments retire them all. GETMENU
holds the step loop the way GETKEY does, so parking is not blocking: the
step still returns, the host keeps its frame rate, and the sprite, audio
and collision services keep running underneath because they run before
the blocking checks. RMENU(n,1) reads and clears the way BUMP() does.
Withdrawing the device or retiring the menu releases a holding GETMENU
with 0 rather than wedging the script, which is akbasic_input_service()'s
rule for a withdrawn keyboard.
One thing a program has to know, and docs/19-user-interface.md says it
twice: a menu that is up owns the cursor keys and Return. It has to, and
retiring it gives them back -- forget the MENU n before an INPUT and the
INPUT never sees the Return that ends it.
akbasic_runtime_set_ui() is its own function rather than a fifth argument
to akbasic_runtime_set_devices(), whose signature has twenty-eight call
sites in tests and documentation that are about something else.
deps/libakgl is not touched. akgl_UiAnchor has the four corners and dead
centre, so HUD offers exactly those five; TODO.md records what a
top-centre and bottom-centre would cost upstream, along with the three
other things this deliberately leaves out. No new error code either --
DEVICE, BOUNDS, SYNTAX and TYPE cover the group, and 520 stays free.
tools/screenshot.c had to learn that "needs a font" and "draws the text
grid" are two questions. They were one, and a UI figure came out black:
the text layer owns every pixel of the rows it covers and painted over
the widgets. The new ui=1 fence attribute asks for the first without the
second; MAINTENANCE.md documents it.
112/112 in both configurations, 112/112 under ASan and UBSan, coverage
94.1% against the 90% gate with src/runtime_ui.c at 99% of lines and
100% of functions, doxygen clean, and the four new figures byte-identical
on a re-render. TODO.md section 8's gate table was stale on several
counts besides these and is refreshed with measured numbers.
Co-Authored-By: Tachikoma (Claude Code Opus 5 1M) <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-02 18:37:10 -04:00
| `UISTYLE` | `UISTYLE [fill, edge, ink [,pad [,radius]]]` | The one look every widget draws with. No arguments restores the default. See Chapter 19. |
2026-07-31 21:50:50 -04:00
| `VERIFY` | `VERIFY "name"` | Compare the program in memory against a file. |
| `VOL` | `VOL n` | Set the overall volume, 0 to 15. |
| `WAIT` | `WAIT addr, mask [,xor]` | Poll a byte until it matches. Holds the program. |
| `WIDTH` | `WIDTH 1|2` | How thick a drawn line is. |
| `WINDOW` | `WINDOW l, t, r, b [,clear]` | Constrain the text area. Needs a sink with a grid. |
## Words that are not verbs
`AND` , `ELSE` , `NOT` , `OR` , `REM` , `STEP` , `THEN` , `TO` , `UNTIL` , `USING` and `WHILE`
are reserved, but none of them is a statement on its own — each is consumed by the verb
it belongs to.
## Deliberately absent
`BANK` , `FAST` , `MONITOR` and `SPRDEF` have no table entry at all. The first three are
incompatible with a modern machine — there is no bank switching, no CPU speed to
control, and no machine-language monitor to drop into. `SPRDEF` is an interactive
full-screen editor rather than a programmable verb.
