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>
65 lines
2.8 KiB
Markdown
65 lines
2.8 KiB
Markdown
# 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](http://www.jbrain.com/pub/cbm/manuals/128/C128PRG.pdf):
|
|
the language first, then each hardware area, then the reference sections. If you know
|
|
BASIC 7.0 you can skip to **[Chapter 13](13-differences.md)**, which is the list of
|
|
everything that behaves differently here and why. **[Chapter 14](14-architecture.md)** 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](01-introduction.md)** | What akbasic is, what it is not, and how to build it |
|
|
| **[2. Getting started](02-getting-started.md)** | The prompt, your first program, saving and loading |
|
|
| **[3. The language](03-the-language.md)** | Variables, types, arrays, operators, expressions |
|
|
| **[4. Control flow](04-control-flow.md)** | `IF`, `FOR`, `DO`, `GOSUB`, labels, `ON`, error trapping |
|
|
| **[5. Strings and formatting](05-strings-and-formatting.md)** | String functions, `PRINT USING`, `PUDEF` |
|
|
| **[6. Graphics](06-graphics.md)** | `GRAPHIC`, `DRAW`, `BOX`, `CIRCLE`, `PAINT`, shapes |
|
|
| **[7. Sound](07-sound.md)** | `SOUND`, `PLAY`, `ENVELOPE`, `VOL`, `TEMPO` |
|
|
| **[8. Sprites](08-sprites.md)** | `SPRITE`, `SPRSAV`, `MOVSPR`, collision |
|
|
| **[9. Files and disk](09-files-and-disk.md)** | Channels, `DOPEN`, program storage |
|
|
| **[10. Embedding](10-embedding.md)** | Driving the interpreter from C |
|
|
| **[11. Verb reference](11-verb-reference.md)** | Every statement, alphabetically |
|
|
| **[12. Function reference](12-function-reference.md)** | Every function, alphabetically |
|
|
| **[13. Differences from BASIC 7.0](13-differences.md)** | What a C128 programmer needs to know |
|
|
| **[14. Architecture](14-architecture.md)** | How the interpreter is put together, how to debug it, how to change it |
|
|
| **[15. Error codes](15-error-codes.md)** | Appendix: every value `ER#` can hold and every error line the interpreter prints |
|
|
|
|
## The shortest possible start
|
|
|
|
```sh norun
|
|
$ cmake -S . -B build && cmake --build build
|
|
$ ./build/basic
|
|
```
|
|
|
|
```basic repl
|
|
10 FOR I# = 1 TO 5
|
|
20 PRINT "HELLO " + I#
|
|
30 NEXT I#
|
|
RUN
|
|
```
|
|
|
|
```output
|
|
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.
|