akbasic/docs/03-the-language.md

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