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$
@	structure	ENEMY@

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, 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:

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.

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:

A# = 3
PRINT A# * 0.45
PRINT 0.45 * A#

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.

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:

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)

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:

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"

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.

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)

49

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")

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.