Execute every documented example as a test
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>
This commit is contained in:
2026-07-31 22:41:36 -04:00
parent 6f49f6a7f2
commit 342e4c07da
29 changed files with 1303 additions and 103 deletions

View File

@@ -12,7 +12,7 @@ see and manipulate a script's sprites.
### From an image file
```
```basic requires=akgl setup=ship
10 SPRSAV "ship.png", 1
```
@@ -25,7 +25,7 @@ A sprite loaded this way takes **the image's own size**. It is not forced to 24
### From a saved region
```
```basic requires=akgl
10 BOX 1, 0, 0, 24, 21
20 SSHAPE A$, 0, 0, 24, 21
30 SPRSAV A$, 1
@@ -37,7 +37,7 @@ faithful rather than a shortcut.
### From data
```
```basic norun
10 DIM P#(63)
20 FOR I# = 0 TO 62
30 READ P#(I#)
@@ -58,9 +58,10 @@ operation.
## Showing and moving
```
10 SPRITE 1, 1, 3
20 MOVSPR 1, 100, 50
```basic requires=akgl setup=ship
10 SPRSAV "ship.png", 1
20 SPRITE 1, 1, 3
30 MOVSPR 1, 100, 50
```
`SPRITE n [,on] [,colour] [,priority] [,xexpand] [,yexpand] [,multicolour]`. Only the
@@ -88,7 +89,7 @@ raster coordinates.
## Collision
```
```basic norun
10 COLLISION 1, BUMPED
20 REM ... main loop ...
90 GOTO 20