Andrew Kesterson
cdaefcc941
Some checks failed
akbasic CI Build / cmake_build (push) Successful in 3m0s
akbasic CI Build / sanitizers (push) Successful in 3m45s
akbasic CI Build / coverage (push) Failing after 3m22s
akbasic CI Build / akgl_build (push) Failing after 21s
akbasic CI Build / mutation_test (push) Successful in 11m26s
Organised the way the C128 Programmer's Reference Guide is: the language first, then each hardware area, then the reference sections. One markdown file per chapter. The verb and function references are generated from the interpreter's own dispatch table, with an assertion that every row is described, so they cannot drift out of step with what the program accepts. 98 verbs and 30 functions. Every example was run before it was written down, which caught three claims that were wrong: a whole FOR loop on one line prints nothing rather than looping once, MID and INSTR count from zero where a C128 counts from one, and a multi-line DEF returns a value the caller has to assign away. Chapter 13 is the list a BASIC 7.0 programmer needs -- roughly sixty documented differences, including the two known FOR defects and the fact that drawing does not survive a frame. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
149 lines
3.6 KiB
Markdown
149 lines
3.6 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$` |
|
|
|
|
```
|
|
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.
|
|
|
|
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:
|
|
|
|
```
|
|
PRINT 1.5
|
|
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:
|
|
|
|
```
|
|
PRINT "COUNT: " + 42
|
|
COUNT: 42
|
|
```
|
|
|
|
`*` repeats:
|
|
|
|
```
|
|
PRINT "-" * 20
|
|
--------------------
|
|
```
|
|
|
|
## 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)`:
|
|
|
|
```
|
|
10 DIM A#(3)
|
|
20 A#(0) = 10 : A#(1) = 20 : A#(2) = 30
|
|
30 PRINT A#(0) + A#(1) + A#(2)
|
|
```
|
|
|
|
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**:
|
|
|
|
```
|
|
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:
|
|
|
|
```
|
|
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"
|
|
```
|
|
|
|
`AND` and `OR` are still bitwise on ordinary numbers: `PRINT 12 AND 10` gives `8`.
|
|
|
|
## Comments
|
|
|
|
`REM` comments to the end of the line.
|
|
|
|
```
|
|
10 REM This does nothing at all
|
|
```
|
|
|
|
## Functions you define yourself
|
|
|
|
`DEF` makes a single-expression function:
|
|
|
|
```
|
|
10 DEF SQUARE(X#) = X# * X#
|
|
20 PRINT SQUARE(7)
|
|
```
|
|
|
|
A multi-line definition runs until `RETURN`, which is how you write a subroutine that
|
|
takes arguments:
|
|
|
|
```
|
|
10 DEF GREET(N$)
|
|
20 PRINT "HELLO, " + N$
|
|
30 RETURN 0
|
|
40 X# = GREET("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.
|