andrew/akbasic
1
0
Fork 0
Code Issues 27 Pull Requests Actions Packages Projects Releases Wiki Activity

Write the usage guide as thirteen chapters in docs/

Browse Source 
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>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
This commit is contained in:
Tachikoma
2026-07-31 21:50:50 -04:00
parent 4e7d2cff6c
commit 1f8dabf5e7
14 changed files with 1592 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
docs/README.md Normal file
View File

@@ -0,0 +1,46 @@
# 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.