docs/README.md

# 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.

## 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 |

## The shortest possible start

```
$ cmake -S . -B build && cmake --build build
$ ./build/basic
READY
10 FOR I# = 1 TO 5
20 PRINT "HELLO " + I#
30 NEXT I#
RUN
```

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.
Write the usage guide as thirteen chapters in docs/ Organised the way the C128 Programmer's Reference Guide is: the language first, then each hardware area, then the reference sections. One markdown file per chapter. The verb and function references are generated from the interpreter's own dispatch table, with an assertion that every row is described, so they cannot drift out of step with what the program accepts. 98 verbs and 30 functions. Every example was run before it was written down, which caught three claims that were wrong: a whole FOR loop on one line prints nothing rather than looping once, MID and INSTR count from zero where a C128 counts from one, and a multi-line DEF returns a value the caller has to assign away. Chapter 13 is the list a BASIC 7.0 programmer needs -- roughly sixty documented differences, including the two known FOR defects and the fact that drawing does not survive a frame. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> 2026-07-31 21:50:50 -04:00			`# 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.`

			`## 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 \|`

			`## The shortest possible start`

			```
			`$ cmake -S . -B build && cmake --build build`
			`$ ./build/basic`
			`READY`
			`10 FOR I# = 1 TO 5`
			`20 PRINT "HELLO " + I#`
			`30 NEXT I#`
			`RUN`
			```

			`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.`