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
63 lines
3.9 KiB
Markdown
63 lines
3.9 KiB
Markdown
# 12. Function reference
|
|
|
|
Every function, alphabetically, generated from the interpreter's own dispatch table.
|
|
|
|
A function is called with parentheses and yields a value; it cannot stand alone as a
|
|
statement. The arity column is how many arguments it takes — the interpreter checks it,
|
|
so a call with the wrong number is a syntax error rather than a surprise.
|
|
|
|
| Function | Args | Form | What it gives |
|
|
|---|---|---|---|
|
|
| `ABS` | 1 | `ABS(n)` | The absolute value of an integer or float. |
|
|
| `ATN` | 1 | `ATN(n)` | Arctangent, in radians. |
|
|
| `BUMP` | 1 | `BUMP(1)` | Which sprites have collided, as a bitmask. **Reading clears it.** |
|
|
| `CHR` | 1 | `CHR(n)` | The character for a Unicode code point, as a string. |
|
|
| `COS` | 1 | `COS(n)` | Cosine, in radians. |
|
|
| `ERR` | 1 | `ERR(n)` | The message text for an error code. `ERR(ER#)` names the last one. |
|
|
| `HEX` | 1 | `HEX(n)` | An integer as hexadecimal text. |
|
|
| `INSTR` | 2 | `INSTR(A$, B$)` | Where `B$` appears in `A$`, counting from zero, or -1. |
|
|
| `LEFT` | 2 | `LEFT(A$, n)` | The leftmost `n` characters. Clamped to the string's length. |
|
|
| `LEN` | 1 | `LEN(x)` | The length of a string, or the element count of an array. |
|
|
| `LOG` | 1 | `LOG(n)` | Natural logarithm. |
|
|
| `MID` | 3 | `MID(A$, start, len)` | A substring, counting from zero. |
|
|
| `MOD` | 2 | `MOD(a, b)` | The remainder of `a / b`. Integers only. |
|
|
| `PEEK` | 1 | `PEEK(addr)` | The byte at a real address. |
|
|
| `POINTER` | 1 | `POINTER(V)` | The address of a variable's value. |
|
|
| `POINTERVAR` | 1 | `POINTERVAR(V)` | The address of the variable structure itself, metadata included. |
|
|
| `RAD` | 1 | `RAD(n)` | Degrees converted to radians. |
|
|
| `RCOLLISION` | 2 | `RCOLLISION(n, f)` | What sprite `n` last collided with and how: what, which, the normal, the depth, the point, and which axis to reverse. See Chapter 8. |
|
|
| `RGR` | 1 | `RGR(f)` | The `GRAPHIC` mode (0), the drawing surface's width (1) or height (2) in pixels, or a character cell's width (3) or height (4). |
|
|
| `RIGHT` | 2 | `RIGHT(A$, n)` | The rightmost `n` characters. Clamped. |
|
|
| `RMENU` | 2 | `RMENU(n, f)` | A menu's state: field 0 the highlighted entry, field 1 whether it has been confirmed. **Reading field 1 clears it.** |
|
|
| `RWINDOW` | 1 | `RWINDOW(f)` | The current text window's rows (0) or columns (1). Field 2 is a C128 screen mode and is refused. |
|
|
| `RSPCOLOR` | 1 | `RSPCOLOR(n)` | One of `SPRCOLOR`'s two shared registers, 1 or 2. |
|
|
| `RSPHIT` | 2 | `RSPHIT(n, f)` | One of `SPRHIT`'s settings for sprite `n`, in `SPRHIT`'s own argument order: 0 the kind, 1 to 4 the two corners. |
|
|
| `RSPPOS` | 2 | `RSPPOS(n, f)` | A sprite's x (0), y (1) or speed (2). |
|
|
| `RSPRITE` | 2 | `RSPRITE(n, f)` | One of a sprite's `SPRITE` settings, in `SPRITE`'s argument order. |
|
|
| `SGN` | 1 | `SGN(n)` | -1, 0 or 1 according to the sign. |
|
|
| `SHL` | 2 | `SHL(n, bits)` | Shift left. |
|
|
| `SHR` | 2 | `SHR(n, bits)` | Shift right. |
|
|
| `SIN` | 1 | `SIN(n)` | Sine, in radians. |
|
|
| `SPC` | 1 | `SPC(n)` | A string of `n` spaces. |
|
|
| `STR` | 1 | `STR(n)` | A number as a string. |
|
|
| `TAN` | 1 | `TAN(n)` | Tangent, in radians. |
|
|
| `VAL` | 1 | `VAL(A$)` | A string as a number. Refuses text that is not one. |
|
|
| `XOR` | 2 | `XOR(a, b)` | Bitwise exclusive or. |
|
|
|
|
## Reserved variables
|
|
|
|
Two things a C128 exposes as bare names are ordinary global variables here, because
|
|
this dialect has no variable name without a type suffix:
|
|
|
|
| Here | On a C128 | Holds |
|
|
|---|---|---|
|
|
| `ER#` | `ER` | the code of the last trapped error |
|
|
| `EL#` | `EL` | the line it happened on |
|
|
| `TI#` | `TI` | jiffies — sixtieths of a second — since the host's clock started |
|
|
| `TI$` | `TI$` | the same time as `HHMMSS` |
|
|
|
|
`ER#` carries this interpreter's error code, not a Commodore error number. There is no
|
|
correspondence to reproduce — the errors raised here are not the errors a 1985 ROM
|
|
raised — so print `ERR(ER#)` rather than the number. **[Chapter 15](15-error-codes.md)
|
|
lists every value it can hold.**
|