Andrew Kesterson
694b446ce4
`RGR(1)` and `RGR(2)` gave the window in pixels and nothing gave columns, rows or the cell size -- so anything placing a character *and* a sprite at the same spot had to hardcode a number measured by hand against whatever font the host loaded. The Breakout in examples/ does exactly that, `CW# = 16`, and it is the one thing in that listing that breaks on a different font or window. **`RWINDOW` is BASIC 7.0's own answer and had never been implemented here.** `RWINDOW(0)` is the current text window's rows and `RWINDOW(1)` its columns. `RWINDOW(2)` reports a C128's 40 or 80 column screen mode, and this interpreter has neither -- refused by name, because answering 0 would be a plausible lie, which is worse than a refusal that says why. The cell size in pixels is `RGR(3)` and `RGR(4)`, beside the surface's own dimensions rather than on `RWINDOW`. Two reasons: a cell size is a fact about the surface, and `RWINDOW` reports the *window*, so dividing `RGR(1)` by a column count stops being right the moment a program calls `WINDOW`. Both read a new optional `grid` entry point on `akbasic_TextSink` -- columns, rows, cell width, cell height -- implemented by the akgl sink and forwarded by the tee, in the shape `moveto` and `window` already had. NULL everywhere else, so both verbs refuse by name against a sink with no grid. `akbasic_sink_init_ stdio()` clears it for the same reason it now clears the other two. Measured on the standalone build: `RGR(3)` answers 16 and `RWINDOW` answers 50 columns by 37 rows -- the three numbers the Breakout listing had written out as constants -- and `RWINDOW` follows a `WINDOW` call while `RGR(3)` does not. tests/console_verbs.c drives the answers through a stand-in sink with a grid, since the harness sink is stdio and has none; tests/graphics_verbs.c covers the new `RGR` fields, their refusal, and the moved range bound. The `c excerpt=` block in docs/10-embedding.md moves with the header, which is `docs_examples` doing its job. TODO.md section 6 item 31's second half, struck. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
60 lines
3.4 KiB
Markdown
60 lines
3.4 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. |
|
|
| `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. |
|
|
| `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. |
|
|
| `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.**
|