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

Write the usage guide as thirteen chapters in docs/
Some checks failed
akbasic CI Build / cmake_build (push) Successful in 3m0s
Details
akbasic CI Build / sanitizers (push) Successful in 3m45s
Details
akbasic CI Build / coverage (push) Failing after 3m22s
Details
akbasic CI Build / akgl_build (push) Failing after 21s
Details
akbasic CI Build / mutation_test (push) Successful in 11m26s
Details

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>
This commit is contained in:
Andrew Kesterson
2026-07-31 21:50:50 -04:00
parent 9845e77a5c
commit cdaefcc941
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.