Andrew Kesterson
342e4c07da
Some checks failed
akbasic CI Build / cmake_build (push) Successful in 3m2s
akbasic CI Build / sanitizers (push) Successful in 3m52s
akbasic CI Build / coverage (push) Failing after 3m24s
akbasic CI Build / akgl_build (push) Failing after 20s
akbasic CI Build / mutation_test (push) Has been cancelled
docs/ and README.md carry 85 fenced blocks. Every one was checked by hand exactly once, when it was written, which is not a standard that survives a changing interpreter -- and four were already wrong: two transcripts showing a leading space PRINT does not emit, akbasic_TextSink in README.md missing the two members it had grown hours earlier, and FILTER's refusal quoted with wording the code does not use. tests/docs_examples.sh reads a fence-tag vocabulary and runs what it finds. BASIC programs and transcripts run and are byte-compared against an `output` block; C snippets compile with -fsyntax-only against the real include path, which CMake writes out because it is transitive through akerror, akstdlib and akgl; shell blocks run in a sandbox. Anything that would reconfigure the build tree, hit the network or re-enter the suite is tagged norun with the reason in MAINTENANCE.md, and the two cmake blocks stay hand-maintained by decision. An untagged block is a failure rather than a default, and the pass line reports what it executed by kind. Both exist because the way a harness like this dies is by quietly matching nothing and passing -- which it duly did on the first CTest run, where a generator expression evaluating to nothing still contributed an empty argument that the script read as a filename. The count is what caught it. The excerpt check earns its own mention: a block tagged `c excerpt=include/akbasic/sink.h` must still appear in that header, comments and whitespace ignored. Compiling it would only redefine the type, so a compile check could not have found the stale struct, and did not. Registered as the CTest case docs_examples in both configurations. Fixing the four wrong examples turned up two interpreter defects, fixed in the previous commit and recorded in TODO.md section 8. MAINTENANCE.md is new: the fence-tag reference, what to do when the case fails, and the conventions that until now only existed inside source comments -- the three test lists and how two of them invert "passed", the sorted verb table, that a golden file is never edited to suit this interpreter, and that a fix gets mutation-checked with a file copy rather than git checkout. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
61 lines
2.4 KiB
Markdown
61 lines
2.4 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.
|
|
|
|
## 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
|
|
|
|
```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.
|