Andrew Kesterson
9151438fad
Some checks failed
akbasic CI Build / cmake_build (push) Failing after 3m23s
akbasic CI Build / sanitizers (push) Failing after 4m36s
akbasic CI Build / coverage (push) Failing after 3m41s
akbasic CI Build / akgl_build (push) Failing after 4m45s
akbasic CI Build / mutation_test (push) Failing after 3m31s
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
132 lines
9.5 KiB
Markdown
132 lines
9.5 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.** Needs a directory-reading wrapper that does not exist yet. |
|
|
| `DLOAD` | `DLOAD "name"` | Load a program from a file. |
|
|
| `DO` | `DO [WHILE c | UNTIL c]` | Start a loop. The condition may be here, on the `LOOP`, or neither. |
|
|
| `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`. |
|
|
| `END` | `END` | Stop the program. Does not arm `CONT`. |
|
|
| `ENVELOPE` | `ENVELOPE n, a, d, s, r` | Define one of `PLAY`'s ten envelope presets. |
|
|
| `EXIT` | `EXIT` | Leave the innermost `FOR` or `DO` 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]` | Start a counted loop, ended by `NEXT`. |
|
|
| `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. |
|
|
| `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. |
|
|
| `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`. |
|
|
| `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.
|