andrew/akbasic

Fork 0

Files

Ishikawa 2cb68665d0

akbasic CI Build / cmake_build (push) Successful in 3m26s

Details

akbasic CI Build / coverage (push) Successful in 4m0s

Details

akbasic CI Build / sanitizers (push) Successful in 6m33s

Details

akbasic CI Build / akgl_build (push) Successful in 9m32s

Details

akbasic CI Build / mutation_test (push) Successful in 18m47s

Details

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

10 KiB

Raw Permalink Blame History

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`.
`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.
`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.
`COLLISION`	`COLLISION type [,target]`	Call a subroutine when sprites collide. No target disarms it.
`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`.
`DIALOG`	`DIALOG ["text"]`	Show a text panel across the bottom of the screen. No argument takes it down. See Chapter 19.
`DIM`	`DIM A#(n [,...])`	Make an array. Subscripts start at zero; `n` is the count.
`DIM` … `AS`	`DIM S@ AS T`, `DIM P@ AS PTR TO T`	Make a structure, or a strict pointer to one. See Chapter 16.
`DIRECTORY`	`DIRECTORY`	Refused. Not written yet; the standard-library wrapper it waited on has landed.
`DLOAD`	`DLOAD "name"`	Load a program from a file.
`DO`	`DO [WHILE c	UNTIL c]`,` DO EACH V IN gen(args)`
`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`.
`EMIT`	`EMIT expr`	Yield one value from a `GEN` body. Only valid inside one; see Chapter 4.
`END`	`END`	Stop the program. Does not arm `CONT`.
`END GEN`	`END GEN`	Close a `GEN` body, the way `RETURN` closes a multi-line `DEF`.
`ENVELOPE`	`ENVELOPE n, a, d, s, r`	Define one of `PLAY`'s ten envelope presets.
`EXIT`	`EXIT`	Leave the innermost `FOR`, `FOR EACH`, `DO` or `DO EACH` loop.
`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.
`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.
`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.
`GETMENU`	`GETMENU n, V%`	Wait for a menu choice, holding the program but not the host. Assigns the entry number. See Chapter 19.
`GOSUB`	`GOSUB line`	Call a subroutine, returning on `RETURN`.
`GOTO`	`GOTO line`	Jump to a line or a label.
`GRAPHIC`	`GRAPHIC mode	CLR`
`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.
`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.
`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.
`LOOP`	`LOOP [WHILE c	UNTIL c]`
`MENU`	`MENU [n [,"item", ...]]`	Show a menu the player picks from. No entries retires it; no arguments retire them all. See Chapter 19.
`MOVSPR`	`MOVSPR n, ...`	Move a sprite. Four forms; see Chapter 8.
`NEW`	`NEW`	Erase the program and every variable.
`NEXT`	`NEXT V`	End a `FOR` loop and advance its counter, or resume a `FOR EACH` for its next value.
`ON`	`ON e GOTO	GOSUB t [,...]`
`PAINT`	`PAINT src, x, y`	Flood-fill the region containing a point.
`PLAY`	`PLAY "notes"`	Queue notes. Does not block.
`POINT`	`POINT P@ AT s@`	Aim a strict pointer at a structure. See Chapter 16.
`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`	`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.
`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.
`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.
`SOUND`	`SOUND v, freq, dur [,...]`	Play a tone on a voice. Does not block.
`SPRCOLOR`	`SPRCOLOR [c1] [,c2]`	Set the two shared multicolour registers.
`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.
`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.
`TYPE`	`TYPE NAME` … `END TYPE`	Declare a record, its fields one per line. See Chapter 16.
`UISTYLE`	`UISTYLE [fill, edge, ink [,pad [,radius]]]`	The one look every widget draws with. No arguments restores the default. See Chapter 19.
`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`
`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.

10 KiB Raw Permalink Blame History

11. Verb reference

Words that are not verbs

Deliberately absent

10 KiB

Raw Permalink Blame History