Andrew Kesterson
80b76ad467
Some checks failed
akbasic CI Build / cmake_build (push) Successful in 3m2s
akbasic CI Build / sanitizers (push) Successful in 3m51s
akbasic CI Build / coverage (push) Failing after 3m24s
akbasic CI Build / akgl_build (push) Failing after 20s
akbasic CI Build / mutation_test (push) Has been cancelled
README.md was 577 lines and answered four different questions at once: what
the project is, how to build it, every verb and function in the language, and
how to maintain the test harness. The verb and function lists had already been
written a second time in docs/11 and docs/12, which is how a list of that size
goes stale -- there is no way to notice the two have drifted apart.
README.md is now 150 lines and holds only what somebody evaluating the project
needs: what it is, the quickstart, why it was rewritten in C, the five rules
embedding imposes on the design, the two ways to use it, and where everything
else lives. Technical detail goes to docs/, maintenance to MAINTENANCE.md.
The akbasic_TextSink struct moved to docs/10-embedding.md rather than being
deleted. It was the corpus's only `c excerpt=` block -- the check that caught
the stale struct two commits ago -- so dropping it with the README would have
quietly retired a test. docs/10 also stopped claiming README.md carries the
full API surface and the pool limits, which the trim made false.
CLAUDE.md went from 458 lines to 62, because almost none of it was
agent-specific. The project goals, the Go reference and its architecture, the
dependency version and ABI rules, the four ways an embedded build collides,
the libakerror convention, the error-code range map and the style rules are
all things a maintainer needs, and they are now in MAINTENANCE.md with one
copy to keep true. CLAUDE.md points there and keeps only the rules no test
enforces: tests in the same commit asserting the correct contract, file a
missing dependency capability upstream, do not edit generated output or
tests/reference/, co-author your commits.
Four claims did not survive the move, having gone stale where nothing could
notice:
- "The repository is currently empty apart from its submodules -- no
commits, no source tree, no build files." There are 43 commits.
- libakgl's target_compile_definitions(akerror PUBLIC AKERR_MAX_ERR_VALUE)
at deps/libakgl/CMakeLists.txt:44, described as inert but present. It is
gone; only a historical mention in a comment remains.
- "akbasic_init() claims 512-767." There is no akbasic_init. It is
akbasic_error_register(), called from akbasic_runtime_init().
- Time-relative phrasing ("libakgl hit two of them in the last week").
Five places pointed at CLAUDE.md for the range map or the file-it-upstream
rule and now point at MAINTENANCE.md: include/akbasic/error.h,
src/runtime_disk.c and three entries in TODO.md. Both source changes are
comments. deps/libakgl/TODO.md cites it too and is left alone; it is a
submodule, and the rule it quotes is still reachable from CLAUDE.md.
ctest is green at 95 of 95, docs_examples included: 36 programs, 9
transcripts, 44 output comparisons, 3 C snippets, 1 excerpt.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The akbasic guide
akbasic is a BASIC interpreter in the style of Commodore BASIC 7.0 — the dialect the C128 shipped with — and Dartmouth BASIC. It runs programs from a file or from an interactive prompt, and it is also a C library you can link into a game so that players can script it.
These chapters follow the shape of the C128 Programmer's Reference Guide: the language first, then each hardware area, then the reference sections. If you know BASIC 7.0 you can skip to Chapter 13, which is the list of everything that behaves differently here and why.
Chapters
| 1. Introduction | What akbasic is, what it is not, and how to build it |
| 2. Getting started | The prompt, your first program, saving and loading |
| 3. The language | Variables, types, arrays, operators, expressions |
| 4. Control flow | IF, FOR, DO, GOSUB, labels, ON, error trapping |
| 5. Strings and formatting | String functions, PRINT USING, PUDEF |
| 6. Graphics | GRAPHIC, DRAW, BOX, CIRCLE, PAINT, shapes |
| 7. Sound | SOUND, PLAY, ENVELOPE, VOL, TEMPO |
| 8. Sprites | SPRITE, SPRSAV, MOVSPR, collision |
| 9. Files and disk | Channels, DOPEN, program storage |
| 10. Embedding | Driving the interpreter from C |
| 11. Verb reference | Every statement, alphabetically |
| 12. Function reference | Every function, alphabetically |
| 13. Differences from BASIC 7.0 | What a C128 programmer needs to know |
The shortest possible start
$ cmake -S . -B build && cmake --build build
$ ./build/basic
10 FOR I# = 1 TO 5
20 PRINT "HELLO " + I#
30 NEXT I#
RUN
HELLO 1
HELLO 2
HELLO 3
HELLO 4
HELLO 5
READY
Two things in that program are not Commodore BASIC and will catch you out
immediately: variables carry a type suffix (I# is an integer) and +
concatenates a string with a number. Chapter 3 explains both.
Every example in these chapters is executed by the test suite and its output
compared byte for byte — see MAINTENANCE.md if you are editing them.