2cb68665d0
All checks were successful
akbasic CI Build / cmake_build (push) Successful in 3m26s
akbasic CI Build / coverage (push) Successful in 4m0s
akbasic CI Build / sanitizers (push) Successful in 6m33s
akbasic CI Build / akgl_build (push) Successful in 9m32s
akbasic CI Build / mutation_test (push) Successful in 18m47s
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>
135 lines
10 KiB
Markdown
135 lines
10 KiB
Markdown
# 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)` | 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. |
|
|
| `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` | 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. |
|
|
| `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]` | End a `DO` loop, including a `DO EACH`. |
|
|
| `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 [,...]` | 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. |
|
|
| `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 from a `TRAP` handler. |
|
|
| `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` | 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.
|