# 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.

**A name is letters and digits and nothing else.** There is no underscore: `HIGH_SCORE#`
does not scan, and what it reports is `UNKNOWN TOKEN _` rather than anything about naming,
so it is worth knowing before you meet it. Run words together — `HIGHSCORE#` — or shorten
them, which is what the listings in this guide do.

`@` 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.
