andrew/akbasic
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Finish the language: every remaining verb group, and the defects that blocked them

Browse Source 
Closes groups A, C, D, E, F, H and J of TODO.md section 4, plus RESTORE and
RENUMBER, and closes section 6 -- all seventeen reference defects. Seven of
those turned out to have been fixed or never ported and nobody had written it
down; the audit records the evidence for each.

Two of the seventeen were real. math_plus mutated its left operand when the
operand was mutable, so A# + 1 could modify A#; it was gated on FOR/NEXT
coverage because NEXT relied on the mutation, so tests/for_next.c came first
and NEXT now writes the counter back itself. And the binary operators summed
both numeric fields of their right operand, which no BASIC program can reach
-- that one needed a test written against the value API.

Writing the tests turned up eight defects nobody had listed. Seven are fixed:

  IF A = 2 THEN was a parse error; only == worked
  IF ... AND ... was a parse error, because a condition parsed as one relation
  IF A = 1 OR B = 2 THEN was silently always false, and so was IF A THEN
  EXIT before any NEXT restarted the program and exhausted the variable pool
  READ never found a DATA line above it, and swallowed the lines between
  PRINT 2 + 2 at the prompt was filed as program text instead of answering
  a short read discarded its bytes, so COPY produced empty files
  every verb taking an argument list said "peek() returned nil token!" on none

The eighth is not fixed and cannot be quietly: a FOR whose step overshoots
runs its body one extra time, and FOR I = 1 TO 1 runs it zero times. The two
errors cancel for a step of 1, which is why neither was noticed. Correcting
them changes the expected output of a checked-in acceptance file, and
tests/reference/README.md forbids editing one to suit this interpreter. It is
tests/for_semantics.c in AKBASIC_KNOWN_FAILING_TESTS, asserting the correct
contract, and TODO.md items 19 and 20.

Sprites are real libakgl actors with a renderfunc of their own, because
akgl_actor_render draws every sprite square and an actor has no per-axis
scale. Both are filed upstream. SPRSAV takes an image file, an SSHAPE handle
or a 63-element integer array -- a string here cannot hold a zero byte.

Verbs that need hardware that does not exist are refused by name with the
reason rather than faked: SYS, HEADER, COLLECT, BACKUP, BOOT, FILTER, and
DIRECTORY, which is refused for a missing libakstdlib wrapper filed upstream.

94 tests in the default build, 93 with SDL, 94 under ASan and UBSan, doxygen
clean. The Go acceptance corpus stayed green throughout.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Andrew Kesterson
2026-07-31 21:50:37 -04:00
parent 3aade4947a
commit 9845e77a5c
87 changed files with 11024 additions and 325 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
README.md
View File

