Andrew Kesterson
737fdc760f
ER# held numbers nothing explained. The appendix lists the four error classes the interpreter prints, the eight codes it owns and what raises each, and the codes that reach ER# from errno, libakerror and libakgl underneath it. The table is not asserted. A program in the chapter trips seven of the eight and prints what it got, and docs_examples byte-compares the result -- so the numbers are checked rather than claimed. The eighth, 516, is not usefully trappable and the chapter says why: entering a handler takes a scope, and the pool being empty is what raised it. Two things worth a reader's attention came out of writing it. Two codes register the same ERR() text, so a program must compare the number and print the text. And VAL reports libakerror's Value Error rather than the interpreter's 517, which makes that number the platform's rather than ours -- filed as section 6 item 21, not fixed here, because deciding which libakstdlib failures to translate is a boundary question and ENOENT out of DOPEN is the counter-case. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
59 lines
3.3 KiB
Markdown
59 lines
3.3 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), or the drawing surface's width (1) or height (2) in pixels. |
|
|
| `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. **[Chapter 15](15-error-codes.md)
|
|
lists every value it can hold.**
|