Andrew Kesterson
c8b917d205
No behaviour change, by decision. `A# * 0.45` is 0 and `0.45 * A#` is 1.35, because every operator branches on `self->valuetype` and converts the right operand to match. It is inherited from the Go reference, a C128 promotes to float instead, and this interpreter is at least consistent about it -- so a dialect saying the left operand wins is a defensible position, and changing it to promotion would alter the result of every mixed expression in every existing program. **The defect was that nobody said so.** Chapter 3's "Numbers" did not mention it, Chapter 13 did not list it among the differences, and nothing fails when a program gets it wrong -- it computes something else and carries on. The game in examples/ lost its per-level speed increase to `5.6 + LEVEL# * 0.45` evaluating to a flat 5.6, and bled velocity out of every bounce through `0 - BLVX%(B#)` quantising to whole pixels. Both read correctly. Neither produced a diagnostic. Now said in three places: a section in Chapter 3 with the demonstration and the two rules that keep a program out of it (put the float on the left, put the answer somewhere with a `%` on it), a row in Chapter 13 naming it as the difference from 7.0 most likely to turn a working listing into a quietly wrong one, and the reasoning on value.h where the operators are declared. tests/value_arithmetic.c pins it in both directions across multiply and subtract, with a comment saying it is the documented contract rather than an accident -- so promotion becomes a decision somebody takes deliberately rather than a change that could slip in under a passing suite. TODO.md section 9 item 4, struck as a documentation outcome. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
212 lines
5.1 KiB
Markdown
212 lines
5.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.
|
|
|
|
### The left operand decides whether the arithmetic is integer or float
|
|
|
|
**Not the wider of the two, and not the destination.** An integer on the left of an
|
|
operator converts the right-hand side to an integer, which throws away its fraction:
|
|
|
|
```basic
|
|
A# = 3
|
|
PRINT A# * 0.45
|
|
PRINT 0.45 * A#
|
|
```
|
|
|
|
```output
|
|
0
|
|
1.350000
|
|
```
|
|
|
|
That is the same expression written the other way round, and the answers differ by
|
|
everything. A C128 promotes to float instead; this interpreter does not, and it is
|
|
consistent about it — see [Chapter 13](13-differences.md).
|
|
|
|
**Nothing fails when you get it wrong.** The program computes something else and carries
|
|
on, which is what makes it worth learning early rather than meeting later. Two rules keep
|
|
you out of it:
|
|
|
|
- **Put the float on the left.** `0.45 * LEVEL#`, not `LEVEL# * 0.45`. Likewise
|
|
`0.0 - V%` rather than `0 - V%` to negate a float, which is otherwise quantised to a
|
|
whole number.
|
|
- **Put the answer somewhere that can hold it.** A float expression assigned to a `#`
|
|
variable truncates: `T# = 4.2 / 5.6` is `0`.
|
|
|
|
## 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.
|