@@ -102,6 +102,14 @@ The Go project is deprecated and will not be updated, so the two are **no longer
That corpus lives at [`tests/reference/`](tests/reference/README.md), copied byte for byte out of the Go project. Its README records where it came from and the rule for changing it: **diverge deliberately, never by accident.** A failure there means this interpreter's behaviour changed — nine times in ten that is a bug you just introduced, and the tenth time it is an improvement that should move the expectation, say why, and add a line to `TODO.md` §5.
## The guide
A full multi-chapter guide lives in [`docs/`](docs/README.md), organised the way the
C128 Programmer's Reference Guide is: the language, then each hardware area, then a
reference section for every verb and function. If you already write BASIC 7.0, start
with [Chapter 13](docs/13-differences.md) — it is the list of everything that behaves
differently here, and why.
## Case Sensitivity
The old computers BASIC was originally written on only had CAPITAL LETTER KEYS on their keyboards. Modern keyboards have the indescribable luxury of upper and lower case. In this basic, verbs and function names are case insensitive. Variable names are case sensitive.
@@ -140,6 +148,10 @@ Expressions can be grouped with `()` arbitrarily deeply. Currently the interpret
The following commands/verbs are implemented:
* `AUTO n` : Turn automatic line numbering on/off at increments of `n`
* `COLLISION t [, line-or-label]` : Call a subroutine when sprites collide. Type 1 only;
omitting the target disarms it. The handler is entered between source lines and must end in
`RETURN`, exactly as a `GOSUB` body does. Types 2 (sprite-to-background) and 3 (light pen)
are refused by name
* `REM` : everything after this is a comment
* `DATA LITERAL[, ...]`: Define a series of literal values that can be read by a preceding `READ` verb
* `DEF FN(X, ...) = expression` : Define a function with arguments that performs a given expression. See also "Subroutines", below.
@@ -182,6 +194,26 @@ The following commands/verbs are implemented:
* `RETURN` : return from `GOSUB` to the point where it was called
* `RUN [n]`: Run the program currently in memory, optionally starting at line `n`
* `STOP`: Stop program execution at the current point. `CONT` resumes from there
* `MOVSPR n, ...` : Move a sprite. Four forms, and the separators are what tell them apart:
* `MOVSPR n, x, y` — put it at (x, y) in BASIC's 320x200 space
* `MOVSPR n, +x, -y` — move it *by* that much; a signed coordinate is an offset
* `MOVSPR n, d ; a` — move it `d` pixels along bearing `a`, in degrees clockwise from
straight up. Distance first, then angle
* `MOVSPR n, a # s` — set it moving along bearing `a` at speed `s` (0-15, 0 stops). Nothing
moves on the statement itself: the sprite moves as the program runs, paced off the host's
clock
* `SPRCOLOR [c1] [, c2]` : Set the two colour registers every multicolour sprite shares. Either
may be omitted, which leaves that register alone
* `SPRITE n [,on] [,colour] [,priority] [,xexpand] [,yexpand] [,multicolour]` : Configure a
sprite. Only the number is required, and an omitted argument leaves that attribute alone
* `SPRSAV source, n` : Give sprite `n` an image. Three kinds of source:
* `SPRSAV "ship.png", n` — an image file. Tried against the working directory first and then
against the directory the running program was loaded from, so a program stored beside its
art works from anywhere. The sprite takes the image's own size
* `SPRSAV A$, n` — a region `SSHAPE` saved
* `SPRSAV A#, n` — 63 elements of a DIMmed integer array, three bytes per row and twenty-one
rows, most significant bit leftmost. This is the `DATA`-driven form; it takes an integer
array rather than a string because a string here cannot hold a zero byte
* `SWAP A, B`: Exchange two variables of the same type, arrays and their dimensions included
* `TRON` / `TROFF`: Turn line tracing on and off. A traced program prints `[10][20]` inline
ahead of each line, as a C128 does
@@ -195,6 +227,7 @@ The following functions are implemented
* `ABS(x#|x%)`: Return the absolute value of the float or integer argument
* `ATN(x#|x%)`: Return the arctangent of the float or integer argument. Input and output are in radians.
* `BUMP(1)`: Return a bitmask of which sprites have collided since the last call — bit 0 is sprite 1. **Reading clears it**, which is what makes "has anything hit me since I last looked" answerable at all. Type 1 (sprite-to-sprite) only
* `CHR(x#)`: Return the character value of the UTF-8 unicode codepoint in x#. Returns as a string.
* `COS(x#|x%)`: Return the cosine of the float or integer argument. Input and output are in radians.
* `HEX(x#)`: Return the string representation of the integer number in x#
@@ -208,6 +241,9 @@ The following functions are implemented
* `POINTER(X)`: Return the address in memory for the value of the variable identified in X. This is the direct integer, float or string value stored, it is not a reference to the internal variable structure.
* `POINTERVAR(X)` : Return the address in memory of the variable X. This is the address of the internal `akbasic_Variable` structure, which includes additional metadata about the variable, in addition to the value. For a pointer directly to the value, use `POINTER`.
* `RAD(X#|X%)`: Convert degrees to radians
* `RSPCOLOR(F#)`: Return one of `SPRCOLOR`'s two shared registers — 1 or 2
* `RSPPOS(N#, F#)`: Return sprite `N#`'s x (0), y (1) or speed (2)
* `RSPRITE(N#, F#)`: Return one of sprite `N#`'s `SPRITE` settings, in `SPRITE`'s own argument order: enabled (0), colour (1), priority (2), x-expand (3), y-expand (4), multicolour (5)
* `RIGHT(X$, Y#)`: Return the rightmost Y# characters of the string in X$. Y# is clamped to LEN(X$).
* `SGN(X#)`: Returns the sign of X# (-1 for negative, 1 for positive, 0 if 0).
* `SHL(X#, Y#)`: Returns the value of X# shifted left Y# bits
@@ -415,7 +451,11 @@ target_link_libraries(YOUR_GAME PRIVATE akbasic::akbasic)
Both are off by default, which is why the interpreter and its whole test suite build on a machine with no SDL.
The graphics, sound and console verbs reach hardware through records of function pointers on the runtime — `akbasic_GraphicsBackend`, `akbasic_AudioBackend` and `akbasic_InputBackend`, attached with `akbasic_runtime_set_devices()`. All three may be `NULL`, which is what a default build of the standalone driver gives them: a verb that needs a device it was not given raises rather than crashing, and a `PRINT`-only program never notices. An SDL build attaches all three. A host that renders some other way supplies its own records and never links `libakgl` at all.
The graphics, sound, console and sprite verbs reach hardware through records of function pointers on the runtime — `akbasic_GraphicsBackend`, `akbasic_AudioBackend`, `akbasic_InputBackend` and `akbasic_SpriteBackend`, attached with `akbasic_runtime_set_devices()`. All four may be `NULL`, which is what a default build of the standalone driver gives them: a verb that needs a device it was not given raises rather than crashing, and a `PRINT`-only program never notices. An SDL build attaches all four. A host that renders some other way supplies its own records and never links `libakgl` at all.
**Sprites are real `libakgl` actors.** Each of BASIC's eight becomes a `SpriteSheet`, a `Sprite`, a `Character` and an `Actor` registered in `AKGL_REGISTRY_ACTOR`, so a host game sees a script's sprites alongside its own and can do anything to them it can do to an actor. `akbasic_sprite_akgl_render()` draws them; a host that never calls it gets a script whose sprite state is correct and whose sprites are never drawn. None of it goes through libakgl's sprite JSON — a Commodore sprite has no frame list, no animation speed and no state map — except for `SPRSAV "ship.png", n`, which resolves and loads through exactly the calls the JSON loader makes.
If you drive the interpreter without `akbasic_frontend_akgl_init()`, sprites need three things from you that `akgl_game_init()` would otherwise have done: `akgl_heap_init()`, `akgl_registry_init()`, and a `camera` pointing somewhere. `akgl_actor_render()` dereferences that global without checking it. `src/frontend_akgl.c` is the worked example.
Two things about those verbs that differ from a real C128, because both would otherwise surprise you. `PLAY` does not block — it queues its notes and `akbasic_runtime_step()` releases them against whatever time you last passed to `akbasic_runtime_settime()`, so the statement after a `PLAY` runs immediately. And `GETKEY` holds the program without blocking you: the step still returns, it simply does not advance until a key arrives.
@@ -455,40 +495,56 @@ Plus six more the original already carried: a leading `0` selects base 8, so `PR
## Not implemented
* Multiple statements on one line (e.g. `10 PRINT A$ : REM This prints the thing`). The `COLON` token exists and nothing consumes it.
* Using an array reference inside a parameter list (e.g. `READ A$(0), B#`) results in parsing errors
* `APPEND`, `BACKUP`, `BEGIN`, `BEND`, `BLOAD`, `BOOT`, `BOX`, `BSAVE`
* `CATALOG`, `CHAR`, `CIRCLE`, `CLOSE`, `CLR`, `CMD`, `COLLECT`, `COLLISION`, `COLOR`, `CONCAT`, `CONT`, `COPY`
* `DCLEAR`, `DCLOSE`, `DIRECTORY`, `DOPEN`, `DRAW`, `DVERIFY`
* `DO`, `LOOP`, `WHILE`, `UNTIL`. You can do the same thing with `IF` and `GOTO`.
* `END`, `ENVELOPE`, `ER`, `ERR`
* `FETCH`, `FILTER`
* `GET`, `GETKEY`, `GRAPHIC`, `GSHAPE`
* `HEADER`, `HELP`
* `KEY`, `LOAD`, `LOCATE`
* `MOVSPR`, `NEW`, `ON`, `PAINT`, `PLAY`, `PUDEF`
* `RENAME`, `RENUMBER`, `RESTORE`, `RESUME`
* `SAVE`, `SCALE`, `SCNCLR`, `SCRATCH`, `SLEEP`, `SOUND`
* `SPRCOLOR`, `SPRDEF`, `SPRITE`, `SPRSAV`, `SSHAPE`, `STASH`, `SWAP`, `SYS`
* `TEMPO`, `TI`, `TRAP`, `TROFF`, `TRON`
* `USING`, `VERIFY`, `VOL`, `WAIT`, `WIDTH`, `WINDOW`
This list was checked against the dispatch table in `src/verbs.c` when it was last edited. It
had drifted badly before that -- it named a third of the language as missing after it had
landed -- so check it the same way rather than trusting it.
* `APPEND`, `BACKUP`, `BLOAD`, `BOOT`, `BSAVE`
* `BEGIN`, `BEND`, `DO`, `LOOP`, `WHILE`, `UNTIL`, `END`, `ON`. You can do the same thing with `IF` and `GOTO`.
* `CATALOG`, `CHAR`, `CLOSE`, `CMD`, `COLLECT`, `CONCAT`, `COPY`
* `DCLEAR`, `DCLOSE`, `DIRECTORY`, `DOPEN`, `DVERIFY`
* `ER`, `ERR`, `TRAP`, `RESUME`
* `FETCH`, `STASH`, `SYS`
* `HEADER`, `KEY`, `LOAD`, `SAVE`, `SCRATCH`, `RENAME`, `VERIFY`
* `PUDEF`, `RENUMBER`, `RESTORE`
* `SLEEP`, `TI`, `WAIT`, `WIDTH`, `WINDOW`, `USING`
* `SPRDEF`
* The I/O-channel variants (`GETIO`, `INPUTIO`, `OPENIO`, `PRINTIO`, `RECORDIO`)
One of those is still blocked on a missing `libakgl` capability, and it is only one. Four were — text measurement, immediate-mode drawing, audio, and a non-blocking keystroke read — and rather than work around them here they were filed in [`deps/libakgl/TODO.md`](deps/libakgl/TODO.md) under "API gaps blocking akbasic". All four have since landed upstream (`akgl_text_measure`, the `akgl_draw_*` family, `akgl_audio_*`, and `akgl_controller_poll_key`), so what is left is akbasic-side work.
`FILTER` parses and is then refused, which is a third state and deliberate. It sets the SID's
filter cutoff, band switches and resonance; `akgl_audio_*` synthesises raw waveforms and mixes
them, there is no filter stage to configure, and SDL3 supplies no primitive to build one from.
Until an `akgl_audio_filter()` exists it refuses at execution rather than being silently
ignored -- a program that asks for a low-pass and gets an unfiltered square wave has been lied
to.
The exception is `FILTER`, which sets the SID's filter cutoff, band switches and resonance. `akgl_audio_*` synthesises raw waveforms and mixes them; there is no filter stage to configure, and SDL3 supplies no primitive to build one from. Until an `akgl_audio_filter()` exists, `FILTER` parses and then refuses at execution rather than being silently ignored — a program that asks for a low-pass and gets an unfiltered square wave has been lied to.
It is the only verb still blocked on a missing `libakgl` capability. Four others were -- text
measurement, immediate-mode drawing, audio, and a non-blocking keystroke read -- and rather
than work around them here they were filed in
[`deps/libakgl/TODO.md`](deps/libakgl/TODO.md) under "API gaps blocking akbasic". All four have
since landed upstream (`akgl_text_measure`, the `akgl_draw_*` family, `akgl_audio_*`, and
`akgl_controller_poll_key`), so what is left is akbasic-side work.
Building the sprite verbs turned up three more, none of which blocks a verb. An actor is drawn
square regardless of its sprite's height (libakgl's own defect 26) and an actor cannot be scaled
per axis (filed from here); both are worked around by installing a `renderfunc` of ours on each
actor. The third — an error context leaked per relative asset path resolved — was found and
fixed upstream in 0.4.0 while this was being written.
## Deliberately out of scope
* `BANK` - the modern PC memory layout is incompatible with the idea of bank switching
* `FAST` - Irrelevant on modern PC CPUs
* `MONITOR` - there is no machine-language monitor to drop into
* `SPRDEF` - an interactive full-screen sprite editor driven by single keystrokes, not a
programmable verb. A program cannot call it usefully and this interpreter does not own the
screen it would take over. `SPRSAV`'s three source forms are what replace it
# Dependencies
* [libakerror](https://source.starfort.tech/andrew/libakerror) 1.0.0 — TRY/CATCH-style error contexts. Every function that can fail returns one.
* [libakstdlib](https://source.starfort.tech/andrew/libakstdlib) 0.2.0 — libc wrappers that report through `libakerror`.
* [libakgl](https://source.starfort.tech/andrew/libakgl) 0.3.0 — **optional**, only for `-DAKBASIC_WITH_AKGL=ON`. Pulls in SDL3. 0.3.0 closed every API gap this project had filed against it, so there are no libakgl workarounds left here.
* [libakgl](https://source.starfort.tech/andrew/libakgl) 0.4.0 — **optional**, only for `-DAKBASIC_WITH_AKGL=ON`. Pulls in SDL3. 0.3.0 closed every API gap this project had filed against it; 0.4.0 is a leak-and-overread release. It changed no public struct, but the soname carries `MAJOR.MINOR` while the major is 0, so rebuild rather than relink.
* [basicinterpret](https://source.starfort.tech/andrew/basicinterpret) — the Go original. Vendored as the behavioural spec for questions about semantics, and for nothing else: its acceptance corpus and its Commodore font are checked in here now, so **the build and the test suite do not need it**. Not linked, not built, and safe to omit.
Everything is a submodule; `git submodule update --init --recursive` gets all of it. There is nothing to install first.