2cb68665d0
Review findings and follow-ups from PR #61 review: - runtime_generator.c: akbasic_runtime_release_generator() now releases the forGeneratorEnv of every scope it walks through. Abandoning a generator that was itself suspended inside a FOR EACH over another generator stranded the inner generator's pool slot; a loop doing so exhausted the twelve-slot pool and died far from the cause. - runtime.c/runtime.h: new akbasic_runtime_unwind_to_environment(), the shared teardown for the error unwinds in pump_generator() and call_function() -- both previously bare prev_environment() loops with the same suspended-generator blindness. - runtime_commands.c: bare RETURN standing in a GEN's own frame ends the generator exactly as END GEN does -- a GEN is a function at heart. RETURN with a value there is refused (values leave a GEN only through EMIT). The no-frame error message now says "GOSUB, DEF, or GEN". - runtime_structure.c: LOOP WHILE/UNTIL composes with DO EACH -- checked after each trip with the loop variable still holding that trip's value; a condition that stops the loop abandons the generator exactly as EXIT does. Previously the condition was silently ignored, while the verb reference documented it as working. - parser_commands.c: trailing tokens after the generator call on a FOR EACH/DO EACH line are refused at parse. Previously they sat unparsed and blew up only after the loop completed, when the parent scope resumed the line mid-statement -- an error at the loop's end pointing at its start. - tests/generators.c: pool-exhaustion tests for the nested-abandonment and LOOP-condition paths, RETURN semantics tests, and a direct test of the unwind primitive. Three new golden pairs cover RETURN, LOOP conditions and the misplaced-condition parse error. - docs: RETURN and LOOP-condition semantics in 04-control-flow.md and 11-verb-reference.md; corrected the self-recursion analogy (functions are re-entrant here). TODO.md 1.10 records the generator design decisions the code comments were already citing, plus the zero-arg parameter-list limitation. MAINTENANCE.md gains the abandoned-generators invariant those comments also cited. Co-Authored-By: Andrew Kesterson <andrew@aklabs.net> Co-Authored-By: Claude Fable 5 <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 17 and 18 are tutorials rather than reference: they build one complete game twice, two different ways, in numbered steps you can type in one at a time. Start with 17 — it needs nothing but the earlier chapters, and 18 assumes it. Chapters 20 and 21 are the third tutorial, from the other side of the boundary: a C game on libakgl that embeds the interpreter as its enemy-behavior engine, for anyone whose question is "how do I put this in my game".
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 |
| 16. Structures | TYPE, records, strict pointers, and sharing a C struct with an embedding host |
| 17. Tutorial: Breakout | Build a whole game out of the text grid and two DATA sprites, in sixteen steps |
| 18. Tutorial: Breakout with artwork | Build it again out of loaded artwork, powerups and a drawn colour HUD, in thirteen |
| 19. Menus and dialogs | MENU, DIALOG, HUD and UISTYLE — the widgets, and who owns the keyboard |
| 20. Tutorial: GALAGA | Build a C engine on libakgl that embeds the interpreter, boots a script and hands it an actor |
| 21. Tutorial: GALAGA enemies | Share three C structs with the script, then write the wave's whole brain in BASIC |
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.