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