Document structures: a chapter, the architecture, and the differences
docs/16-structures.md is the feature: records, nesting, copy-on-assign, strict pointers, lists, what is checked and what is not, and how a host shares its own C structs. Every example in it is executed by docs_examples and byte-compared, including the refusals -- so a message that changes fails the suite rather than quietly making the chapter wrong. The chapter makes one contrast explicitly, because it is the question a reader will actually have: a misspelled *field* is refused and a misspelled *variable* still prints zero. The rule underneath is that what the program declared gets checked and what it did not gets shrugged at -- a variable's name is never declared, a TYPE's field list is. Structures end up the strictest thing in the language, not from a higher standard but because they are the only named thing whose valid spellings are written down. Chapter 14 gains the layout: an instance is a contiguous run of value slots with a diagram of where the fields sit, the three-pass prescan and why each pass exists, why the copy cannot live in akbasic_value_clone(), and why the render depth bound is four rather than eight. Chapter 3 gains the @ suffix, chapter 13 records that all of this is an addition BASIC 7.0 has nothing like, and the verb reference gains TYPE, POINT and DIM ... AS. MAINTENANCE.md gains the two rules that are on a maintainer rather than on a test: a structure copy must not go through clone, and a field chain gets its own leaf field. TODO.md section 5 records what was invented and the three limits that are ours, and section 8 records the two defects the work exposed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -33,6 +33,7 @@ for the reasoning in each case.
|
||||
| `DEF` | `DEF NAME(args) = expr` | Define a function. Multi-line definitions end in `RETURN`. |
|
||||
| `DELETE` | `DELETE [n][-n]` | Delete lines, with the same range forms as `LIST`. |
|
||||
| `DIM` | `DIM A#(n [,...])` | Make an array. Subscripts start at zero; `n` is the count. |
|
||||
| `DIM` … `AS` | `DIM S@ AS T`, `DIM P@ AS PTR TO T` | Make a structure, or a strict pointer to one. See Chapter 16. |
|
||||
| `DIRECTORY` | `DIRECTORY` | **Refused.** Needs a directory-reading wrapper that does not exist yet. |
|
||||
| `DLOAD` | `DLOAD "name"` | Load a program from a file. |
|
||||
| `DO` | `DO [WHILE c | UNTIL c]` | Start a loop. The condition may be here, on the `LOOP`, or neither. |
|
||||
@@ -70,6 +71,7 @@ for the reasoning in each case.
|
||||
| `ON` | `ON e GOTO|GOSUB t [,...]` | Branch to the `e`th target, counting from one. |
|
||||
| `PAINT` | `PAINT src, x, y` | Flood-fill the region containing a point. |
|
||||
| `PLAY` | `PLAY "notes"` | Queue notes. Does not block. |
|
||||
| `POINT` | `POINT P@ AT s@` | Aim a strict pointer at a structure. See Chapter 16. |
|
||||
| `POKE` | `POKE addr, byte` | Write a byte to a real address. |
|
||||
| `PRINT` | `PRINT [expr]` | Print a value and a newline. |
|
||||
| `PRINT#` | `PRINT #n, expr` | Write a line to a channel. |
|
||||
@@ -101,6 +103,7 @@ for the reasoning in each case.
|
||||
| `TRAP` | `TRAP [target]` | Send errors to a handler. No target disarms it. |
|
||||
| `TROFF` | `TROFF` | Turn line tracing off. |
|
||||
| `TRON` | `TRON` | Turn line tracing on; each line prints its number in brackets. |
|
||||
| `TYPE` | `TYPE NAME` … `END TYPE` | Declare a record, its fields one per line. See Chapter 16. |
|
||||
| `VERIFY` | `VERIFY "name"` | Compare the program in memory against a file. |
|
||||
| `VOL` | `VOL n` | Set the overall volume, 0 to 15. |
|
||||
| `WAIT` | `WAIT addr, mask [,xor]` | Poll a byte until it matches. Holds the program. |
|
||||
|
||||
Reference in New Issue
Block a user