Andrew Kesterson
cdaefcc941
Some checks failed
akbasic CI Build / cmake_build (push) Successful in 3m0s
akbasic CI Build / sanitizers (push) Successful in 3m45s
akbasic CI Build / coverage (push) Failing after 3m22s
akbasic CI Build / akgl_build (push) Failing after 21s
akbasic CI Build / mutation_test (push) Successful in 11m26s
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>
57 lines
3.1 KiB
Markdown
57 lines
3.1 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. |
|
|
| `RIGHT` | 2 | `RIGHT(A$, n)` | The rightmost `n` characters. Clamped. |
|
|
| `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.
|