andrew/akbasic
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a1dcfcacf37254bb5e430a0bdba17ea366a9e9cc
akbasic/docs/11-verb-reference.md

125 lines
8.5 KiB
Markdown
Raw Normal View History

Write the usage guide as thirteen chapters in docs/ Organised the way the C128 Programmer's Reference Guide is: the language first, then each hardware area, then the reference sections. One markdown file per chapter. The verb and function references are generated from the interpreter's own dispatch table, with an assertion that every row is described, so they cannot drift out of step with what the program accepts. 98 verbs and 30 functions. Every example was run before it was written down, which caught three claims that were wrong: a whole FOR loop on one line prints nothing rather than looping once, MID and INSTR count from zero where a C128 counts from one, and a multi-line DEF returns a value the caller has to assign away. Chapter 13 is the list a BASIC 7.0 programmer needs -- roughly sixty documented differences, including the two known FOR defects and the fact that drawing does not survive a frame. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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>
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. |
Write the usage guide as thirteen chapters in docs/ Organised the way the C128 Programmer's Reference Guide is: the language first, then each hardware area, then the reference sections. One markdown file per chapter. The verb and function references are generated from the interpreter's own dispatch table, with an assertion that every row is described, so they cannot drift out of step with what the program accepts. 98 verbs and 30 functions. Every example was run before it was written down, which caught three claims that were wrong: a whole FOR loop on one line prints nothing rather than looping once, MID and INSTR count from zero where a C128 counts from one, and a multi-line DEF returns a value the caller has to assign away. Chapter 13 is the list a BASIC 7.0 programmer needs -- roughly sixty documented differences, including the two known FOR defects and the fact that drawing does not survive a frame. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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. |
| `COLLISION` | `COLLISION 1 [,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`. |
| `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>
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. |
Write the usage guide as thirteen chapters in docs/ Organised the way the C128 Programmer's Reference Guide is: the language first, then each hardware area, then the reference sections. One markdown file per chapter. The verb and function references are generated from the interpreter's own dispatch table, with an assertion that every row is described, so they cannot drift out of step with what the program accepts. 98 verbs and 30 functions. Every example was run before it was written down, which caught three claims that were wrong: a whole FOR loop on one line prints nothing rather than looping once, MID and INSTR count from zero where a C128 counts from one, and a multi-line DEF returns a value the caller has to assign away. Chapter 13 is the list a BASIC 7.0 programmer needs -- roughly sixty documented differences, including the two known FOR defects and the fact that drawing does not survive a frame. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-07-31 21:50:50 -04:00
| `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. |
| `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. |
| `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. |
| `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. |
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>
2026-08-01 12:03:02 -04:00
| `POINT` | `POINT P@ AT s@` | Aim a strict pointer at a structure. See Chapter 16. |
Write the usage guide as thirteen chapters in docs/ Organised the way the C128 Programmer's Reference Guide is: the language first, then each hardware area, then the reference sections. One markdown file per chapter. The verb and function references are generated from the interpreter's own dispatch table, with an assertion that every row is described, so they cannot drift out of step with what the program accepts. 98 verbs and 30 functions. Every example was run before it was written down, which caught three claims that were wrong: a whole FOR loop on one line prints nothing rather than looping once, MID and INSTR count from zero where a C128 counts from one, and a multi-line DEF returns a value the caller has to assign away. Chapter 13 is the list a BASIC 7.0 programmer needs -- roughly sixty documented differences, including the two known FOR defects and the fact that drawing does not survive a frame. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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. |
| `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. |
| `SOUND` | `SOUND v, freq, dur [,...]` | Play a tone on a voice. Does not block. |
| `SPRCOLOR` | `SPRCOLOR [c1] [,c2]` | Set the two shared multicolour registers. |
| `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>
2026-08-01 12:03:02 -04:00
| `TYPE` | `TYPE NAME` … `END TYPE` | Declare a record, its fields one per line. See Chapter 16. |
Write the usage guide as thirteen chapters in docs/ Organised the way the C128 Programmer's Reference Guide is: the language first, then each hardware area, then the reference sections. One markdown file per chapter. The verb and function references are generated from the interpreter's own dispatch table, with an assertion that every row is described, so they cannot drift out of step with what the program accepts. 98 verbs and 30 functions. Every example was run before it was written down, which caught three claims that were wrong: a whole FOR loop on one line prints nothing rather than looping once, MID and INSTR count from zero where a C128 counts from one, and a multi-line DEF returns a value the caller has to assign away. Chapter 13 is the list a BASIC 7.0 programmer needs -- roughly sixty documented differences, including the two known FOR defects and the fact that drawing does not survive a frame. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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.
Reference in New Issue Copy Permalink