Andrew Kesterson
342e4c07da
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>
3.8 KiB
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$ |
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.
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:
PRINT 1.5
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.
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:
PRINT "COUNT: " + 42
COUNT: 42
* repeats:
PRINT "-" * 20
--------------------
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):
10 DIM A#(3)
20 A#(0) = 10 : A#(1) = 20 : A#(2) = 30
30 PRINT A#(0) + A#(1) + A#(2)
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:
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:
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"
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.
10 REM This does nothing at all
Functions you define yourself
DEF makes a single-expression function:
10 DEF SQUARE(X#) = X# * X#
20 PRINT SQUARE(7)
49
A multi-line definition runs until RETURN, which is how you write a subroutine that
takes arguments:
10 DEF GREET(N$)
20 PRINT "HELLO, " + N$
30 RETURN 0
40 X# = GREET("WORLD")
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.