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

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