2026-07-31 21:50:50 -04:00
|
|
|
# 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. |
|
Draw into the whole window, not its top-left 320x200
The graphics verbs documented a coordinate transform that did not exist. With
SCALE off a coordinate went straight to akgl_draw_* as a pixel address, so an
800x600 window drew a C128 listing into its corner and left the rest unused --
while the chapter said coordinates were 320x200 and stretching to fit was the
host's business.
akbasic_GraphicsBackend gains a size entry point, require_graphics() asks it
before every verb that draws so a resized window is honoured between two
statements, and 320x200 becomes the fallback for a backend that leaves it NULL.
It is the record's one optional member, so a host written against the old header
keeps the behaviour it had.
SCALE now maps onto the device, and RGR(1)/RGR(2) report the drawing surface so
a program can use a window whose size it did not choose. RGR(0) is BASIC 7.0's
own field, the GRAPHIC mode.
SCALE also mapped xmax onto the width rather than onto the last pixel, so
SCALE 1, 319, 199 followed by DRAW 1, 319, 199 drew nothing at all -- one pixel
past the surface. Fixed in the same line, because it is what makes "SCALE gives
a C128 listing the whole window" true rather than nearly true.
The akgl test renders against a 128x128 target, deliberately smaller than the
old constants: a SCALE still dividing by them misses it entirely rather than
landing somewhere plausible.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-01 07:35:20 -04:00
|
|
|
| `RGR` | 1 | `RGR(f)` | The `GRAPHIC` mode (0), or the drawing surface's width (1) or height (2) in pixels. |
|
2026-07-31 21:50:50 -04:00
|
|
|
| `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
|
Document every error code a script can see, as chapter 15
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>
2026-08-01 07:36:36 -04:00
|
|
|
raised — so print `ERR(ER#)` rather than the number. **[Chapter 15](15-error-codes.md)
|
|
|
|
|
lists every value it can hold.**
|