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>
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. Chapter 14 is the odd one out: it is about the interpreter rather than the language, for anyone embedding it, debugging it or changing it.
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 |
| 14. Architecture | How the interpreter is put together, how to debug it, how to change it |
| 15. Error codes | Appendix: every value ER# can hold and every error line the interpreter prints |
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.