Andrew Kesterson
1fb808f480
Some checks failed
akbasic CI Build / cmake_build (push) Failing after 3m21s
akbasic CI Build / sanitizers (push) Failing after 4m32s
akbasic CI Build / coverage (push) Failing after 3m37s
akbasic CI Build / akgl_build (push) Failing after 22s
akbasic CI Build / mutation_test (push) Failing after 3m30s
Chapters 17 and 18 read as a code review of a finished listing: they explained why each decision had been made, walked through the project's own history, and led with what had once been broken. A reader who wanted to build the game got the reasoning and had to reconstruct the program. Both are now step-by-step. Each opens with a picture of the finished game and a bullet list of the steps, each bullet is a section, and each section states its goal, shows the code, and says how to check it. Chapter 17 is sixteen steps and Chapter 18 is thirteen, and the last of each is the assembly: the order of the file, the full declaration block, and the routines the earlier steps referred to. Project history is gone -- it belongs in Chapter 14 and in git -- and where a listing has to do something awkward, the tutorial shows how first and names the `TODO.md` item that will make it unnecessary second. **Three defects had no entry anywhere**, which the rewrite found by trying to state each rule as a rule. §6 item 35: `a - b + c` computes `a - (b + c)`, because `subtraction()` sits above `addition()` as its own precedence level and the inner loop eats the `+`. Item 36: only one unparenthesised `AND` or `OR` is matched, which is item 12's `if`-where-`while` on the one operator pair item 12 did not reach. Item 37: a `GOTO` out of a `FOR` or a `DO` leaks the loop's scope, so a main loop written that way stops on the thirty-second lost life -- which is why both games are built out of `LABEL` and `GOTO`, and it is a workaround rather than a preference. Chapter 3 gains the identifier rule the third trial ran into: there is no underscore in a name, and the error says `UNKNOWN TOKEN _`. **`tools/screenshot.c` learned to draw the text layer**, behind a new `text=1` fence attribute, because Chapter 17's game is characters in the grid and a figure without that layer is two sprites on black. It opens the bundled font at the size the standalone frontend uses, so a figure's cell size is the reader's cell size, and it uses the akgl sink alone rather than a tee so the program's output lands in the picture instead of on the stdout the caller reads to decide a figure failed. Both new figures -- `breakout-game.png` and `breakout-game-artwork.png` -- are generated from listings in the chapters like every other one. Verified by handing each chapter, alone, to an agent on a much smaller model and telling it to build the game from the tutorial text with the `examples/` tree off limits. The first pass scored 3.5 and 3 out of 10 and named what was missing: routines referred to but never shown, the third level layout, the sprite `DATA`, the font table, edits to earlier routines that were never marked as edits. Those are now in. The second pass built a 658-line Chapter 17 game that plays itself for ninety seconds with the score at 1890 and no error line, and the third built a 1053-line Chapter 18 game with 61 labels, no invented routines, no gaps found, and forty seconds clean. 9/10 and 8/10. One real bug in the new prose, caught in review: Chapter 18's `HITBAR` did not set the `HIT#` that `BALLPADDLE` reads to decide whether the paddle already caught the ball. Both suites green in both configurations, `docs_examples` and `docs_screenshots --check` pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
217 lines
5.4 KiB
Markdown
217 lines
5.4 KiB
Markdown
# 3. The language
|
|
|
|
## Variables carry their type in a suffix
|
|
|
|
This is the first thing that will catch a C128 programmer. Every variable name ends in
|
|
a character that says what it holds:
|
|
|
|
| Suffix | Type | Example |
|
|
|---|---|---|
|
|
| `#` | integer | `COUNT#`, `I#` |
|
|
| `%` | floating point | `RATE%`, `X%` |
|
|
| `$` | string | `NAME$` |
|
|
| `@` | structure | `ENEMY@` |
|
|
|
|
```basic
|
|
10 COUNT# = 42
|
|
20 RATE% = 1.5
|
|
30 NAME$ = "ADA"
|
|
```
|
|
|
|
There is no such thing as a variable with no suffix. A bare name is a **label** — see
|
|
Chapter 4 — so `GOTO DONE` and `LABEL DONE` are how the two meet.
|
|
|
|
**A name is letters and digits and nothing else.** There is no underscore: `HIGH_SCORE#`
|
|
does not scan, and what it reports is `UNKNOWN TOKEN _` rather than anything about naming,
|
|
so it is worth knowing before you meet it. Run words together — `HIGHSCORE#` — or shorten
|
|
them, which is what the listings in this guide do.
|
|
|
|
`@` is the odd one out: it says "a structure" without saying *which*, so a structure
|
|
variable has to be declared with `DIM E@ AS ENEMY` before it can be used. That is
|
|
**[Chapter 16](16-structures.md)**, along with records, pointers and how a host shares its
|
|
own C structs with a script.
|
|
|
|
On a C128 the suffixes mean something different (`%` is integer, no suffix is float).
|
|
Here `%` is float and `#` is integer, following the Go implementation this was ported
|
|
from. Chapter 13 lists it with the other differences.
|
|
|
|
Variable names are **case sensitive**. Verb and function names are not: `print`,
|
|
`Print` and `PRINT` are the same word.
|
|
|
|
## Numbers
|
|
|
|
Integers are 64-bit. Floats are IEEE doubles, so they print with six decimal places:
|
|
|
|
```basic repl
|
|
PRINT 1.5
|
|
```
|
|
|
|
```output
|
|
1.500000
|
|
```
|
|
|
|
Literals may be written in hexadecimal with a `0x` prefix. A leading zero is *not*
|
|
octal — `010` is ten, because a leading zero in a listing is far more often padding
|
|
than a base.
|
|
|
|
### The left operand decides whether the arithmetic is integer or float
|
|
|
|
**Not the wider of the two, and not the destination.** An integer on the left of an
|
|
operator converts the right-hand side to an integer, which throws away its fraction:
|
|
|
|
```basic
|
|
A# = 3
|
|
PRINT A# * 0.45
|
|
PRINT 0.45 * A#
|
|
```
|
|
|
|
```output
|
|
0
|
|
1.350000
|
|
```
|
|
|
|
That is the same expression written the other way round, and the answers differ by
|
|
everything. A C128 promotes to float instead; this interpreter does not, and it is
|
|
consistent about it — see [Chapter 13](13-differences.md).
|
|
|
|
**Nothing fails when you get it wrong.** The program computes something else and carries
|
|
on, which is what makes it worth learning early rather than meeting later. Two rules keep
|
|
you out of it:
|
|
|
|
- **Put the float on the left.** `0.45 * LEVEL#`, not `LEVEL# * 0.45`. Likewise
|
|
`0.0 - V%` rather than `0 - V%` to negate a float, which is otherwise quantised to a
|
|
whole number.
|
|
- **Put the answer somewhere that can hold it.** A float expression assigned to a `#`
|
|
variable truncates: `T# = 4.2 / 5.6` is `0`.
|
|
|
|
## Strings
|
|
|
|
Strings are up to 255 characters and are written in double quotes. There is no
|
|
escaping: a string cannot contain a double quote.
|
|
|
|
`+` concatenates, and it will concatenate a string with a number:
|
|
|
|
```basic repl
|
|
PRINT "COUNT: " + 42
|
|
```
|
|
|
|
```output
|
|
COUNT: 42
|
|
```
|
|
|
|
`*` repeats:
|
|
|
|
```basic repl
|
|
PRINT "-" * 20
|
|
```
|
|
|
|
```output
|
|
--------------------
|
|
```
|
|
|
|
## Arrays
|
|
|
|
`DIM` makes one. Subscripts start at zero and the number you give is the *count*, so
|
|
`DIM A#(3)` gives you `A#(0)` through `A#(2)`:
|
|
|
|
```basic
|
|
10 DIM A#(3)
|
|
20 A#(0) = 10 : A#(1) = 20 : A#(2) = 30
|
|
30 PRINT A#(0) + A#(1) + A#(2)
|
|
```
|
|
|
|
```output
|
|
60
|
|
```
|
|
|
|
Arrays can have several dimensions: `DIM GRID#(10, 10)`. `LEN(A#)` gives the total
|
|
number of elements.
|
|
|
|
An array name used with no subscript means the whole array, which is what `SPRSAV` and
|
|
`SWAP` take.
|
|
|
|
## Operators
|
|
|
|
In order of precedence, tightest first:
|
|
|
|
| Operators | Meaning |
|
|
|---|---|
|
|
| `^` | exponentiation |
|
|
| `-` (unary), `NOT` | negation, bitwise/logical not |
|
|
| `*` `/` | multiply, divide |
|
|
| `+` `-` | add and concatenate, subtract |
|
|
| `<` `<=` `>` `>=` `=` `==` `<>` | comparison |
|
|
| `AND` `OR` | bitwise, and logical |
|
|
|
|
### `=` and `==`
|
|
|
|
Both mean equality **inside a condition**:
|
|
|
|
```basic norun
|
|
10 IF A# = 5 THEN PRINT "FIVE"
|
|
20 IF A# == 5 THEN PRINT "ALSO FIVE"
|
|
```
|
|
|
|
Outside a condition `=` is assignment, which is why the distinction has to exist at
|
|
all. `==` works everywhere and is what the older programs in this repository use.
|
|
|
|
### Truth
|
|
|
|
A comparison yields **-1 for true and 0 for false**, which is Commodore's convention
|
|
and the reason `AND` and `OR` double as the logical operators: -1 is every bit set.
|
|
|
|
Anything non-zero is true, so `IF A# THEN ...` works:
|
|
|
|
```basic
|
|
10 A# = 5
|
|
20 IF A# THEN PRINT "NON-ZERO IS TRUE"
|
|
30 IF A# = 5 AND A# > 1 THEN PRINT "AND WORKS"
|
|
40 IF NOT (A# = 9) THEN PRINT "SO DOES NOT"
|
|
```
|
|
|
|
```output
|
|
NON-ZERO IS TRUE
|
|
AND WORKS
|
|
SO DOES NOT
|
|
```
|
|
|
|
`AND` and `OR` are still bitwise on ordinary numbers: `PRINT 12 AND 10` gives `8`.
|
|
|
|
## Comments
|
|
|
|
`REM` comments to the end of the line.
|
|
|
|
```basic
|
|
10 REM This does nothing at all
|
|
```
|
|
|
|
## Functions you define yourself
|
|
|
|
`DEF` makes a single-expression function:
|
|
|
|
```basic
|
|
10 DEF SQUARE(X#) = X# * X#
|
|
20 PRINT SQUARE(7)
|
|
```
|
|
|
|
```output
|
|
49
|
|
```
|
|
|
|
A multi-line definition runs until `RETURN`, which is how you write a subroutine that
|
|
takes arguments:
|
|
|
|
```basic
|
|
10 DEF GREET(N$)
|
|
20 PRINT "HELLO, " + N$
|
|
30 RETURN 0
|
|
40 X# = GREET("WORLD")
|
|
```
|
|
|
|
```output
|
|
HELLO, WORLD
|
|
```
|
|
|
|
`RETURN` carries the value back, so a multi-line `DEF` is a function even when you only
|
|
wanted the effect — assign the result somewhere to throw it away.
|