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>
4.6 KiB
4. Control flow
IF ... THEN ... ELSE
10 A# = 5
20 IF A# = 5 THEN PRINT "FIVE" ELSE PRINT "NOT FIVE"
FIVE
The condition is a whole expression, so AND, OR and NOT all work in one:
10 A# = 5
20 IF A# > 0 AND A# < 10 THEN PRINT "IN RANGE"
IN RANGE
Everything after THEN on the line belongs to the condition, which matters as soon
as you put several statements on a line:
| Line | Condition | What runs |
|---|---|---|
IF C THEN A : B |
true | A, B |
IF C THEN A : B |
false | nothing |
IF C THEN A ELSE B : D |
true | A |
IF C THEN A ELSE B : D |
false | B, D |
The remainder always belongs to whichever arm was written last.
Blocks
BEGIN and BEND make an IF span lines:
10 A# = 5
20 IF A# = 5 THEN BEGIN
30 PRINT "IN THE BLOCK"
40 PRINT "STILL IN IT"
50 BEND
60 PRINT "AFTER"
IN THE BLOCK
STILL IN IT
AFTER
When the condition is false every line up to the BEND is skipped.
FOR ... NEXT
10 FOR I# = 1 TO 5
20 PRINT I#
30 NEXT I#
1
2
3
4
5
STEP sets the stride, and a negative one counts down:
10 FOR I# = 10 TO 0 STEP -2
20 PRINT I#
30 NEXT I#
10
8
6
4
2
0
The counter is an ordinary variable and the body may assign to it. Two things to know:
- The counter does not survive the loop. It lives in the loop's own scope, so reading it afterwards gives zero. On a C128 it keeps its final value.
- A step that overshoots runs the body one extra time.
FOR I = 1 TO 9 STEP 3runs with 1, 4, 7 and 10. Both are recorded as known defects; see Chapter 13.
EXIT leaves the loop early:
10 FOR I# = 1 TO 100
20 IF I# = 5 THEN EXIT
30 NEXT I#
40 PRINT "OUT"
OUT
DO ... LOOP
The condition can go on either end, or neither:
10 I# = 0
20 DO WHILE I# < 3
30 PRINT I#
40 I# = I# + 1
50 LOOP
0
1
2
10 I# = 0
20 DO
30 PRINT I#
40 I# = I# + 1
50 LOOP UNTIL I# = 3
0
1
2
A condition on the DO is tested before the body, so the body may run zero times. A
condition on the LOOP is tested after, so it runs at least once. DO with no
condition at all loops forever until an EXIT or a GOTO leaves it.
EXIT works here too.
GOTO and GOSUB
10 GOSUB 100
20 PRINT "BACK"
30 END
100 PRINT "IN THE SUBROUTINE"
110 RETURN
IN THE SUBROUTINE
BACK
RETURN goes back to the line after the GOSUB.
Labels
A label is a name with no type suffix. It marks a line, and anything that takes a line number takes a label instead:
10 GOTO SETUP
20 PRINT "SKIPPED"
100 LABEL SETUP
110 PRINT "ARRIVED"
ARRIVED
Labels are filed before the program runs, so a forward GOTO works. This is worth
using for its own sake: a program written with labels is immune to RENUMBER, because
there is no number to rewrite.
ON
ON picks the nth target from a list, counting from one:
10 CHOICE# = 2
20 ON CHOICE# GOTO 100, 200, 300
30 PRINT "CHOICE WAS OUT OF RANGE"
40 END
100 PRINT "FIRST"
110 END
200 PRINT "SECOND"
210 END
300 PRINT "THIRD"
SECOND
Out of range is not an error — it falls through to the next statement, which is what
lets you write the check as the line after. ON ... GOSUB works the same way and
returns.
Trapping errors
TRAP sends an error to a handler instead of stopping the program:
10 TRAP HANDLER
20 DIM Q#(2)
30 PRINT Q#(9)
40 PRINT "CARRIED ON"
50 END
100 LABEL HANDLER
110 PRINT "CAUGHT " + ERR(ER#) + " ON LINE " + EL#
120 RESUME NEXT
CAUGHT Out Of Bounds ON LINE 30
CARRIED ON
Two variables are set when the trap fires: ER# is the error code and EL# is
the line it happened on. ERR(ER#) gives the message text. On a C128 these are called
ER and EL with no suffix; this dialect has no bare variable names.
RESUME comes in three forms:
| Form | Where it goes |
|---|---|
RESUME |
back to the line that failed, and tries again |
RESUME NEXT |
on to the line after the one that failed |
RESUME (line) |
to a line you name |
Bare RESUME only terminates if the handler fixed whatever was wrong — that is what
it is for.
TRAP with no argument turns trapping off. An error inside a handler is reported
normally rather than re-entering it, so a broken handler cannot loop forever.
STOP, END and CONT
STOP stops the program and returns to the prompt; CONT resumes from there. END
stops it without arming CONT. QUIT ends the interpreter itself.