Andrew Kesterson
cdaefcc941
Some checks failed
akbasic CI Build / cmake_build (push) Successful in 3m0s
akbasic CI Build / sanitizers (push) Successful in 3m45s
akbasic CI Build / coverage (push) Failing after 3m22s
akbasic CI Build / akgl_build (push) Failing after 21s
akbasic CI Build / mutation_test (push) Successful in 11m26s
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>
75 lines
2.7 KiB
Markdown
75 lines
2.7 KiB
Markdown
# 1. Introduction
|
|
|
|
## What akbasic is
|
|
|
|
A BASIC interpreter written in C, styled after **Commodore BASIC 7.0** and
|
|
**Dartmouth BASIC**. It does three things:
|
|
|
|
- **Runs a program from a file.** `basic program.bas` loads it, runs it, and exits.
|
|
- **Gives you a prompt.** `basic` with no arguments is a REPL: type lines with
|
|
numbers to build a program, type verbs without numbers to run them immediately.
|
|
- **Links into a program as a library.** A game can embed the interpreter, hand it a
|
|
script, and step it a frame at a time. That is the reason for most of the design
|
|
decisions you will notice.
|
|
|
|
It is a rewrite of an earlier Go implementation, which is kept only as a reference for
|
|
questions about semantics. Its acceptance corpus is checked in here and runs on every
|
|
build.
|
|
|
|
## What akbasic is not
|
|
|
|
**It is not an emulator.** There is no 6502, no VIC-II, no SID, no 1541 and no
|
|
bank-switched memory. Verbs that only make sense against that hardware are either
|
|
reinterpreted for a modern machine — and Chapter 13 says exactly how — or refused by
|
|
name with the reason. Nothing is silently ignored.
|
|
|
|
**It is not byte-compatible with a C128.** Error numbers are not Commodore's, floating
|
|
point is IEEE double rather than Commodore's five-byte format, and a handful of
|
|
statements parse differently. Again: Chapter 13.
|
|
|
|
## Two builds
|
|
|
|
The default build has no dependency on SDL and no graphics, sound, sprites or windowed
|
|
text. Everything else works, and the whole test suite runs on a machine with no SDL
|
|
installed at all.
|
|
|
|
```sh
|
|
cmake -S . -B build
|
|
cmake --build build
|
|
```
|
|
|
|
The SDL build adds a window, the Commodore font, and the graphics, sound and sprite
|
|
devices. It needs [libakgl](https://source.starfort.tech/andrew/libakgl), which is
|
|
vendored as a submodule.
|
|
|
|
```sh
|
|
git submodule update --init --recursive
|
|
cmake -S . -B build-akgl -DAKBASIC_WITH_AKGL=ON
|
|
cmake --build build-akgl
|
|
```
|
|
|
|
A verb that needs a device the build does not have does not crash and does not lie. It
|
|
reports itself by name:
|
|
|
|
```
|
|
? 10 : RUNTIME ERROR DRAW needs a graphics device and this runtime has none
|
|
```
|
|
|
|
That is the same message an embedded host sees when it deliberately withholds a
|
|
device — a game may want a script that can print but not draw.
|
|
|
|
## Running the tests
|
|
|
|
```sh
|
|
ctest --test-dir build --output-on-failure
|
|
```
|
|
|
|
The suite includes the original Go implementation's acceptance corpus, byte-compared,
|
|
plus this project's own tests for everything the corpus does not reach.
|
|
|
|
## Where to go next
|
|
|
|
Chapter 2 gets a program running. If you already write BASIC 7.0, read
|
|
**[Chapter 13](13-differences.md)** first — it is short, and it will save you the
|
|
three or four surprises that would otherwise find you one at a time.
|