andrew/akbasic
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document structures: a chapter, the architecture, and the differences

Browse Source 
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:
Andrew Kesterson
2026-08-01 12:03:02 -04:00
parent 631c70ce7d
commit 6bac929901
8 changed files with 484 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/03-the-language.md
View File

@@ -10,6 +10,7 @@ a character that says what it holds:
| `#` | integer | `COUNT#`, `I#` |
| `%` | floating point | `RATE%`, `X%` |
| `$` | string | `NAME$` |
| `@` | structure | `ENEMY@` |
```basic
10 COUNT# = 42
@@ -20,6 +21,11 @@ a character that says what it holds:
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.
`@` 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.