File: basic.txt

package info (click to toggle)
brandy 1.23.6-1
links: PTS, VCS
area: main
in suites: forky, sid
size: 3,268 kB
sloc: ansic: 39,421; makefile: 91; sh: 1
file content (4930 lines) | stat: -rw-r--r-- 183,485 bytes
BASIC V/VI Guide
~~~~~~~~~~~~~~~~

Contents
~~~~~~~~
        Introduction
        History
        Features
        Constants
        Variables
        Keywords
        Line Numbers
        Operators
        Assignment Operators
        Indirection Operators
        Array Operations
        Built-in Functions
        Pseudo Variables
        Procedures and Functions
        Error Handling
        Issuing Commands to the Underlying Operating System
        Statement Types
        Statements
        Commands
        The Program Environment
        Screen Output
        VDU Commands
        PLOT Codes
        BASIC Keywords, Commands and Functions


Introduction
~~~~~~~~~~~~
The following notes give a brief introduction to BASIC V/VI and to the
environment that the interpreter emulates. They describe the entire language
but not in any great detail; more attention is given to features specific to
this version of BASIC. Useful information can be found on the web site 'The
BBC Lives!' where scanned version of manuals such as the 'BBC Microcomputer
User Guide' can be found. The information in these manuals is not 100%
relevant to BASIC V/VI but they are good for background information and many
details of BASIC II, the predecessor of (and to all intents and purposes, a
strict subset of) BASIC V/VI.

These notes describe the BASIC language. The file 'use' contains information
on how to use the interpreter and on the features and limitations of the
different versions of the program.


History
~~~~~~~
At the start of the 1980s the British Broadcasting Corporation was looking
for a microcomputer to be used for their series 'The Computer Programme'.
The machine chosen became known as the 'BBC Micro' and it was made by Acorn
Computers. It was an extremely potent and flexible little computer that some
people still use to this day. The dialect of BASIC on it was called 'BBC
BASIC'. This was an extended BASIC that added such features as procedures
and multi-line functions. It was also one of the fastest BASIC interpreters
available on an eight-bit computer. The interpreter was well integrated with
the rest of the machine: it was possible to directly call operating system
functions from BASIC programs and there was also a built-in assembler. If
something could not be done in BASIC or was too slow it was possible to
write the code in assembler. Many programs were written that used a
combination of BASIC and assembler. Compilers and interpreters for languages
such as BCPL, C and Pascal were written for the BBC Micro, but by far the
most popular language was BASIC.

In 1987 Acorn brought out the Archimedes. This included a new version of the
BBC BASIC interpreter that had many additional features such as 'CASE'
statements and multi-line 'IF' statements. It kept its reputation for speed.
This version of BASIC was called 'BASIC V', and later a version using 64-bit
floating point numbers was issued as a soft-load for RISC OS as 'BASIC VI'
and it is the dialect of the language implemented by this interpreter.

The operating system that ran on the Archimedes and the machines that have
succeeded it over the years is called 'RISC OS'. This was designed and
written by Acorn Computers. 


Features
~~~~~~~~
The main features of BASIC V/VI are:

1)  It is a structured BASIC with a full range of statement types such as
    WHILE and REPEAT loops, a block IF statement and a CASE statement.
2)  It has procedures and multi-line functions which can have local
    variables and arrays.
3)  It has 'indirection operators' which allow data structures to be 
    constructed and manipulated. Memory can be allocated from the BASIC heap
    that can be referenced using these operators. (This is not to say that
    the dialect includes data structures per se but they can be set up and
    used in a way that appears to be reminiscent of BCPL.)
4)  The Acorn-written interpreters include an assembler. Programs can be
    written using a mix of BASIC and assembler. All the features of the
    BASIC interpreter are available to the assembler, so that, for example,
    functions written in BASIC are used as macros.
    (Please note that Matrix Brandy does not implement an assembler.)
5)  Speed: the interpreter is very fast.


Notation
~~~~~~~~
A few words on the notation used in these notes might be in order.

In describing the syntax of statements, parts of the statement are often put
in angle brackets <like this>. The purpose of this is to say what goes at
that part of the statement, for example:

        GOSUB <line number>

This says that the keyword GOSUB is to be followed by a line number if a
GOSUB statement is used in the program. Another example:

        ON ERROR <statements>

This one says that in an 'ON ERROR' statement, the keywords 'ON ERROR' are
followed by one or more BASIC statements.

In some cases, parts of a statement are in square brackets, for example:

        IF <expression> THEN <line number>
                                 [ ELSE <line number> ]

This means that that part of the statement is optional. In the example, the
'[ ELSE <line number> ]' part of the statement can be omitted.


Constants
~~~~~~~~~
The interpreter supports five types of variable:

-  Decimal integer
-  Hexadecimal integer
-  Binary integer
-  Floating point
-  String

Hexadecimal constants begin with a '&' and binary ones with a '%'. Strings
are enclosed in '"'. It is possible to embed a '"' is a string by preceding
it with another '"'. Examples:

        &FFFF
        &123456
        %1001101
        %1
        "abcdefghij"
        "klmnop""qrst"


Variables
~~~~~~~~~
The interpreter supports three main types:

        32-bit integer          e.g. abc%
        64-bit integer          e.g. def%%
        Floating point          e.g. ghi
        String                  e.g. jkl$

32-bit integer variables are denoted as being a 32-bit integer by having a
'%' at the end of the name.

64-bit integer variables are denoted as being a 64-bit integer by having a
double '%%' at the end of the name.

8-bit unsigned integers are denoted as being an 8-bit unsigned integer by
having a '&' at the end of the name.

Floating point variables are 64 bits wide. If a variable does not have
either a '%', '%%', '&' or a '$' suffix then it is a floating point
variable.

String variables have a '$' suffix at the end of their name. They can refer
to strings that have a maximum length of 65,536 characters.
    
Note that it is possible for variables of different types to have the same
name, for example, 'abc%', 'abc' and 'abc$' can all exist at the same time.
The '%' and '$' are considered to be part of the name. Similarly, it is
possible to have arrays and simple variables of the same name, for example:

        abcd$           <-- String variable
        abcd$()         <-- String array

What happens is that the '(' is considered to be part of the name of the
array.

Variable names are case sensitive, so that 'abcd' and 'AbCd' are different
variables.

BBC BASIC has two classes of variables, the normal dynamic variables that
are created when the program runs and a set of what are called 'static'
variables which comprises of the integer variables A% to Z%. These variables
are independent of any program in that their valaues are not reset or
changed when a program is loaded or modified. They can, for example, be used
to pass values from one program to another.


Keywords
~~~~~~~~
Keywords are BASIC's reserved words. They are split into two types
in this interpreter, BASIC keywords and BASIC commands. Examples
of the former are 'IF', 'ENDPROC' and 'WHILE'. Examples of
commands are 'LOAD', 'LIST' and 'NEW'. A complete list of keywords
is given at the end of these notes.

If Matrix Brandy is invoked with '-lck', the 'lowercase' config option is
present, or the command SYS"Brandy_AllowLowercase",1 is issued, commands can
be given in either lower or upper case to make it more convenient to type
them in. Otherwise all commands must be entered in upper case, as is the
case with the BBC Micro and RISC OS versions of BBC BASIC. A word of warning
with this, some variables in lower case may be mistaken for keywords and
thus cannot be used in this mode, however a program loaded from file may
contain these and will not be interpreted as keywords.

The interpreter tries to be clever with keywords. In general keywords cannot
be used as variable names but there are cases where if a keyword is followed
by a letter it is not identified as a keyword, for example, 'COUNT' on its
own is a keyword but 'COUNTER' can be used as a variable without any
problems. The keywords that can are treated in this way are marked with a
'*' in the keyword list at the end of the notes.


Line Numbers
~~~~~~~~~~~~
Each line in a BASIC program has a line number. This is used when editing a
program at the command line and in the program by such statements as 'GOTO',
'GOSUB', 'ON GOTO', and 'RESTORE'. BBC BASIC is a structured BASIC and line
numbers are largely superfluous if statement types such as these are not
used. They are still needed to identify the line on which an error was
detected when a program runs. Programs and libraries can be written without
line numbers using a text editor such as 'vi'. Line numbers will
automatically be added when the program is loaded. Similarly, programs can
be saved without line numbers, although the default is to include them.

Line numbers are in the range 0 to 65279.


Operators
~~~~~~~~~
BBC BASIC supports the usual range of operators. The following list details
what is available. The operators are given in priority order, with operators
of the same priority grouped together. From highest to lowest priority they
are:

        ^               Exponentiation
------------------
        *               Multiplication
        /               Division
        DIV             Integer division
        MOD             Integer modulus
------------------
        +               Addition and string concatenation
        -               Subtraction
------------------
        =               Equals
        <>              Not equals
        >               Greater than
        <               Less than
        >=              Greater than or equal to
        <=              Less than or equal to
        <<              Left shift              
        >>              Arithmetic right shift
        >>>             Logical right shift
------------------
        AND             Logical AND
------------------
        OR              Logical OR
        EOR             Exclusive OR

There is a point to watch out for when using the comparison and shift
operators. It is not possible to chain these together in an expression, for
example:

        abc% >> 2 <= 10

will give an error. The solution is to put brackets around the first part of
the expression thus:

        (abc% >> 2) <= 10

This is a feature of BASIC V/VI.

Assignment Operators
~~~~~~~~~~~~~~~~~~~~
As well as using '=' for assignments in the normal way, BBC BASIC has two
other assignment operators:

        <variable> += <expression>
        <variable> -= <expression>

'+=' adds <expression> to the variable <variable> and '-=' subtracts it.

Examples:
        abc% += 1
        ghi(N%) -= count
        xyz$ += "abcd"
        table%!offset% -= X%
        $(table%+name%) += "xyz"

Matrix Brandy offers 5 more from BB4W and BBCSDL, and JGH's ARM BBC BASIC
Plus. These are:
        <variable> AND= <expression>
        <variable> OR= <expression>
        <variable> EOR= <expression>
        <variable> MOD= <expression>
        <variable> DIV= <expression>

Examples:
        a% AND=&7F
        a OR=128

These five all operate on integers, and where float values are supplied
will be truncated to integers.  Of the eight assignment operators, only =
and += are valid for string types.

Indirection Operators
~~~~~~~~~~~~~~~~~~~~~
These are equivalent to 'peek' and 'poke' in other versions of BASIC except
that they are far more flexible and powerful.

Strictly speaking these are not proper operators but language constructs.

There are two types of operator, unary and dyadic. The unary ones are:

        ?       Reference to a one byte integer
        !       Reference to a four byte integer
        |       Reference to a floating point value
        ]       Reference to an eight byte integer
        $       Reference to a string

The dyadic operators are:

        ?       Reference to a one byte integer
        !       Reference to a four byte integer

Note that there are not dyadic versions of '$', ']' and '|'.

Unary operators can be followed by a variable, array reference or an
expression in parentheses. For dyadic operators, the item before the
operator must be a variable or array reference. A variable, array reference
or expression in parentheses follows the operator.

Examples of unary operators:

        $pointer%
        !abc%
        ?(abc%+10)
        ](abc%%+40)=8589934592
        $text% = "abc"

Examples of dyadic operators:

        pointer%!offset%
        abc%?next%
        array%(N%)!field%

The operators all work in the same way. The value of the expression after
the operator (unary version) or of the variable before the operator (dyadic
version) is interpreted as an address. The value after the operator in the
dyadic version is a byte offset from that address.

Indirection operators cannot be chained together, that is, they cannot be
used in an expression such as:

        pointer%!offset%!field%

In general, indirection operators can be used in the same way and places as
normal variables and the two forms of reference can be freely mixed.

Examples:

        IF $text%="quit" THEN STOP
        table%!offset% = table%!offset2
        !(table%+offset%) = !(table%+offset2)
        abc = |address+1.0
        PROCabcd(!table%, table%!4)
        FOR table%!8=1 TO 10: NEXT

The interpreter limits the range of addresses that can be read from or
written to using indirection operators to the BASIC workspace. It is not
possible to access any location outside this block of memory.

Indirection operators can be used to built up and manipulate data
structures. However they are not true data structures in the sense of
structs in a C program and there are no checks on the legality of references
(beyond ensuring that the addresses are in range). It is possible for a
program to allocate memory from the BASIC heap to be used used for data
structures and accessed via the indirection operators. A special form of the
DIM statement is used for this:

        DIM table%% 100

Strictly speaking this allocates a byte array with indexes 0 to 100. From a
more practical point of view, it allocates a 101 byte block of memory and
puts its address in table%. This block can then be manipulated using the
indirection operators as desired, for example:

        $table%%="an error message"
        table%%!0 = 0: table%%!4 = 99

In fact, blocks of memory allocated this way can only be referenced via
indirection operators.

Similarly, memory outside the heap can be requested using DIM HIMEM (a
Basalt extension).  This memory can also be freed using DIM HIMEM var%% -1.
Memory allocated this way, like that allocated from the heap using a regular
DIM, can only be referenced via indirection operators.

Numeric arrays can also be defined off-heap using DIM HIMEM, but these use a
different syntax to free them, see CLEAR HIMEM.

Note that it is recommended to use a 64-bit integer when DIMming memory, as
on a 64-bit system there is no guarantee you will be allocated memory in the
bottom 4GB of the memory map.

A word of warning: If this is used in conjunction with LOCAL, the array or
memory block must be deallocated before exiting the procedure, otherwise
your program will cause a memory leak.


Array Operations
~~~~~~~~~~~~~~~~
The interpreter supports some arithmetic operations on entire arrays. There
are some restrictions: the arrays have to be the same size (number of
dimensions and size of each dimension) and of exactly the same type. Also,
general expressions involving arrays are not allowed, nor is it possible to
return an array as the result from a function. What is allowed is as
follows:

Assignment
----------
<array 1> = <array 2>
The contents of <array 2> are copied to <array 1>

<array> = <expression>
All elements of array <array> are set to <expression>

<array> = <expression 1> , <expression 2> , ... , <expression n>
Each expression <expression x> is evaluated and then assigned to the x'th
element of the array <array>. There can be fewer expressions than there are
elements in the array, in which case the remaining array elements are left
unchanged.

<array 1> += <array 2>, <array 1> -= <array2>
Each element of <array 2> is added to <subtracted from) the corresponding
element in <array 1>.

<array> += <expression>, <array> -= <expression>
The expression <expression> is evaluated and the result added to (subtracted
from) each element of <array>.

Examples:
        abc%() = def%()
        ghi$() = "test"
        jkl() = 0.0, 1.1, 2.2, 3.3, FNxyz(4.4)
        abc%() += def%()
        jhl() -= PI

Addition and Subtraction
------------------------
<array 1> = <array 2> + <array 3>
Add the corresponding elements of <array 2> and <array 3> and store the
result in the same element in <array 1>.

<array 1> = <array 2> - <array 3>
Subtract the elements in <array 3> from the corresponding element in array
<2> and store the result in <array 1>.

<array 1> = <array 2> + <expression>
<array 1> = <expression> + <array 2>
Add <expression> to each element of <array 2>, storing the result of each
addition in the corresponding element of <array 1>.

<array 1> = <array 2> - <expression>
<array 1> = <expression> - <array 2>
Subtract <expression> from each element of <array 2>, storing the result of
each subtraction in the corresponding element of <array 1>.

Examples:
        abc%() = def%() + ghi%()
        jkl() = mno() - pqr()
        aaa$() = bbb$() + "ccc" + FNddd(eee$)
        abc%() = 1 - def%()

Multiplication and Division
---------------------------
<array 1> = <array 2> * <array 3>
Multiply each element of <array 2> by the corresponding element in <array 3>
and store the result in <array 1>.

<array 1> = <array 2> / <array 3>
Divide each element of <array 2> by the corresponding element in <array 3>
and store the result in <array 1>.

<array 1> = <array 2> DIV <array 3>
Carry out an integer division of each element of <array 2> by the
corresponding element in <array 3> and store the result in <array 1>.

<array 1> = <array 2> MOD <array 3>
Carry out an integer division of each element of <array 2> by the
corresponding element in <array 3> and store the remainder in <array 1>.

<array 1> = <array 2> * <expression>
<array 1> = <expression> * <array 2>
Multiply each element of <array 2> by the value <expression> and store the
result in the corresponding element in <array 1>.

<array 1> = <array 2> / <expression>
Divide each element of <array 2> by the value <expression> and store the
result in the corresponding element in <array 1>.

<array 1> = <expression> / <array 2>
Divide <expression> by each element of <array 2> and store the result in the
corresponding element in <array 1>.

<array 1> = <array 2> DIV <expression>
Carry out an integer division of each element of <array 2> by the value
<expression> and store the result in the corresponding element in <array 1>.

<array 1> = <expression> DIV <array 2>
Carry out an integer division of <expression> by each element of <array 2>
and store the result in the corresponding element in <array 1>.

<array 1> = <array 2> MOD <expression>
Carry out an integer division of each element of <array 2> by the value
<expression> and store the remainder in the corresponding element in
<array 1>.

<array 1> = <expression> MOD <array 2>
Carry out an integer division of <expression> by each element of <array 2>
and store the remainder in the corresponding element in <array 1>.

Examples:
        abc() = def() * ghi()
        abc() = 10.0 * ghi()
        jkl%() = mno%() MOD 100
        abc() = 1 / abc()

Matrix Multiplication
---------------------
<array 1> = <array 2> . <array 3>
Perform a matrix multiplication of <array 2> and <array 3> and store the
result in <array 1>.

Note that '.' is used as the matrix multiplication operator.

This also supports the vector "dot product" for a pair of one-dimensional
arrays of the same size as per BBCSDL (note this is not supported on
RISC OS).

Portability note: Given that RISC OS does ot support the dot product
directly, this can be implemented in a portable fashion using the normal
array multiplier then running the resulting array thrrough SUM().

Built-in Functions
~~~~~~~~~~~~~~~~~~
The interpreter has a fairly standard set of functions. One feature of this
dialect of BASIC is that many of the functions look like monadic operators,
for example, a call to the 'LEN' function can be written as 'LEN abc$' as
well as 'LEN(abc$)'.

Function names can often be abbreviated when typing them at the command
line. The abbreviated version of the name is the first few characters of the
name followed by a dot, for example, the 'LE' is the abbreviated form of
'LEFT$('. The names are given in full when the program is listed.

Following is a list of functions implemented and a summary of their actions.
More detailed information on the vast majority of them can be found in the
manuals on the 'The BBC Lives!' web site.

Entries marked with a '*' after the name are functions added in this
interpreter.

<factor> represents a simple expression that consists of just a variable
name, array reference or constant or a complete expression in parentheses.

<expression> is a full expression. Sometimes this is written as <string
expression> or <numeric expression> to qualify the type of expression, or
abbreviated to <expr> to reduce clutter.

<array> is a reference to a whole array.

ABS
        Use: ABS <factor>
        Returns the absolute value of the numeric value <factor>

ACS
        Use: ACS <factor>
        Returns the arccosine of the numeric value <factor>

ADVAL
        Use: ADVAL <factor>
        This is an unsupported function. Either use of it is flagged as an
        error or it returns zero, depending on the options used to start the
        interpreter.

ARGC *
        Use: ARGC
        Returns the number of parameters on the command line. This will be
        zero if there are no parameters. 


ARGV$ *
        Use: ARGV$ <factor>
        Returns parameter number <factor> on the command line as a string.
        ARGV$ 0 returns the name of the program. ARGV$ 1 is the first
        parameter, ARGV$ 2 the second and so forth. ARGV$ ARGC is the last
        parameter.

ASN
        Use: ASN <factor>
        Returns the arcsine of the numeric value <factor>

ATN
        Use: ATN <factor>
        Use: ATN(y,x)
        In the first form, this returns the arctan of the numeric value
        <factor>.
        In the second form, this calculates the principal value of the arc
        tangent of (y/x), using the signs of the two arguments to determine
        the quadrant of the result.

BEAT
        Use: BEAT
        Returns information from the RISC OS sound system.

BGET
        Use: BGET# <factor>
        Returns the next byte from the file with handle <factor>

CHR$
        Use: CHR$ <factor>
        Returns a string consisting of a single character with ASCII code
        <factor>

COLOUR
        Use: COLOUR(<red expression>, <green expression>,
                <blue expression>)
        This takes the colour with the specified colour components and
        returns a number that represents the closest match to that colour in
        the current screen mode. This value is for use with the 'COLOUR OF'
        and 'GCOL OF' statements. It has no meaning otherwise.

        Example:
                red = COLOUR(255, 0, 0): COLOUR OF red

COS
        Use: COS <factor>
        Returns the cosine of the numeric value <factor>

COUNT
        Use: COUNT
        Returns the number of characters printed on the current line by
        PRINT.

DEG
        Use: DEG <factor>
        Converts the angle <factor> from radians to degrees.

DIM
        Use: a) DIM(<array>)
             b) DIM(<array>, <expression>)
        a) returns the number of dimensions in array <array>.
        b) returns the highest index of dimemsion <expression> of array
           <array>.

END
        Use: END
        Returns the address of the top of the BASIC heap.

EOF
        Use: EOF# <factor>
        Returns TRUE if the file with handle <factor> is at end of file.

ERL
        Use: ERL
        Returns the number of the line that contained the last error
        encountered by the interpreter or zero if no error has been seen.

ERR
        Use: ERR
        Returns the error number of the last error encountered by the
        interpreter or zero.

EVAL
        Use: EVAL <factor>
        Evaluates the string <factor> as if it were an expression in a
        statement in the program and returns the result.

EXP
        Use: EXP <factor>
        Returns the exponentional of the numeric value <factor>.

FALSE
        Use: FALSE
        The function returns the value corresponding to 'false' in the
        interpreter (zero).

GET
        Use: a) GET
             b) GET(x,y)
        a) Returns the next character pressed on the keyboard as a number,
           waiting if there is not one available.
        b) Returns the character at position (x,y) on the screen.This only
           works in RISC OS or on the SDL build; on text builds this returns
           0.

GET$
        Use: a) GET$
             b) GET$# <factor>
             c) GET$(x,y)
        a) Returns the next character pressed on the keyboard as a
           one character string, waiting if there is not one
           available.
        b) Returns the next line from the open file with handle
           <factor> as a character string.
        c) Returns the character at position (x,y) on the screen. This only
           works in RISC OS or on the SDL build; on text builds this returns
           0.

INKEY
        Use: INKEY <factor>
        If numeric value <factor> is greater than or equal to zero, return
        the next character pressed on the keyboard as a number but only wait
        for <factor> centiseconds. Return -1 if no key pressed in that time.
        If numeric value <factor> is -256, return a number that  identifies
        the operating system under which the program is running. (See the
        'use' guide for the values returned.) If numeric factor <factor> is
        less than zero and greater than -256, return TRUE if the key with
        RISC OS internal key number <factor> is being pressed otherwise
        return FALSE.
        
INKEY$
        Use: INKEY$ <factor>
        This is the same as INKEY but returns its result as a single
        character string. In the case of a keyboard read with timeout, an
        empty string is returned if the time limit expires instead of -1.
        
INSTR(
        Use: INSTR(<expr1> , <expr2> [, <expr3>])
        Search string <expr1> for the string <expr2> returning the index
        (starting from 1) of the start of <expr2> in <expr1> if the string
        is found otherwise return zero. <expr3> is an option expression that
        gives a starting point in <expr1> at which to start looking for
        <expr2>.

INT
        Use: INT <factor>
        Returns the integer part of number <factor>, rounding down (towards
        minus infinity). By default (matching 6502, 32000, PDP11 and ARM
        BASIC) the value must be within the range -2^31 to 2^31-1 that can
        be stored within an integer variable. However, to allow values out
        of this range (so INT actually returns a floating-point value) do:
        SYS "Brandy_INTusesFloat",1

LEN
        Use: LEN <factor>
        Returns the length of string <factor>.

LISTO *
        Use: LISTO
        Returns the current LISTO setting.

LN
        Use: LN <factor>
        Return the natural log of number <factor>.

LOG
        Use: LOG <factor>
        Returns the base 10 log of number <factor>.

MOD     Use: MOD <array>
        Returns the modulus (square root of the sum of the squares) of
        numeric array <array>.

MODE    Use: MODE
        Returns the number of the current RISC OS screen mode.

NOT
        Use: NOT <factor>
        Returns the logical negation (ones complement) of numeric value
        <factor>.

OPENIN
        Use: OPENIN <factor>
        Opens the file named by the string <factor> for input and returns
        its numeric handle or zero if it cannot be opened.

OPENOUT
        Use: OPENOUT <factor>
        Opens the file named by the string <factor> for output and returns
        its numeric handle. If the file exists already its length is reset
        to zero.

OPENUP
        Use: OPENUP <factor>
        Opens the file named by the string <factor> for both input and
        output and returns its numeric handle. Network sockets can also be
        opened, see docs/networking.txt.

PI
        Use: PI
        Returns the value PI.

POINT(
        Use: POINT(<x expr>,<y expr>)
        Returns the colour number of the point on the graphics screen with
        graphics coordinates (<x expr>, <y expr>).

POS
        Use: POS
        Returns the offset (from 0) of the text cursor from the left-hand
        side of the screen.

QUIT
        Use: QUIT
        Returns TRUE if the interpreter was started with the option '-quit',
        that is, the interpreter will be exited from when the BASIC program
        finishes running.

RAD
        Use: RAD <factor>
        Convert the angle <factor> given in degrees to radians.

REPORT$
        Use: REPORT$
        Returns the message for the last error encountered.

RND
        Use: a) RND
             b) RND(<negative expr>)
             c) RND(0)
             d) RND(1)
             e) RND(<expression>)
        a) Return a pseudo-random number in the range -2147483648 to
           2147483647
        b) Initialises the random number generator with seed value
           <negative expr>.
        c) Returns the last number generated by RND(1).
        d) Returns a floating point number in the range 0 to 1.
        e) Returns an integer number in the range 1 to <expression>.

SGN
        Use: SGN <factor>
        Returns -1 if the numeric value <factor> is less than zero, zero if
        it is equal to zero, or 1 if it is greater than zero.

SIN
        Use: SIN <factor>
        Returns the sine of numeric value <factor>.

SQR
        Use: SQR <factor>
        Returns the square root of numeric value <factor>.

STR$
        Use: a) STR$ <factor>
             b) STR$~ <factor>
        a) Converts the numeric value <factor> to a decimal string.
        b) Converts the numeric value <factor> to a hexadecimal string. An
        error is reported if a hexadecimal value cannot be accurately
        represented (e.g. a value greater than 2^31-1 when Hex64 is not
        enabled, or any value greater than 2^63-1, and similar negative
        numbers). 

STRING$(
        Use: STRING$( <expression>, <string expr> )
        Returns a string made from the string <string expr> repeated
        <expression> times.

SUM
        Use: SUM <array>
        If <array> is a numeric array it returns the sum of all of the
        elements of the array. If <array> is a string array it returns a
        string made from all of the elements of <array> concatenated.

SUM LEN
        Use: SUM LEN <array>
        Returns the total length of all of the strings in string array
        <array>.

SYS(
        Use: SYS(<string>)
        This is a wrapper for SYS call OS_SWINumberFromString, and returns
        the SWI number for a given SWI name.

TAN
        Use: TAN <factor>
        Returns the tangent of numeric value <factor>

TEMPO
        Use: TEMPO
        Unsupported RISC OS feature. The function returns zero or generates
        an error depending on intepreter command line options.

TINT
        Use: TINT(<x expr>,<y expr>)
        Returns the TINT value of the position with x and y graphics
        coordinates <x expr> and <y expr> on the screen in 256 colour modes.
        
TOP
        Use: TOP
        Returns the address of the first byte after the BASIC program.

TRACE
        Use: TRACE
        Returns the handle of the file to which TRACE output is being
        written or zero if a file is not being used.

TRUE
        Use: TRUE
        Returns the value used by the interpreter for 'true' (-1).

USR
        Use: USR <factor>
        Calls machine code at address <factor>. Not implemented in this
        interpreter except in one special case. See the 'use' guide.

VAL
        Use: VAL <factor>
        Converts the string <factor> to a number.

VERIFY( *
        Use: VERIFY(<expr 1>, <expr 2> [, <expr 3>] )
        Returns the offset of the first character in string expression
        <expr 1> that is not in string <expr 2> or zero if all characters in
        <expr 1> are in <expr 2>. <expr 3> is the optional position at which
        to start the search.

VDU
        Use: VDU <factor>
        Returns the value of the RISC OS mode variable given by <factor>.
        This can be used to determine such things as the screen width, the
        number of colours and so forth. Refer to the section 'Mode
        Variables' below for more details.
        
VPOS
        Use: VPOS
        Returns the offset (from zero) from the top of the screen of the
        text cursor.

WIDTH
        Use: WIDTH
        The function returns the current value of 'WIDTH' (the width of the
        current line as set by the program) or zero if a line width has not
        been defined via the WIDTH statement.

XLATE$( *
        Use: a) XLATE$(<expr 1>)
             b) XLATE$(<expr 1>, <expr 2>)
        a) Returns the string expression <expr 1> with all upper case
           characters converted to lower case.
        b) Returns the string expression <expr 1> with the characters
           translated using string expression or string array <expr 2>.
           Characters in <expr 1> are replaced with the character in the
           position corresponding to the ASCII code of the original
           character.


Pseudo Variables
~~~~~~~~~~~~~~~~
Pseudo variables are a half way house between a function and a variable.
When they appear in the right hand side of an expression they are functions
but they can also appear on the left hand side of an expression too.

Pseudo variables cannot follow the keyword 'LET', that is, using them in
statements such as:

        LET FILEPATH$="."

is not permitted. Similarly, they can only be followed by '=', that is,
assignments of the form '<something>+=<value>' are not allowed.

EXT
As a function:
        Use: EXT# <factor>
        Returns the size of the open file with the handle <factor>.

        Example:
                oldsize% = EXT#file%

On left-hand side:
        Use: EXT# <factor> = <expression>
        Change the size of the open file with handle <factor> to
        <expression> bytes.

        Example:
                IF action$="delete" THEN EXT#file% = 0

FILEPATH$
As a function:
        Use: FILEPATH$
        Returns the list of directories to search when trying to find a
        library or a program.

        Example:
                PRINT"Current search path: ";FILEPATH$

On left-hand side:
        Use: FILEPATH$ = <expression>
        Sets the directory list to the string expression <expression>. Note
        that there are no checks to make sure that the directory names are
        valid. Setting FILEPATH$ to an empty string is allowed.

        Example:
                FILEPATH$ = "/home/mine,/usr/local/basic"

HIMEM
As a function:
        Use: HIMEM
        Returns the address of the end of the BASIC workspace.

        Example:
                PRINT "Top of workspace is at ";~HIMEM

On left-hand side:
        Use: HIMEM = <expression>
        This sets the address of the top of the BASIC workspace to the value
        of the numeric expression <expression>. If the new value of HIMEM
        puts it in the BASIC program or outside the BASIC workspace, the
        statement is ignored.

        Example:
                HIMEM = HIMEM-1000

        The places where HIMEM can be changed are limited. It cannot be
        altered in a procedure, function or subroutine, nor in the body of a
        loop. The only safe place to change it is at the start of a program.

LEFT$
As a function:
        Use: LEFT$(<string expression> [, <expression>)
        Returns the left-hand <expression> characters from the string
        <string expression>. <expression> can be omitted, in which case
        <string expression> with the last character removed is returned.

        Examples:
                LEFT$(abc$, 4)
                LEFT$($table%, 10)
                LEFT$(xyz$(X%))

On left-hand side:
        Use: LEFT$(<string variable> [, <expression>])
                                        = <string expression>
        This replaces the left-hand characters of string <string variable>
        with the string expression <string expression>. <expression> says
        how many characters to replace. If it is omitted then the length of
        <string expression> is used. If this value exceeds the original
        length of <string variable> then the length of <string variable> is
        used instead.

        <string variable> can be a normal string variable, an array
        reference or a string referenced by the string indirection operator.

        Examples:
                LEFT$(abc$)="1234"
                LEFT$(abc$, 2)="abcdefgh"
                LEFT$(xyz$(X%), 5)="123"
                LEFT$($table%, 3)="pqrst"

LOMEM
As a function:
        Use: LOMEM
        Returns the address of the start of the BASIC heap

        Example:
                PRINT"Variables start at ";~LOMEM

On left-hand side:
        Use: LOMEM = <expression>
        This changes the address of the start of the BASIC heap to the
        numeric value <expression>. All of the variables created so far are
        discarded when LOMEM is changed. If the value is outside the range
        TOP to HIMEM it is ignored. The assignment is also ignored if LOMEM
        is changed in a function or procedure.

        Examples:
                LOMEM = LOMEM+1000

MID$
As a function:
        Use: MID$(<string expression>, <start expression>
                                        [, <length expression>] )

        Returns a substring from the string <string expression> starting at
        character position <start expression>. The substring is of length
        <length expression> characters. <length expression> can be omitted,
        in which case the the string from the <start expression>'th
        character to the end of the string is returned.

        If <start expression> is negative or exceeds the length of the
        string the empty string is returned. If <length expression> is
        negative or exceeds the number of characters in the string, the
        original string is returned.

        Examples:
                A$ = MID$(B$, 10)
                A$ = MID$(B$, 10, 20)
                A$ = MID$($table%, 5, 10)


On left-hand side:
        Use: MID$(<string variable>, <start expression>
                [, <length expression>] ) = <string expression>
        The characters of the string <string variable> starting at character
        position <start expression> are overwritten by characters from
        string <string expression>. <length expression> is optional and says
        how many characters are to be taken from <string expression>. If it
        is omitted then all of <string expression> is used.

        Only the existing characters of <string variable> are overwritten.
        The length of the string is never changed.

        If <start expression> is negative then <string variable> is
        overwritten from the start of the string. If it exceeds the length
        of <string variable> then nothing is changed. If <length expression>
        is negative then the length of <string expression> is used instead.

        Examples:
                MID$(A$, 5) = "ABCD"
                MID$(A$, 10, 10) = X$ + "abcdefghijklmnop"
                MID$($table%, 10) = "12345"

PAGE
As a function:
        Use: PAGE
        Returns the address of the start of the BASIC program.

        Example:
                PRINT"The program starts at ";~PAGE

On left-hand side:
        Use: PAGE = <expression>
        This sets the address of the start of the BASIC program in memory to
        <expression>. Any program currently loaded is discarded. The change
        is ignored if the value of <expression> is outside the range of the
        value of PAGE when the interpreter was started to HIMEM.

        Note: one trick possible with the Acorn interpreter is to hold
        several programs in memory at the same time and to switch between
        them by altering PAGE. This does not work with the current version
        of this interpreter. 

        Example:
                PAGE = PAGE + 1000

PTR
As a function:
        Use: PTR# <factor>
        Returns the value of the offset in bytes of the file pointer in the
        open file with handle <factor>.

        Example:
                place = PTR# thefile%

        Additionally, PTR can get the address of an array or string.

        Example 1:
                stringptr%% = PTR(string$)
        Note that the string is not terminated.

        Example 2:
                arrayptr%% = PTR(array())
        This points to the array structure (see basicdefs.h structure
        basicarray). The address of the first member of the array is stored
        at ](arrayptr%%+8). The address is zero padded on 32-bit platforms.

On left-hand side:
        Use: PTR# <factor> = <expression>
        Sets the file pointer of the open file with handle <factor> to
        <expression>. This is offset into the file in bytes.

        Example 1:
                PTR# thefile% = 0

        Example 2:
                PTR(array()) = arrayptr%%
        This sets array() to use the array structure contained at
        arrayptr%%. 

RIGHT$
As a function:
        Use: RIGHT$(<string variable> [, <expression>] )
        Returns a string containing the right-most <expression> characters
        from the string <string variable>. It is possible to omit
        <expression>, when just the last character is returned. If
        <expression> is zero or negative, the empty string is returned. If
        it exceeds the length of <string variable>, the original string is
        returned.

        Examples:
                RIGHT$(A$, 5)
                RIGHT$(X%) + RIGHT$(Y$)

Om left-hand side:
        Use: RIGHT$(<string variable> [, <expression>]) =
                                        <string expression>
        The right-most <expression> characters of the string <string
        variable> are overwritten with character from <string expression>.
        If <expression> is omitted, the length of the string <string
        expression> is used instead. If it is zero or negative, <string
        variable> is left unchanged. The length of the string <string
        variable> is never changed.

        Examples:
                RIGHT$(A$) = "1234"
                RIGHT$(A$, 5) = "abcdefgh"
                RIGHT$($table%, 1) = A$

TIME
As a function:
        Use: TIME
        Returns the current value of the centisecond counter. This is a
        32-bit timer updated one hundred times per second, although the real
        accuracy depends on the underlying operating system.

        Example:
                newtime = TIME+100

On left-hand side:
        Use: TIME = <expression>
        Sets the centisecond counter to <expression>.

        Example:
                TIME = 0

TIME$
As a function:
        Use: TIME$
        Returns the current date and time as a string in the form:
        "www,dd mmm yyyy.hh:mm:ss"

        Example:
                now$ = TIME$

On left-hand side:
        Use: TIME$ = <expression>
        Sets the date and time to the string expression <expression>.
        This feature is not implemented, and does nothing.


Procedures and Functions
~~~~~~~~~~~~~~~~~~~~~~~~
BASIC V/VI has both procedures and multi-line functions. They can both take
parameters of any sort, including arrays, and it is possible to return
values via parameters. They can also have local variables.

Procedures and functions are declared in the same way:

Procedures:     DEF PROC<name> [ ( <parameter list> ) ]
Functions:      DEF FN<name> [ ( <parameter list> ) ]

<name> is the name of the procedure or function. The keywords 'PROC' and
'FN' are considered to be part of the name.

<parameter list> is the list of variables to be used as formal parameters.
There can be any number of these. Names are separated by commas. Parameters
where values are to be returned are preceded by the keyword RETURN.

Examples:

        DEF PROCabc
        DEF PROCxyz(aa$)
        DEF FNpqr(X%, abc%, def$)
        DEF PROCijk(RETURN X%, RETURN Y%)
        DEF FNmno(array())
        DEF PROCpqr(array1$(), RETURN array2$())

When a procedure or function is called, the current values of the variables
that are to be used as parameters are saved before they are set to the
values they will take for the call. When the call ends their old values are
restored.

All of the parameters are evaluated before the values are assigned to the
parameter variables.

Procedures and functions are called in the normal way, for example:

        PROCxyz("abcd")
        value = FNpqr(A%+1, B%+2, C$+"3")

Calls to procedures are ended with ENDPROC. Calls to functions end with an
'=' followed by the value the function is to return, for example:

        DEF PROCabc(X%)
        IF X%=0 THEN ENDPROC
        Y% = Y% DIV X%
        ENDPROC

        DEF FNxyz(X%)
        IF X%=0 THEN = 0
        = Y% DIV X%

Note that the name of a function does not include the type of the result it
will return. It is possible for the same function to return both string and
numeric values, but this is of very limited use. (The only place it will not
give an error is in a PRINT statement.)

Recursive calls to procedures and functions are allowed. The only limit on
the depth of the recursion is the amount of memory available.

Procedures and functions can have local variables. These are defined by
means of the LOCAL statement. The format of this is:

        LOCAL <list of variables>

for example:

        LOCAL abc%, def, ghi$, jkl$

Any number of local variables can be declared. It is also possible to have
local arrays. These are slightly more complicated in that the array is
declared to be local and its dimensions defined separately, thus:

        LOCAL array()
        DIM array(100)

The scope of local variables is dynamic, that is, they are not restricted to
the procedure or function in which they were defined. It is perhaps easier
to understand this by considering what happens: when a variable is declared
to be local, its value (if the variable exists already) is saved and the
value reset to zero (or the empty string). When the procedure or function is
returned from, the old value is restored. Declaring a variable to be local
does not create a new version of that variable. The same variable is still
used but its old value is saved first.


Error Handling
~~~~~~~~~~~~~~
BBC BASIC provides two statements for dealing with errors, ON ERROR and ON
ERROR LOCAL. ON ERROR is the less sophisticated of the two. If an error is
detected, the interpreter ends all loops and returns from all procedures,
functions and subroutines before continuing with the statements after ON
ERROR. It is not possible to recover from the error and restart the program
at the point where it occured. Most of the time all that can be done is to
tidy up and abort the program. ON ERROR LOCAL gives more control in that
when an error occurs, the statements after the ON ERROR LOCAL are executed
but everything is left as it was at the time of the error. This means it is
possible to trap errors and recover from them.

The statement 'ON ERROR OFF' turns off the trapping of errors in the
program. This should be used at the start of an error handler to prevent
errors in the error handler causing an infinite loop.

To allow for finer control over errors, BASIC V/VI also has two statements
that allow different error handlers to be used at different points in the
program, LOCAL ERROR and RESTORE error. LOCAL ERROR stores details of any
existing error handler and allows a new one to be set up. RESTORE ERROR
restores the error handler to the saved one. If LOCAL ERROR is used in a
function or procedure, the old error handler is restored when the function
or procedured calls ends.

Care should be taken if using ON ERROR LOCAL within the body of a loop. If
an error is detected once the program has exited from the loop, it will
branch back into it when the interpreter goes to the statements after ON
ERROR LOCAL. The interpreter is unaware of the context of the error handler
(that is, it has back into the body of a loop) and unpredictable results
might ensue.

The function REPORT$ returns the last error message. ERR returns the number
of that error and ERL the number of the line in which it occured. Note that
this does not say whether the error occured in the program or a library.
The REPORT statement displays the last error message. The ERROR statement
can be used to report user-generated errors. The interpreter allows the use
of the LIST command in programs, so it is possible for error handlers to
list the line in which the error occured by the statement

        LIST ERL

Note that the line listed will always be in the BASIC program so if the
error occured in a library the wrong line will be shown.

Some of the errors that the interpreter flags are classed as 'fatal', for
example, running out of memory. The BASIC program is always abandoned if a
fatal error occurs. It is not possible to trap them with ON ERROR or ON
ERROR LOCAL.


Issuing Commands to the Underlying Operating System
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are two ways in which commands can be send to the operating system on
which the interpreter is running. The most flexible way is the OSCLI
statement. The second way is to put the command on a line preceded by a
'*', for example:

        10 *date
        20 IF flag THEN *help

Whatever follows the '*' up to the end of the line is passed as the command.

There is no restriction on the commands that can be issued this way.


Statement Types
~~~~~~~~~~~~~~~
Statements are broken into two types, executable statements that can appear
in a program and commands that, in general, can only be used on the command
line.

Many of the keywords and commands can be abbreviated when they are typed in.
They will be shown in their complete form when the program is listed. The
rule is to type in the minimum number of characters of the keyword and then
follow it with a dot, for example:

        P.

can be type instead of 'PRINT'. The minimum abbreviation for each keyword
and command is given in the section 'BASIC Keywords, Commands and Functions'
at the end of these notes.

All of the BBC BASIC statement types are described below. However, not all
versions of the Matrix Brandy interpreter support all of them, in
particular, the graphics statements might not be available.

Statements
~~~~~~~~~~
In the following:

<factor> represents a simple expression that consists of just a variable
name, array reference or constant or a complete expression in parentheses.

<expression> is a full expression. Sometimes this is written as <string
expression> or <numeric expression> to qualify the type of expression, or
abbreviated to <expr> to reduce clutter.

<array> is a reference to a whole array.

<statements> is one or more BASIC statements.

Items in square brackets are optional.


BEATS
Statement for controlling the RISC OS sound system.

BPUT
Syntax: a) BPUT#<factor>, <expression> [;]
        b) BPUT#<factor>, <expr 1>, <expr 2>, ... ,<expr n> [;]

BPUT is used to write data to a file. The handle of the file is given by
<factor>. <expression> is the value to be written. If <expression> is
numeric, the result of the expression modulo 256 (that is, the least
significant byte) is written to the file. If <expression> is a string, the
complete string is written to the file. If the string expression is followed
by a ';' that is all that happens. If the ';' is absent, a 'newline'
character (ASCII code 10) is also written to the file after the string.

The second form of the BPUT statement is the same as the first except that a
list of items to be written separated by commas can be supplied. If the last
item is a string expression then a new line character is also written to the
file unless the expression is followed by a ';'.

Examples:
        BPUT#outfile, X%
        BPUT#outfile, A$
        IF TRACE THEN BPUT#TRACE, "Result so far is "+STR$X%
        BPUT#outfile, 1, 2, 3, 4, 5
        BPUT#outfile, STR$A%, " ", STR$B%

CALL
This is an unsupported statement that allows machine code subroutines to be
called.

This statement is supported for calling a subset of BBC MOS calls, however
this is not the recommended method as it is not possible to pass complete
64-bit addresses via X% and Y%.

CASE
Syntax: CASE <expression> OF

This marks the start of a CASE statement. This statement must be the last
one on a line.

The complete syntax of a CASE statement is:

        CASE <expression> OF
        WHEN <expression 1>: <statements>
        WHEN <expression 2>: <statements>
        OTHERWISE: <statements>
        ENDCASE

The expression <expression> is evaluated. The interpreter then searches for
'WHEN' statements and evaluates each expression after the 'WHEN' in turn and
compares it to the result of <expression>. If they are equal it starts
executing the statements <statements> after the 'WHEN' from that point to
the next 'WHEN', 'OTHERWISE' or 'ENDCASE'. At this point it jumps to the
statements after the ENDCASE.

Any number of expressions (limited by the length of the line) can follow the
WHEN keyword. They are separated by commas.

The expressions after the WHEN keyword do not have to be constants. Any type
of expression is allowed and they can be of numeric or string types.

The WHEN keyword must be the first item on a line after the line number
(except for any intervening blanks). The same goes for the OTHERWISE and
ENDCASE keywords.

CASE statements can be nested to any depth.

Examples:

        CASE day$ OF
        WHEN "Monday": PRINT"It is Monday"
        WHEN "Tuesday", "Thursday":
          PRINT"It is Tuesday or Thursday"
        WHEN "Friday":
          PRINT"It is Friday"
        WHEN "Wednesday": PRINT"It it the middle of the week"
        OTHERWISE
          PRINT"It is the weekend"
        ENDCASE

As general expressions can be used after the WHEN, CASE statements are very
flexible. Here one is being used in place of a series of IF statements:

        CASE TRUE OF
        WHEN abc%<10: state%=1
        WHEN abc%=10: state%=2
        WHEN abc%>20 AND abc%<20: state%=3
        OTHERWISE: state%=99
        ENDCASE

CHAIN
Syntax: CHAIN <string expression>

CHAIN loads and runs the program named by the string <string expression>.
The programs currently in memory is replaced by this one and the values of
all variables lost, with the exception of the static integer variables.

Extension: The interpreter searches for the program to load in the
directories given by the pseudo-variable FILEPATH$.

CIRCLE
Syntax: a) CIRCLE <x expression>,<y expression>,<expression>
        b) CIRCLE FILL <x expression>,<y expression>,<expression>

a) This draws a circle outline centred at (<x expression>, <y expression>)
   and with a radius <expression> in the current graphics foreground colour.

b) This version plots a filled circle centred at (<x expression>,
   <y expression>) and with a radius <expression> using the current
   graphics foreground colour.

CLG
Syntax: CLG

This statement clears the graphics window (normally the whole screen) to the
current graphics background colour.

CLEAR
Syntax: CLEAR [HIMEM [<array()>]]

CLEAR discards all of the variables and arrays created so far in the
program. It also clears the chain of called procedures and functions so it
should not be used in a procedure or function.

Example:
        IF silly% THEN CLEAR

Matrix Brandy extends the CLEAR syntax with CLEAR HIMEM [<array()>] which
will de-allocate the off-heap array if specified, or all arrays defined
using DIM HIMEM.

CLOSE
Syntax: CLOSE# <factor>

The CLOSE statement closes one or more open files. <factor> is a numeric
value that gives the handle of the file to close. If <factor> is zero then
*all* files that have been opened by the BASIC program are closed.

Example:
        CLOSE#outfile%

CLS
Syntax: CLS

CLS clears the screen (or the current text window if one is being used). It
also sends the cursor to the top left-hand corner of the screen.

Example:
        IF full% THEN CLS

COLOUR
Syntax: a) COLOUR <expression>
        b) COLOUR <colour expression> TINT <tint expression>
        c) COLOUR <red expression>, <green expression>, <blue expression>
        d) COLOUR <logical expression>, <physical expression>
        e) COLOUR <colour expression>, <red expression>, <green expression>,
                  <blue expression>
        f) COLOUR OF <expression> ON <expression>
        g) COLOUR OF <red expression>, <green expression>, <blue expression>
                  ON <red expression>, <green expression>, <blue expression>

The COLOUR statement is used to change the colour being used when writing
text on the screen. It is also used to change the physical colour
corresponding to the given logical colour.

a) This sets the colour to be used when writing text on the screen.
   <expression> is a numeric value. It is reduced modulo the number of
   colours available in the current screen mode. The colour changed is the
   logical colour.

If the original value of <expression> is less than 128, the colour changed
is the text foreground colour; otherwise the background colour is altered.
128 is subtracted from the vale of <expression> to get the colour number.

b) This version of the statement is used in 256 colour modes to set the
   colour used for writing text on the screen. <colour expression> sets the
   logical colour and <tint expression> sets the 'tint' value. If the value
   of <colour expression> is less than 128 then the foreground colour is
   changed otherwise the background one is altered. Whether or not <colour
   expression> is less than 128 affects whether the foreground tint value or
   background tint value is the one changed by <tint expression>.

The colour value is reduced modulo 64 to obtain the colour. The tint value
has set values: 0, 64, 128 and 192. The increasing tint value has an effect
on the brightness of the colour. See the section '256 Colour Modes' below
for an explanation of how the colour and tint work together.

c) This sets the current text foreground colour to the colour with
   components <red expression>, <green expression>, <blue expression>. The
   values of the colour components are reduced modulo 256. The colour is
   mapped to the nearest equivalent colour in the current screen mode.

d) This version of the COLOUR statement changes the mapping
   between the logical colour number and the colour displayed on the screen
   in screen modes which have less than 256 colours. <logical expression> is
   the logical colour number whose mapping is to be changed. The value is
   reduced modulo the number of colours in the current screen mode.
   <physical colour> is the colour number of the physical colour to be used.
   The colour numbers are given in the section '2, 4 and 16 Colour Modes'
   below.

e) This version of the statement is related to c) above in that it alters
   the colour displayed for a given logical colour number in screen modes
   with more than sixteen colours available. <colour expression> is the
   number of the colour to change and <red expression>, <green expression>
   and <blue expression> are the red, green and blue components of the new
   colour. These are reduced modulo 256. The colour number is also reduced
   modulo 256.

f) This version of the statement has two parts, the 'OF' part and the 'ON'
   part. The 'OF' part gives the foreground colour and the 'ON' part the
   background colour. Either of these parts can be omitted but not both of
   them. The value <expression> is the colour number to use.

g) This version has two parts, the 'OF' part and the 'ON' part where the
   'OF' part is used to give the foreground colour and the 'ON' part the
   background colour. The three expressions after each keyword, <red
   expression>, <green expression> and <blue expression>, give the red,
   green and blue components of the colour to use. The colour that will
   actually be used is the closest match to this colour in the current
   screen mode. Either the 'OF' or the 'ON' part can be left out but not
   both.

Examples:
        COLOUR 5
        COLOUR 23 TINT &C0
        COLOUR 2, 128, 128, 128
        COLOUR OF 0, 0, 255 ON 0, 0, 0
        COLOUR ON 191, 191, 191
        COLOUR ON COLOUR(191, 191, 191)

The 'COLOUR OF' statement (along with 'GCOL OF') represent a new way of
selecting colours to use on screen. Along with the 'COLOUR()' function they
provide a means of specifying colours independently of the screen mode, for
example:

        pink = COLOUR(255, 127, 255) 
        blue = COLOUR(0, 0, 255)
        COLOUR OF pink ON blue

This avoids use of the 'TINT' keyword.

DATA
Syntax: DATA <items of data>
The DATA statement provides the data to be read by a READ statement. It must
be the first keyword on a line after the line number.

<items of data> is one or more items of data separated by commas.

DEF
'DEF' marks the start of a procedure or function definition. It must be the
first non-blank item on a line after the line number. Refer to the section
'Procedures and Functions' above for more information.

Examples:
        DEF PROCfirst
        DEF FNsecond(X%)


DIM
Syntax: DIM <list of arrays>

The DIM statement is used to declare arrays. <list of arrays> contains one
or more arrays to be declared separated by commas. There are two types of
array declation. The format of a normal array declaration is:

        <name>( <expression 1> , ... , <expression n> )

where <name> is the name of the array and <expression 1> to <expression n>
are the array's dimensions. Arrays can have up to ten dimensions and their
size is limited only by the available memory.

Array indexes start at zero with the size given in the array declaration as
the highest index of each dimension.

Note that the '(' is considered part of the array name.

Examples:

        DIM abc%(100), def(10,10), ghi$(size%+10)

The second form is used to allocated blocks of memory. There are two
versions of this:

        <variable> <expression>
        <variable> LOCAL <expression>

where <variable> is the name of a variable and <expression> is the size of
the block to allocate in bytes. The address of the block is stored in
<variable>.

The first form can be used anywhere but the second can only be used in a
procedure or function. In the second case the block is allocated on the
BASIC stack and is automatically returned when the procedure or function
containing the DIM statement ends. In the first case memory is obtained from
the BASIC heap and it cannot be returned to the heap for reuse later.

To be more accurate, the second form allocates a byte array with a low index
of zero and a high index of <expression>. For this reason the size of the
block allocated is actually <expression>+1 bytes.

Examples:
        DIM heap% 100000, block% 100
        DIM abc%(10), block% 1000
        DIM xyz% LOCAL 1000
        LOCAL ptr%: DIM ptr% LOCAL 100

One trick is to declare an array in this way with a size of -1 bytes. This
stores the address of the current top of the BASIC heap in the variable, for
example:

        DIM heaptop% -1

The same effect can be obtained using the function 'END'.

Local Arrays
------------
The interpreter allows local arrays to be created in procedures and
functions. The memory for these is reclaimed when the procedure or function
call ends.

The way in which local arrays are defined is as follows:

        LOCAL <array>
        DIM <array>

In other words, the array is declared local first and then its dimensions
are defined, for example:

        LOCAL abc$()
        DIM abc$(10,10)

Off-heap Arrays
---------------
The interpreter allows arrays to be defined outside of the BASIC heap
workspace, and as such can be as large as available memory permits.
Numeric arrays and memory blocks can be declared this way; string arrays
cannot be created off-heap.

The way in which off-heap arrays are defined is as follows:

        DIM HIMEM <array>

Such arrays (not memory blocks) can be cleared and de-allocated using
the syntax CLEAR HIMEM.[<array()>]. Once cleared, the array variable can
be re-dimensioned with another DIM [HIMEM] call. This allows a BASIC program
to resize an array at runtime without having to clear every single variable.

A memory block allocated this way can be de-allocated as follows:

        DIM HIMEM pointer%% -1


DRAW and DRAW BY
Syntax: a) DRAW <x expression> , <y expression>
        b) DRAW BY <x expression> , <y expression>

The DRAW statement draws a line in the current graphics foreground colour
from the current graphics cursor position to the one given by <x
expression>, <y expression>.

a) <x expression> and <y expression> are absolute coordinates.

b) <x expression> and <y expression> are the offsets from the current
graphics cursor position of the end point of the line.

Examples:
        DRAW 500,100: DRAW 500,500: DRAW 100,100
        DRAW BY 400,0: DRAW BY 0,400: DRAW BY -400,-400

ELLIPSE
Syntax: a) ELLIPSE <x expression> , <y expression> ,
                         <semi-major> , <semi-minor> , <angle>
        b) ELLIPSE FILL <x expression> , <y expression> ,
                         <semi-major> , <semi-minor> , <angle>

The ELLIPSE statement draws an ellipse. The coordinates of the centre are
(<x expression>, <y expression>). <semi-major> and <semi-minor> are the
lengths of the semi-major and semi-minor axes respectively. <angle> is the
angle between the semi-major axis and the x axis in radians.

a) This draws an ellipse outline.

b) This draws a filled ellipse.

Example:
        ELLIPSE 500, 500, 400, 200, 0.5

ELSE
Syntax: ELSE

The ELSE statement is part of an IF statement. Refer to the section on the
IF statement for more information.

END
Syntax: END

As a statement, END stops the program.

Example:
        IF alldone THEN END

ENDCASE
Syntax: ENDCASE

Part of a 'CASE' statement. It marks the end of the statement. Refer to the
section on the 'CASE' statement above for more details.

ENDIF
Syntax: ENDIF

Part of a block 'IF' statement. It marks the end of the statement. Refer to
the section on the 'IF' statement below for more information.

ENDPROC
Syntax: ENDPROC

The ENDPROC statement is used to return from a procedure to the calling
routine. Variables corresponding to RETURN parameters are set to the their
returned values, all local variables declared in the procedure are restored
to their original values and local arrays destroyed. The effects of any
LOCAL DATA or LOCAL ERROR statements are undone. Control then passes back to
the statement after the procedure call.

Example:
        IF count%=0 THEN ENDPROC

ENDWHILE
Syntax: ENDWHILE

ENDWHILE marks the end of a WHILE loop. Refer to the section below on the
WHILE statement for more information.

Example:
        ENDWHILE

ENVELOPE
Syntax: ENVELOPE <expression 1> , ... , <expression 14>

This statement passes the command to the sound system. Any effect it has
depends on if the sound system supports ENVELOPE.

ERROR
Syntax: ERROR <error expression> , <string expression>

The ERROR statement is used to generate a user-defined error. <error
expression> is the number of the error and <string expression> is the error
message. Errors raised this way can be trapped just like any other using ON
ERROR and ON ERROR LOCAL.

Example:
        ERROR 25, "Bad error"

EXIT
Syntax: EXIT FOR, EXIT REPEAT or EXIT WHILE

EXIT breaks out of a loop, jumping to the statement immediately after the
matching NEXT, UNTIL or ENDWHILE as appropriate.

This is an extension based on BB4W, BBCSDL, BBCTTY and BBCZ80 v5. Note that
if EXIT FOR is used, every FOR should have its own matching NEXT, properly
nested, and not using multiple control variables on a single NEXT. Unlike
BB4W, EXIT FOR does not accept a control variable.

FALSE
Syntax: FALSE

FALSE returns the value corresponding to 'false' in the interpreter, zero.

Example:

        flag = FALSE

FILL and FILL BY
Syntax: a) FILL <x expression>, <y expression>
        b) FILL BY <x expression> , <y expression>

The FILL statement is used to flood-fill areas with the current graphics
foreground colour.

a) <x expression> and <y expression> give the coordinates of the point at
   which to start the flood fill.

b) <x expression> and <y expression> give the offsets from the current
   graphics cursor position at which to start the flood fill.

Example:
        FILL 500,100

FOR
Syntax: FOR <variable> = <start expression> TO <end expression>
                        [ STEP <step expression> ]

The FOR statement marks the start of a FOR loop. <start expression> and <end
expression> are numeric values that give the start and end values for the
loop index, <variable>. <step expression> is optional and gives the amount
by which the loop index is incremented or decremented on each iteration. If
omitted, it defaults to one.

Execution continues from the statement after the FOR statement to the first
NEXT statement encountered. At this point the loop index is incremented (or
decremented if the step value is negative) and compared against the end
expression. If it exceeds that value (or is less than it if the step is
negative) the loop is terminated, otherwise program execution continues back
at the statement after the FOR.

The body of the loop will be executed at least once.

<end expression> and <step expression> are evaluated only once, at the start
of the loop.

As with all the loop constructs, exiting the loop will automatically undo
the effect of any LOCAL DATA or LOCAL ERROR statements that were used in the
loop. Loops badly nested within the FOR loop body will also be silently
ignored.

Examples:
        FOR N% = 1 TO 10: NEXT
        FOR N% = 10 TO 1 STEP -1: NEXT
        FOR abc = FNstart TO FNfinish STEP 10: NEXT
        FOR array%(5) = 1 TO 10: NEXT array%(5)

The last example shows that the loop index does not have to be a simple
variable.

GCOL
Syntax: a) GCOL <colour expression>
        b) GCOL <colour expression> TINT <tint expression>
        c) GCOL <action expression> , <colour expression>
        d) GCOL <action expression> , <colour expression>
                                        TINT <tint expression>
        e) GCOL <red expression> , <green expression> ,
                                        <blue expression>
        f) GCOL OF <expression> ON <expression>
        g) GCOL OF <action expression>, <expression>
                 ON <action expression>, <expression>
        h) GCOL OF <red expression>, <green expression>,
                <blue expression> ON <red expression>,
                <green expression>, <blue expression>
        i) GCOL OF <action expression>, <red expression>, 
                <green expression>, <blue expression> 
                ON <action expression>, <red expression>,
                <green expression>, <blue expression>


GCOL is used to set the graphics foreground or background colour. The
various combinations are as follows:

a) Set the graphics colour to logical colour number <colour expression>.
   This value is reduced modulo the number of colours available in the
   current screen mode in 2, 4 and 16 colour modes and modulo 64 in 256
   colour modes. If the value is less than 128 then the foreground colour is
   altered. If it is 128 or more, 128 is subtracted from the colour number
   and the background colour changed.

b) Set the graphics colour to logical colour number <colour expression> and
   the 'tint' value to <tint expression>. This version is used in 256 colour
   modes. The colour number is reduced modulo 64. The tint value should be
   set to 0, 64, 128 or 192.

c) This form changes the graphics colour to logical colour number <colour
   expression> and sets the graphics plot action to <action expression>.

d) This is a combination of cases b) and c) and is used in 256 colour modes.
   The graphics colour is set to colour number <colour expression> with tint
   value <tint expression>. The graphics plot action is set to <action
   expression>.

e) The current graphics foreground colour is set to the colour with colour
   components <red expression>, <green expression> and <blue expression>.
   The colour used will be the closest match to the specified colour in the
   current screen mode.

f) and g) are very similar. There are two parts to the statement, the 'OF'
   part and the 'ON' part. The 'OF' part gives the colour to use for the
   graphics foreground colour and the 'ON' part the background colour. In
   case f), only the colour is given but in g) both the colour and the
   graphics plotting action are supplied. It is possible to leave out either
   of the 'OF' or the 'ON' parts but not both.

h) and i) are similar.  There are two parts to the statement, the 'OF' part
   and the 'ON' part. The 'OF' part gives the components of the colour to
   use for the graphics foreground colour and the 'ON' part the components
   of the background colour. The actual colour used will be the closest
   match to the specified colour in the current screen mode. In case h),
   only the colour is given but in i) both the colour and the graphics
   plotting action are supplied. It is possible to leave out either of the
   'OF' or the 'ON' parts but not both.

Examples:
        GCOL OF 192,192,192
        GCOL OF 0, 0, 0 ON 255,255,255
        GCOL OF 1, 15
        GCOL OF COLOUR(0, 0, 255)

The 'CCOL OF' statement (along with 'COLOUR OF') represent a new way of
selecting colours to use on screen. Along with the 'COLOUR()' function they
provide a means of specifying colours independently of the screen mode, for
example:

        pink = GCOL(255, 127, 255) 
        blue = GCOL(0, 0, 255)
        GCOL OF pink ON blue

This avoids the use of the 'TINT' keyword, which is really only of use in
old-style RISC OS 256 colour modes.

GOSUB
Syntax: a) GOSUB <line number>
        b) GOSUB ( <expression> )

The GOSUB statement calls a subroutine. Control passes back to the statement
after the GOSUB by means of a RETURN statement.

a) The subroutine to be called starts at line <line number>.

b) The line number of the subroutine to be called is found given by the
   numeric expression <expression>.

Note that the RENUMBER command will update the line numbers in the first
form of GOSUB above but it cannot handle the second form.

Example:
        GOSUB 1000

GOTO
Syntax: a) GOTO <line number>
        b) GOTO ( <expression> )

Program execution continues at the line specified on the GOTO statement.

a) The number of the line is given explicitly and so the interpreter can go
   to that line immediately.

b) The line number is given by the numeric expression <expression>.

Note that the RENUMBER command will update the line numbers in the first
form of GOTO above but it cannot handle the second form.

IF
Syntax: a) IF <expression> [ [ THEN ] <statements> ]
                                [ ELSE <statements> ]
        b) IF <expression> THEN <line number>
                                 [ ELSE <line number> ]
        c) IF <expression> THEN
                <statements>
            [ ELSE
                <statements> ]
            ENDIF

a) The first form of IF statement is the single line IF.

The numeric expression <expression> is evaluated. If the result is not zero
('true') the statements after the THEN keyword are executed otherwise the
ones after the ELSE keywords are executed.

There can be any number of statements after the THEN or ELSE separated by
colons. The only limit is the length of the line. Those statements can
include further IF statements and some confusion can arise as to which IF
statement an ELSE clause applies. If the interpreter has to look for an ELSE
as the result of the IF expression is zero, it stops at the first one it
finds after the current IF.

It is possible to omit the THEN clause or the ELSE clause. It is also
possible to leave out the THEN. If the item after the IF expression is
neither a THEN nor a ELSE keyword, the THEN keyword is assumed.

Examples:
        IF abc$="xyz" THEN PROCabc: PROCdef
        IF def<2.0 ELSE PRINT"def is too large"
        IF X% PROCpqr
        IF abc$="abc" THEN PRINT"abc": abc$="def" ELSE abc$="abc"

b) This is a variation on the single line IF. Either or both of the THEN and
   ELSE keywords can be followed by a line number instead of one or more
   statements. Program execution continues at that line iIf the interpreter
   finds a line number after a THEN or ELSE keyword.

Examples:
        IF abc%=1 THEN 100
        IF def<2.0 THEN PROCabc ELSE 200
        IF ghi$="abc" ELSE 300

c) The second form of the IF statement is the block IF.

If there is nothing else on the line after a THEN keyword or just a REM
statement then the IF statement is a block IF.

The ELSE part is optional but if it is included the ELSE keyword must be the
first item on the line after the line number and any leading blanks. The
statements for the ELSE part can start on the same line as the ELSE.

The ENDIF must be the first item on the line after the line number and any
preceding blanks.

Block IF statements can be nested to any depth.

Examples:
        IF X%=1 THEN
          PROCabc
        ENDIF

        IF X%=2 THEN
          PROCabc
        ELSE
          PROCdef
        ENDIF

        IF X%=2 THEN
          IF Y%=1 THEN STOP
        ELSE
          PROCabc
          PROCdef
        ENDIF

        IF X=2 THEN REM X is set to 2
          PROCabc
        ELSE
          PROCdef
        ENDIF

Note in this last example that there is a REM statement after the THEN but
the statement is still seen as a block IF.

INPUT
Syntax: a) INPUT <list of variables>
        b) INPUT# <factor>, <list of variables>
        c) INPUT LINE <list of variables>
        d) LINE INPUT <list of variables>

The INPUT statement is used to read data from the terminal of from a file.

a) This form of INPUT statement reads from the terminal. The format is more
   accurately specified as:

        INPUT [<prompt> [,]] <list of variables>
                [<prompt> [,]] <list of variables>] ...

<prompt> is a prompt displayed before the input is read. It can be made up
of any number of the following: a string, the function TAB() and "'". TAB()
is used to display the prompt at a specific position on the screen. "'"
causes a skip to the next line. Examples:

        INPUT TAB(10, 10) "Value: "
        INPUT "Size"
        INPUT TAB(0, 10) "Enter coordinates:" ' "X: "

TAB() takes two parameters, the column number and the row number to which to
move the text cursor, that is, the point at which the next character will be
written.

If the prompt is followed by a comma, a '?' is printed after the prompt.

If the prompt is left out, a '?' will be displayed as the prompt.

<list of variables> is the list of variables to receive the values read.
There can be any number of these. The variable names can be separated with
blanks, commas or semicolons.

Examples:

        INPUT X%,Y%
        INPUT abc(1), abc(2), abc(3)
        INPUT xyz$, ghi%

Values typed in are separated by commas. Leading blanks are ignored when
they are read. When reading a string, trailing blanks as far as the next
comma or the end of the are considered to be part of the string.

Strings can be enclosed in double quotes.

Numeric values can be entered in hexadecimal or binary as well as decimal.
Hexadecimal values are preceded with a '&' and binary ones with a '%'. (Note
that this is an extension in this interpreter.)

If insufficient values are supplied or an error found, the interpreter
prompts again for a value to be entered.

Multiple Prompts
----------------
It is possible to repeat as many prompt and variable list sequences as
desired. When 'return' is pressed the next prompt is displayed and the next
set of values read. Any values not used from the previous read are
discarded.

Example:

        INPUT "Name: " name$ "Address: " address$

b) The second form of INPUT statement is used to read data from a file.
   <factor> is the handle of the file from which input is to be taken and
   <list of variables> gives the variables to received those values.

Note that the data is assumed to be formatted binary data produced using
PRINT#. INPUT# cannot be used to read text from a file.

Example:

        INPUT# file% , abc(1), abc(2), xyz$

c) and d) These are a variation on format a). The difference is that each
   value read is taken from a new line.

Example:
        LINE INPUT "Coordinates: " X% Y%

LET
Syntax: LET <variable> = <expression>

<expression> is evaluated and the result assigned to the variable
<variable>.

Only the '=' assignment operator is allowed here.

Pseudo-variables, for example, PTR#, cannot be used after LET.

LIBRARY
Syntax: a) LIBRARY <expression 1>, <expression 2>, ... , <expression n>
        b) LIBRARY LOCAL <list of variables>

This statement has two purposes. In case a), it is used to read libraries of
BASIC procedures and functions into memory. <expression 1> to <expression n>
are strings that give the names of the libraries. There can be any number of
these. The libraries are held in memory until the BASIC program is run again
or edited or the statements NEW or CLEAR used.

When a procedure or function is called, the interpreter checks to see if it
is one already encountered. If not it searches the BASIC program for it. If
it cannot be found the interpreter then searches the loaded libraries and it
if still cannot locate it, the libraries loaded via the INSTALL command.
Libraries are searched in the reverse order to which they were loaded, for
example, given:

        LIBRARY "aaaaa"
        LIBRARY "bbbbb"
        LIBRARY "ccccc"

'ccccc' will be searched first, then 'bbbbb' and lastly
'aaaaa'.

Libraries can be seen as an extension of the program in memory rather than
separate entities. They can have their own private variables (declared using
LIBRARY LOCAL) but any other variables created in procedures and functions
in the library will be added to those the program creates.

LIBRARY LOCAL is used to define variables and arrays that will be private to
a library. Only the library will be able to reference these variables and
arrays.

The syntax of the statement is as follows:

        LIBRARY LOCAL <list of variables and arrays>

where <list of variable and arrays> is a list of variable and array names
separated by commas, for example:

        LIBRARY LOCAL abc%, def%, ghi$, jkl(), mno(), pqr$()

In the case of arrays, this merely defines that the array is local to the
library. The dimensions of the array have to be declared using a DIM
statement in the normal way, for example:

        LIBRARY LOCAL jkl(), pqr$()
        DIM jkl(100), pqr$(table_size%)

There can be as many LIBRARY LOCAL and DIM statements as necessary but they
have to be before the first DEF PROC or DEF FN statement in the library.
They also have to be the first item on the line.

The variables can only be referenced in the library. They are not visible
outside it. This is different to the way in which local variables are dealt
with in a procedure or function, where local varables can be accessed by any
procedure of function called by the procedure in which they were declared.
They can duplicate the names of variables in the BASIC program or other
libraries.

When looking for a variable in a library, the interpreter first searches for
it amongst the library's private variables and then in the BASIC program's.

The variables and arrays are created the first time the library is
referenced. In practice this means that they are set up when the interpreter
has to search the library for a procedure or function.

Private variables in a library can further be used as local variables in a
procedure or function. Note that they can only be accessed in the library,
for example:

        LIBRARY LOCAL abc%, def, ghi$, jkl(), mno$()
        DIM jkl(100)

        DEF PROCaaa(abc%)
        LOCAL def, ghi$
        ENDPROC

        DEF PROCbbb(def, jkl())
        LOCAL mno$()
        DIM mno$(100)
        ENDPROC

        DEF PROCccc(xyz, abc%)
        ENDPROC

Here, abc%, def, ghi$, jkl() and mno$() are all declared to be private to
the library. The dimensions of jkl() are also defined.

In PROCaaa, abc% is used as a formal parameter (effectively a local
variable) and def and ghi$ declared to be local to the procedure. Any
procedure or function *in the library* that PROCaaa calls that use def and
ghi$ will use PROCaaa's local versions. Any procedure or function that
PROCaaa calls that are *outside* the library *will not* see these variables.

In PROCbbb, def and jkl() are used as formal parameters and mno$() is
defined as a local array and its dimensions given. Note that this is the
first place where the dimensions have been defined.

In PROCccc, two variables are used as formal parameters, xyz and abc%. This
case is more complex in that abc% is one of the library's private variables
whereas xyz is not. xyz is one of the BASIC program's variables. abc% can
only be referenced in the library but xyz is visible anywhere.

The rules for the scope of private library variables may sound complex but
they are quite simple. The point to remember is that a private variable in
*only* accessible in the library in which it was declared. If a variable is
not declared on a LIBRARY LOCAL statement then it is visible anywhere.


LINE
Syntax: a) LINE <x expression 1> , <y expression 1> ,
                        <x expression 2> , <y expression 2>
        b) LINE INPUT <list of variables>

a) This form of the statement draws a line on the screen in the current
   graphics foreground colour from coordinates 
   (<x expression 1> , <y expression 1>) to
   (<x expression 2> , <y expression 2>).

Example:
        LINE 100, 100, 400, 500

b) This is a version of the INPUT statement. It is described in the
   section on INPUT above.

LOCAL
Syntax: a) LOCAL <list of variables>
        b) LOCAL DATA
        c) LOCAL ERROR

a) This version of the LOCAL statement is used in a procedure or function to
   declare local variables. The keyword LOCAL is followed by any number of
   variable names separated by commas, for example:

        LOCAL abc%, def, ghi$, jkl

Arrays can also be declared to be local, but the definition of a local array
is slightly more complicated in that the new array dimensions have to be
given on a DIM statement, for example:

        LOCAL xyz()
        DIM xyz(100,10)

LOCAL statements can only appear in procedure or function.

The term 'local variables' is somewhat misleading in this context in that
the variables are accessible not just in the procedure or function in which
they are declared but anywhere in the program. What actually happens is that
if the variable already exists, its old value is saved and then it is reset
to zero (or the empty string in the case of string variables). When the
procedure or function in which the variable was declared local is exited
from, the old value is restored. Variables that do not exist are created by
the LOCAL statement but they are not destroyed when the procedure or
function is left.

Anything that can appear on the left-hand side of an assignment can in fact
be declared as a local variable, so that, for example, individual elements
can be declared local if need be! Example:

        LOCAL abc(25), abc(30)

This would declare two elements of array abc(), elements 25 and 30, to be
local. The array abc() has to exist already for this to work. Another
example:

        LOCAL block%!4, block%?20, $text%

This would preserve the integer value at address block%!4, the byte at
block%?20 and the string at $text%.

Variables declared LOCAL can be restored to their global state by
'RESTORE LOCAL'.

b) 'LOCAL DATA' saves the current value of the DATA statement pointer. It
   can be reset to its original value by 'RESTORE DATA'.
Example:

        LOCAL DATA
        RESTORE 100
        READ abc%
        RESTORE DATA

Uses of LOCAL DATA can be nested without any problems.

Note that there are times when the DATA pointer will be set back to its old
value automatically:

1) If LOCAL DATA is used in a procedure or function the old value will be
   restored when the function or procedure is exited from.

2) If it is used inside a WHILE, REPEAT or FOR loop, the value will again be
   restored when the loop ends.

It is possible to leave out the RESTORE DATA but it is probably best to
include it.

c) The 'LOCAL ERROR' statement is used to save the details of the current
   'ON ERROR' error handler so that it can be changed and restored later.
   'RESTORE ERROR' is used to reset it. Example:

        LOCAL ERROR
        ON ERROR LOCAL PROClocal_error: ENDPROC
        X=X/0
        RESTORE ERROR

There is no limit on the number of times LOCAL ERROR can be used (other than
the memory available). It is possible to nest LOCAL ERROR statements, that
is, LOCAL ERROR can be used in a procedure, say, and then it can be used
again in the procedures that that procedure calls without any problems.

As with LOCAL DATA, there are times when the old error handler details will
be restored automatically. They are:
   
1) If LOCAL ERROR is used in a procedure or function the old handler will be
   restored when the function or procedure is exited from.

2) If it is used inside a WHILE, REPEAT or FOR loop, the handler will again
   be restored when the loop ends.

So RESTORE ERROR can be omitted but it is probably best to include it.

Note: LOCAL with no parameters is allowed by all Acorn BASICs, however this
does nothing and is indicative of a mistake in the program. Matrix Brandy
replicates this behaviour in case this occurs in existing programs, but
setting the strict option (starting with -strict, compiling without
-DDEFAULT_IGNORE, running SYS"Brandy_Strict",1) makes this report
"Syntax error" in line with Richard Russell's BASICs.

MODE
Syntax: a) MODE <expression>
        b) MODE <x expression>, <y expression>, <depth>, <rate>

a) The MODE statement is used to change the screen mode. <expression> is the
   new screen mode. It can be either a number or a string.

If the mode is numeric, it has to be in the range 0 to 127. This gives the
RISC OS screen mode number. The range of modes defined corresponds to those
available under RISC OS 3.1 (modes 0 to 46) but whether or not all of these
are available depends on the machine on which the program is being run. Mode
numbers greater than 46 are undefined and mode 0 is used instead. There is
one special mode, mode 127. This corresponds to the screen or window size of
the environment in which the interpreter is being run, for example, if the
program is being run in an xterm under NetBSD with a window size of 96
characters by 50 lines, mode 0 (80 by 32) will use only part of this but
mode 127 will switch to the entire window.

The details of the screen mode can also be given as a string. This can be
the RISC OS screen mode number as a string or a more precise specification
of the resolution and the number of colours to be used.

A mode string has the format:

        X<x resolution> Y<y resolution> [ C<colours> ] [ G<levels> ]

where <x resolution> and <y resolution> give the screen size in pixels,
<colours> gives the number of colours for a colour screen mode and <levels>
the number of levels for grey-scale.
Example:

        MODE "X800 Y600 C256"

The number of colours or grey scale levels is optional. The parts of the
mode string can be separated by any number of commas or blanks.

As with numeric screen modes, whether or not the screen mode is available
depends on the machine on which the interpreter is being used.

b) In this version of the statement, <x expression> and <y expression> give
the desired size of the screen in graphics units. <depth> is a value that
gives the number of colours and <rate> the frame rate. The last parameter,
<rate> can be left out, in which case the highest frame rate available will
be used.

The program will attempt to match the details of the requested mode with
those available and will only switch to that mode if it finds a match.

The possible values for <depth> are as follows:

        1       2 colours
        2       4 colours
        4       16 colours
        6       256 colours, old-style RISC OS mode
        8       256 colours, new-style RISC OS mode
        16      32K colours
        32      16M colours

The values possible depend on the version of the program being used. In
general, depths of 16 and 32 are only available in the version of the
program that runs under RISC OS.

Under RISC OS, a depth of 6 specifies an old-style Archimedes type 256
colour screen mode in which the extent to which colours can be changed is
limited. A depth of 8 indicates that a newer type (RISC OS 3.5 and later)
screen mode is to be used where all of the colours can be changed. 

Examples:
        MODE 1024, 768, 8
        MODE 640, 512, 2, 75


MOUSE
Syntax: a) MOUSE ON
        b) MOUSE OFF
        c) MOUSE <x variable>, <y variable>, <button variable>
                                [, <timestamp variable> ]
        d) MOUSE STEP <expression> [, <expression> ]
        e) MOUSE COLOUR <expression>, <red expression>,
                        <green expression>, <blue expression>
        f) MOUSE RECTANGLE <left expression> , <bottom expression>,
                        <right expression> , <top expression>
        g) MOUSE TO <x expression> , <y expression>

The MOUSE statement is used to control various aspects of the mouse.

a) MOUSE ON turns on the mouse pointer if it is not being displayed.

b) MOUSE OFF turns off the mouse pointer.

c) This version of the statement reads the current position of the mouse and
   the button state. The values are stored in <x variable>, <y variable> and
   <button variable>. There is one optional parameter, <timestamp variable>,
   which is set to the time at which the mouse position was recorded derived
   from the centisecond timer.
   
Example:
        MOUSE xpos%, ypos%, buttons%

d) MOUSE STEP is used to the mouse multiplier, that is the number of
   graphics units on the screen that each step of the mouse makes. One or
   two values can be given. <expression> is a number greater than or equal
   to zero. If one value is supplied then both the X and Y steps are set to
   this value. If there are two values, the X multiplier is set to the first
   value and the Y multiplier to the second. It is possible to set the
   multiplier in either direction to zero, in which case the mouse will not
   move in that direction. Except for RISC OS, this command is ignored.
   Examples:

        MOUSE STEP 4,3
        MOUSE STEP 2,0

e) MOUSE COLOUR sets the colour of the mouse pointer on screen. <expression>
   is in the range one to three and says which of the three mouse colours to
   change. <red expression>, <green expression> and <blue expression> are
   the colour components of the new colour. Except for RISC OS, this command
   is ignored. 

Example:
        MOUSE COLOUR 1, 255, 0, 0

f) MOUSE RECTANGLE defines a box on the screen outside of which the mouse
   pointer cannot be moved. It requires four parameters, <left expression>,
   <bottom expression>, <right expression> and <top expression> which give
   the coordinates of the bottom left-hand and top right-hand corners of the
   box in graphics units. Except for RISC OS, this command is ignored.

Example:
        MOUSE RECTANGLE 100, 100, 900, 600

g) The MOUSE TO statement moves the mouse pointer to the coordinates
   (<x expression>, <y expression>) on the screen. The position is expressed
   in graphics units.

Example:
        MOUSE TO 600, 800

MOVE and MOVE BY
Syntax: a) MOVE <x expression> , <y expression>
        b) MOVE BY <x expression> , <y expression>

The MOVE statements move the graphics cursor to the position specified
without drawing a line.

a) MOVE moves the cursor to position <x expression>, <y expression>.

b) MOVE BY moves the cursor by an amount <x expression> and <y expression>
   in the X and Y directions relative to the old graphics cursor position.

Examples:
        MOVE 500, 500
        MOVE BY 100, 60

NEXT
Syntax: NEXT [ <variable name> ]

The NEXT statement is part of the FOR loop. It marks the end of the loop.
<variable name> is optional, and is the name of the FOR loop index variable.
Refer to the section above on the FOR statement for more details.

Example:
        NEXT N%

It is possible to end a number of loops on a single NEXT statement. The
syntax for this type of NEXT is:

        NEXT [ <variable name 1> ] , [ <variable name 2> ] , ...
                        [ <variable name n> ]

In other words, NEXT is followed by a list of variable names separated by
commas. However, the variable names can be omitted, in which case NEXT is
followed by a series of commas, one less in total than the number of FOR
loops being ended at that point.

Examples:
        FOR X% = 1 TO 10
          FOR Y% = 1 TO 10
        NEXT Y%,X%

        FOR abc = 1 TO 100
          FOR def = 1 TO 100
        NEXT ,

OF
'OF' is part of a CASE statement. Refer to the section on CASE statements
above for more details.

Example:
        CASE abc% OF
        WHEN 1: PRINT"1"
        ENDCASE

OFF
Syntax: OFF

This statement turns off the text cursor so that it is not displayed.

Example:
        IF hide% THEN OFF

ON
Syntax: a) ON
        b) ON <expression> GOTO <line number 1> , ... ,
                        <line number n> [ ELSE <statement> ]
        c) ON <expression> GOSUB <line number 1> , ... ,
                        <line number n> [ ELSE <statement> ]
        d) ON <expression> PROC<name 1>, ... ,
                        PROC<name n> [ ELSE <statement> ]
        e) ON ERROR <statements>
        f) ON ERROR OFF
        g) ON ERROR LOCAL <statements>

The ON keyword is used in a variety of statements as follows:

a) ON on its own turns on the text cursor if it is turned off so that it is
   being displayed on the screen.

b) In this form of ON statement, the expression <expression> is used to
   control which line to branch to next. <expression> is a number greater
   than or equal to one. If it is one, the first line listed after the GOTO
   keyword is the one to branch to, if it is two, the second one list is the
   destination and so forth. Two things can happen if <expression> is less
   than one or greater than the number of line numbers given. If the ELSE
   part is supplied, the interpreter jumps to the statement after this. Note
   that only a single statement is allowed here. If there is no ELSE part,
   an error is raised.

The line numbers after the GOTO can be given as expressions if desired, but
the RENUMBER command will probably fail if this is done because it cannot
deal with line numbers given in this way.

Examples:
        ON abc% GOTO 100, 500, 900
        ON def GOTO 1000, 2000, 3000, 4000 ELSE STOP
        ON ghi% GOTO FNline1, FNline2, 1000, abc%*10+1

c) ON ... GOSUB is similar to ON ... GOTO. The expression is used to control
   which subroutine to call. When the subroutine call ends, the program
   continues to run at the statement after the ON ... GOSUB. <expression> is
   used as an index to choose which line number after the GOSUB to call. If
   the value of <expression> is n, the n'th line number is the one selected.
   There are two possibilities if <expression> is less than one or the
   greater than the number of line numbers supplied. If there is an ELSE
   part, the interpreter branches to that. If there is no ELSE, an error is
   flagged.

The line numbers can be given as expressions if required.

Example:

        ON abc% GOSUB 1000, 2000, 3000
        ON def GOSUB 1000, 2000 ELSE PROCerror: PRINT"Done"

In second example, if def is set to one, the subroutine at line 1000 will be
called. When it returns, execution resumes at the statement 'PRINT"Done"' as
this is the statement after the ON ... GOSUB. Similarly, when PROCerror
returns, execution also continues with the PRINT statement.

d) ON ... PROC is again similar to ON ... GOTO. The result of numeric
   expression <expression> is used as an index to locate the procedure to
   call. If the value of <expression> is n, the n'th procedure listed is the
   one called. When the procedure call has ended, execution continue at the
   statement after the ON ... PROC. There are two possibilities if
   <expression> is out of range, that is, is less than one or greater than
   the number of  PROC statements after the expression. If there is an ELSE
   part, the interpreter continues at that statement, otherwise an error is
   reported.

Example:
        ON abc% PROCaaa, PROCbbb(X%), PROCccc("abc")
        ON def PROCaaa, PROCaaa, PROCbbb(1) ELSE STOP

e) ON ERROR is used to deal with errors that the interpreter detects in the
   BASIC program. When an error occurs the interpreter continues with the
   statements after the 'ON ERROR'. However, before it does so it
   automatically returns from all procedures, functions and subroutines as
   well as ending any loops. It is therefore not possible to recover from an
   error and resume execution of the program at the point at which it was
   detected.

Example:
        ON ERROR PROCcomplain: END

The section 'Error Handling' above discusses trapping errors in programs in
more detail.

f) ON ERROR OFF turns off the trapping of errors by the BASIC program.

g) The ON ERROR LOCAL statement is used to trap errors in the BASIC program.
   When one of these statements is executed by the interpreter it notes the
   address of the statements after the keywords ON ERROR LOCAL. When an
   error is detected it continues at those statements.

ON ERROR LOCAL statement gives more control than ON ERROR in that everything
is left as it was at the time of the error. This means that it is possible
to trap errors and recover from them, resuming at the point of the error.

Example:
        ON ERROR LOCAL PRINT"Error - ";REPORT$
        INPUT X,Y
        PRINT X/Y

Here, if an error occured when inputting the values X and Y or when X is
divided by Y, the interpreter would branch to the PRINT statement after the
ON ERROR LOCAL, display the error message and ask for input again.

The section 'Error Handling' above discusses trapping errors in programs in
more detail.

ORIGIN 
Syntax: ORIGIN <x expression> , <y expression>

This statement changes the coordinates of the graphics origin.
<x expression> and <y expression> specify the new coordinates.

Example:
        ORIGIN xplace, yplace

OSCLI
Syntax: OSCLI <string expression> [ TO <string array>
                                        [ , <variable> ] ]

The OSCLI statement is used to issue a command to the operating system on
which the interpreter. <string expression> is the command. <string array> is
an array that will be used to hold the output from the command. It is
optional. If it is not present then the command output goes to the normal
place. <variable> is set to the number of lines stored in <string array>.
Again, it is optional.

The existing contents of <string array> are discarded before the output from
the command is stored in it. Elements of the array that are not used are set
to the empty string. The first element of the array used is 1, so the output
is found in elements 1 to <variable>. If there is more output than will fit
in the array the excess is discarded. There is nothing to indicate that this
has happened so it is up to the user to ensure that the array is large
enough.

Examples:
        F% = OPENIN filename$: size% = EXT#F%: CLOSE#F%
        DIM block% size%
        OSCLI "load "+filename$+" "+STR$~block%

        OSCLI <command> [ TO <string array> [ , <variable> ] ]

        OSCLI "ex" TO array$(), lines%
        FOR N%=1 TO lines%
          IF LEFT$(array$(N%), 1)="a" THEN PRINT array$(N%)
        NEXT


OTHERWISE
Syntax: OTHERWISE [: <statements>]

Part of a 'CASE' statement. When none of the cases given on WHEN statements
match the expression on the CASE statement, the program continues at the
statements after OTHERWISE. Refer to the section on the 'CASE' statement
above for more details.

OVERLAY
Syntax: OVERLAY

This statement is not supported by the interpreter.

PLOT
Syntax: PLOT [<code> ,] <x expression> , <y expression>

This statement carries out the graphics operation with code <code>. <x
expression> and <y expression> are the two parameters that PLOT codes use.

For compatibility with BBCSDL, the <code> is optional, and if not supplied,
code 69 is assumed, making it equivalent to POINT x, y.

PLOT codes are at the heart of the graphics support. They carry out graphics
operations such as drawing lines and shapes. Many of the more common
operations have their own statements, for example, MOVE and DRAW. PLOT
allows any of the codes to used in a program. The section 'Plot Codes' below
gives more details.

Examples:
        PLOT 4, 100, 100
        PLOT 5, 500, 100
        PLOT 5, 500, 500
        PLOT 5, 100, 100

This plots a triangle. It could also be written as:

        MOVE 100, 100
        DRAW 500, 100
        DRAW 500, 500
        DRAW 100, 100

On the other hand, a filled triangle would have to be drawn using:

        MOVE 100, 100
        MOVE 500, 100
        PLOT 85, 500, 500

as there is no BASIC statement to draw one.

POINT and POINT BY
Syntax: a) POINT <x expression> , <y expression>
        b) POINT BY <x expression> , <y expression>

The POINT statement is used to plot a single point on the screen.

a) This form of the statement plots the point at coordinates
   (<x expression>, <y expression>) on the screen.

b) This versions of the statement plots the point at the position <x
   expression> and <y expression> graphics units in the X and Y direction
   relative to the current graphics cursor.

Examples:
        POINT 500, 100
        PONT BY xoffset%, yoffset%

POINT TO
Syntax: POINT TO <x expression> , <y expression>

This statement is similar to the MOUSE TO statement. Normally the pointer on
screen is tied to the mouse but it does not have to be. POINT TO is used to
move the pointer when it is not following the mouse. <x expression> and <y
expression> give the x and y coordinates in graphics units to which the
pointer is to be moved.

Example:
        POINT TO 500, 500

PRINT
Syntax: a) PRINT <list of expressions>
        b) PRINT# <factor>, <list of expressions>

The first version of the PRINT statement displays data on screen and the
second writes it to a file.

a) This version of the statement is used to display information on the
   screen. <list of expressions> is a list of items to be displayed. These
   are separated by blanks, ',' ';' or "'". In addition there are two
   functions specifically for controlling output.

Each item in <list of expression> can be an expression whose value is to be
displayed or a print function. The print functions are:

        TAB( <expression> )
        This moves the text cursor to character position <expression> on the
        current line. If the text cursor is already beyond that column, move
        to the next line and skip to the required column.

        TAB( <x expression>, <y expression> )
        Move the text cursor to column <x expression>, row <y expression> on
        the screen.

        SPC <expression>
        Print <expression> blanks.

The rules describing how values are displayed are quite involved:

1) The print format of numbers is controlled by a special variable called
   '@%'. See the section below for details on the values that this can take.

2) Whilst @% affects the format used for a number, ';' and ',' affect the
   way in which it will be laid out.

   ',' causes two things: numbers will be printed right-justified occupying
   the number of characters set by field width in @%. Secondly, it causes
   the text cursor to be moved to the next column whose number is a multiple
   of the field width.

   ';' causes numbers to be printed left-justified. They occupy only as many
   characters as needed to express the number.

   By default, numbers are printed right-justified.

   If the first expression after the PRINT keyword is numeric and the result
   has to be printed left-justified, the expression has to be preceded with
   a ';' thus: 'PRINT ; abc%'.

3) If a numeric expression is preceded by a '~' then the value is printed in
   hexadecimal. In fact the '~' acts as a switch and and the results of all
   numeric expressions from this point to the next ';' or ',' will be
   printed in hexadecimal.
   
4) If an expression is separated from the previous one by a space then the
   second expression is formatted in same way as the previous one.

5) If an expression is separated from the previous one by a "'" the second
   expression is displayed on the next line. It will be formatted in the
   same way as the previous expression.

6) The functions TAB() and SPC do not affect how numbers will be formatted.

7) Strings are always printed left-justified and do not use the field width
   set by @%.

Examples:
        PRINT abc def
        PRINT ~pqr% xyz%
        PRINT ghi$, "abcde", ~abc%
        PRINT abc$ TAB(20) def
        PRINT TAB(1,1) "a" TAB(2,2) "b" TAB(3,3) "c"
        PRINT ; xyz%
        PRINT CHR$13 ; SPC20 ; X%
        PRINT "Line 1" ' "Line 2" ' "Line 3"

The Format Variable @%
----------------------
This controls how numbers are formatted when they are printed. It can also
affect the function STR$.

@% can best be thought of as being made up of four distinct byte-sized
fields. They are laid out as follows:

        @%=&SSNNPPWW

Byte    Range   Default Purpose
SS      00-01   00      STR$ Format Control
NN      00-B2   00      Format Selection
PP      00-11   09      Number of Digits Printed
WW      00-0F   0A(10)  Zone and Print Field Width

with <flags> in the most significant byte of @% and <width> in the least
signicant byte.

If SS is non-zero, STR$ uses the format specified, else it uses the ARM BBC
BASIC default value of &110A.  Strictly it is only the lowest bit of this
byte that matters, but in practice if the entire top byte is non-zero then
STR$ uses the format specified.

NN controls how numbers are output. The values it can take are:

        0  General format
        1  Exponent format
        2  Fixed precision format
        If bit &80 is set, then use a decimal comma instead of a decimal
        point.
        Matrix Brandy has its own extension to this:
        Bits &10 and &20 are used to control the right-justify padding in
        Exponent format, the default (both 0) follows the traditional
        formatting in BBC BASIC 1 to 5, &10 set gives an additional space
        (matching Acorn ARM BBC BASIC VI), &20 gives two extra spaces, and
        both together set gives 3 extra (perhaps useful if 128-bit floats
        become a thing in the future).

PP gives the number of digits to print. The range is 1 to 255.  If 0 (and
not format 2) then the maximum number of digits is used (PI returns 17
significant figures).  Acorn's documentation don't explicitly mention using
0 here except for fixed precision format, and Richard Russell's
documentation states it is not valid.  However, the 6502 disassembly of all
the Acorn 8-bit BASICs and the RISC OS source code all explicitly handle
this eventuality and use the maximum available digits, it isn't a side-
effect that happens to work. However, use of 0 is not recommended as the
output is system and version dependent:
BBC BASIC I (1981) - BBC Micro - 9 significant figures maximum
BBC BASIC II (1982), BASIC IV (1984), BASIC V (1987-2017) - 10 sf.
ARM BBC BASIC V (from 2017) - 11 significant figures.
ARM BBC BASIC VI - 17 significat figures.
Richard Russell's BASICs all use 9 significant figures if 0 is used, even
though his versions support 64-bit, and sometimes 80-bit floats (depending
on platform). Note that declaring @% LOCAL in a function or procedure will
reset it to 0 until a new value is assigned.

WW is the field width, the number of characters that can be used when
displaying a number. The range is zero to 255 characters. This affects how a
number will be displayed as well as the number of characters skipped when
using a ',' in a PRINT statement.

The default value of @% is &90A, that is, use general output format, display
up to nine digits after the decimal point and use a field width of ten
characters.


To make it easier to use, @% can be set using by assigning the desired
format to it as a string.

        @% = "<format string>"

<format string> is composed as follows:

        [+] [<format>] [<width>] [ . <places>]

Starting the string with a '+' indicates that the format is used to be used
by the function STR$ .

<format> gives the format to use:
        G       General format
        E       Exponent format
        F       Floating point format

<width> is the field width.

<places> gives the number of digits to print. If the format is F, it is the
number of digits after the decimal point.

If ',' is used instead of '.' before the number of places, ',' is used as
the decimal point character instead of '.'.

Note that all of these parts are optional. Only the parts of the format
supplied in the string will be changed.

Examples:

        @% = "G15.12"
        @% = "E"
        @% = "10"
        @% = ","
        @% = "+.10"

b) PRINT# writes data to the file with file handle <factor>. <list of
   expressions> is the data to be written. Note that the output is in
   binary, not text. It is designed to be read by the INPUT# statement.

Examples:
        PRINT#file%, xyz, abc%(X%), "abcdefghij"

QUIT
Syntax: QUIT [ <expression> ]

The QUIT statement is used to exit from the interpreter. It can optionally
be followed by a numeric expression. This value is passed back to the
operating system under which the program is running as a return or status
code. If omitted it defaults to zero.

READ
Syntax: READ <list of variables>

The READ statement is used to read values supplied via DATA statements
elsewhere in the program. <list of variables> is the list of variables to
which the values will be assigned.

When reading the value of a numeric variable, the value in the data
statement is treated as a BASIC expression. The text on the DATA statement
is read as far as the next comma or the end of the line and then evaluated.
The result of the expression is the value assigned to the variable.

If the variable being read is a string variable, the text on the DATA
statement is read as far as the next comma or the end of the line. Blanks
preceding any text are ignored but trailing blanks are considered to be part
of the string. The string can be enclosed in double quotes if need be.

Examples:

        abc% = 100
        READ xyz%, pqr%
        DATA abc%+10, 99
                
Here the expression 'abc%+10' is evaluated when xyz% is read and xyz% will
be set to 110.

        READ abc$, def$
        DATA     aaa   , "   bbb   "

abc$ will be set to the string 'aaa   ' and def$ to '   bbb   '.

The RESTORE statement can be used to change the DATA statement from which
data will be read. LOCAL DATA and RESTORE DATA can be used to save the
current DATA statement pointer and to retrieve its value later.

RECTANGLE
Syntax: a) RECTANGLE  <left expression> , <bottom expression>,
                        <width expression> [, <height expression> ]
        b) RECTANGLE FILL <left expression> , <bottom expression>,
                        <width expression> [, <height expression> ]
        c) RECTANGLE <left expression> , <bottom expression>,
                        <width expression> [, <height expression> ]
                        TO <x expression> , <y expression>
        d) RECTANGLE FILL <left expression> , <bottom expression>,
                        <width expression> [, <height expression> ]
                        TO <x expression> , <y expression>

The RECTANGLE statement has two uses, to draw a rectangle and to move or
copy a rectangular portion of the screen to another part of the screen.

a) This form draws a box on the screen. The botton left-hand corner of the
   box is at the coordinate (<left expression> , <bottom expression>) and
   the width and height are given by <width expression> and <height
   expression>. <height expression> can be omitted, in which case the height
   is taken to be the same as the width.

b) This version draws a filled rectangle. The botton left-hand corner of the
   rectangle is at the coordinate (<left expression> , <bottom expression>)
   and the width and height are given by <width expression> and <height
   expression>. <height expression> can be omitted, in which case the height
   is taken to be the same as the width.

c) This statement copies an area of the screen. The  botton left-hand corner
   of the area is given by the coordinate (<left expression> , <bottom
   expression>) and the width and height are given by <width expression> and
   <height expression>. <height expression> can be omitted, in which case
   the height is taken to be the same as the width. <x expression> and <y
   expression> are the coordinates of the bottom left-hand corner of the
   copied area.

d) This form moves an area of the screen. The  botton left-hand corner of
   the area is given by the coordinate (<left expression> , <bottom
   expression>) and the width and height are given by <width expression> and
   <height expression>. <height expression> can be omitted, in which case
   the height is taken to be the same as the width. <x expression> and <y
   expression> are the coordinates of the bottom left-hand corner of the
   location to which the area will be moved. The old area is set to the
   background graphics colour.

Examples:
        RECTANGLE 400, 400, 500, 200
        RECTANGLE FILL 200, 200, width%, height%
        RECTANGLE FILL 200, 200, size%
        RECTANGLE left%, bottom%, with% TO 1000, 1000
        RECTANGLE FILL left%, bottom%, with% TO 1000, 1000

REM
Syntax: REM <comments>

The REM statement is used to include comments in a program. When a REM
statement is encountered, the interpreter skips to the next line in the
program.

Example:
        REM Here be dragons

REPEAT
Syntax: REPEAT

REPEAT marks the start of a REPEAT loop. The format of one of these is:

        REPEAT
          <statements>
        UNTIL <expression>

The block of statements <statements> is executed. The numeric expression
<expression> is evaluated when the UNTIL is reached. If the result is zero
(the value BASIC used to represent false) the program jumps back to the
start of <statements> and continues from that point again. If the result is
not zero, execution continues with the statement after the UNTIL. In other
words, <statements> will be executed repeatedly until the value of
<expression> is not zero.

REPEAT loops can be nested to any depth.

It is possible to start the loop on the same line REPEAT, missing out the
':' statement separator.

The interpreter is not fussy about where the UNTIL is located, for example,
the following sort of code is allowed:

        IF flag THEN UNTIL X%>10 ELSE UNTIL Y%>10

The interpreter silently ignores incorrectly nested loops of different types
so that, for example, the following will not give an error:

        REPEAT
          FOR X% = 1 TO 10
        UNTIL Y% = 0

Note that the effect of any LOCAL DATA or LOCAL ERROR statements in the body
of the loop will be reversed when the loop ends, that is, the data pointer
and error handler details will be restored to the values they had when the
LOCAL DATA or LOCAL ERROR was encountered.

REPORT
Syntax: REPORT

The REPORT statement displays the error message for the last error
encountered in a program.

Example:
        DEF PROCerror
        PRINT"Program failed with error ";
        REPORT
        PRINT" at line ";ERL
        END

REPORT is used to print the error message. There is a function REPORT$ that
returns it as a string then would be more convenient in code such as the
example above. Other useful functions in this context are ERR and ERL which
return the number of the last error and the line in which it occured.

RESTORE
Syntax: a) RESTORE [ <line number> ]
        b) RESTORE + <expression>
        c) RESTORE DATA
        d) RESTORE LOCAL
        e) RESTORE ERROR

The RESTORE statement has two uses: firstly, it is used to control which
DATA statement is to be used to provide data for a READ statement and
secondly it returns various internal pointers to values previous saved.

a) This version of the statement sets the data pointer to point at the DATA
   statement at or after line <line number>. The line number can be an
   expression. It can also be omitted, when the data pointer is reset to the
   first DATA statement in the program.

Example:
        RESTORE
        RESTORE 100
        IF flag THEN RESTORE start% ELSE RESTORE finish%


b) This form of the statement sets the data pointer to a line relative to
   the one in which the statement is found. <expression> gives the number of
   lines to skip. It has to be a positive value greater than or equal to
   zero. The data pointer is moved to the DATA statement at or after the
   line indicated by the RESTORE statement.

        RESTORE +0
        RESTORE +10
        RESTORE +offset%

c) RESTORE DATA restores the data pointer to the value it had the last time
   a LOCAL DATA was executed. RESTORE DATA has to match up with a LOCAL DATA
   statement.

Note that RESTORE DATA is not always necessary as the data pointer will be
automatically restored under some conditions, for example, if LOCAL DATA is
used in a procedure, there will be an implicit RESTORE DATA when the
procedure call ends. The data pointer is also restored automatically if
LOCAL DATA is used inside a FOR, WHILE or REPEAT loop when the program
leaves the loop.

Example:
        LOCAL DATA
        RESTORE 100
        READ X%
        RESTORE DATA


d) RESTORE LOCAL restores the variable states which were previously declared
   LOCAL within a function or procedure.

Example:
        LOCAL a
        a=42
        PRINT a
        RESTORE LOCAL
        PRINT a

e) RESTORE ERROR restores the BASIC error handler set up by ON ERROR or ON
   ERROR LOCAL to its condition when the last  LOCAL ERROR statement was
   executed. RESTORE error has to match up with a LOCAL ERROR statement.

Note that RESTORE ERROR is not always necessary as the details of the error
handler will be automatically restored under some conditions, for example,
if LOCAL ERROR is used in a procedure, there will be an implicit RESTORE
ERROR when the procedure call ends. The error handler details are also
restored automatically if LOCAL ERROR is used inside a FOR, WHILE or REPEAT
loop when the program leaves the loop.

Example:
        LOCAL ERROR
        ON ERROR LOCAL REPORT
        INPUT X%
        RESTORE ERROR

RETURN
Syntax: RETURN

The RETURN statement is used to return from a subroutine invoked via GOSUB
to the statement after the GOSUB.

Example:
        IF X%=0 RETURN

RUN
Syntax: a) RUN [ <line number> ]
        b) RUN <string expression>

a) The first form of the RUN statement starts a program running. The line
   number <line number> is optional. If supplied, execution starts at that
   line in the program. If omitted, execution starts at the beginning of the
   program.

b) The second version of the RUN statement is identical to the CHAIN
   statement. The expression <string expression> provides the name of the
   program to run. If the program can be found it is loaded into memory and
   run. Any variables that existed at the time the RUN command (with the
   exception of the static integer variables, A% to Z%) are destroyed.

SOUND
Syntax: a) SOUND OFF
        b) SOUND ON
        c) SOUND <channel>,<amplitude>,<pitch>,<duration>(,<delay>)

This statement is used to make a sound.

a) SOUND OFF turns off the sound system.

b) SOUND ON turns on the sound system.

c) This version of the statement is used to make a sound. The sound
   functionality depends on what the underlying sound system implements.

STEP
Syntax: STEP <expression>

The STEP statement is part of a FOR statement. The expression <expression>
gives the amount by which the FOR loop index variable is incremented (or
decremented if negative) on each iteration of the FOR loop. Refer to the
section on the FOR statement for more details.

Example:
        FOR N% = 10 TO 1 STEP -1: NEXT
        FOR X% = 1 TO 5 STEP 2: NEXT

STEREO
Statement for controlling the RISC OS sound system.

STOP
Syntax: STOP

The STOP statement ends the run of a program. It differs from END in that
STOP is trapped as an error, one that can't be caught with ON ERROR.

Example:
        IF bad THEN STOP

SWAP
Syntax: SWAP <variable 1> , <variable 2>

The SWAP statement exchanges the values of the two variables <variable 1>
and <variable 2>. The variables have to be of the same type, that is,
numeric variables can switch values and string variables can but types
cannot be mixed.

Arrays can also be swapped but they have to be of exactly the same type,
although the array dimensions can be different.

Examples:
        SWAP X%, Y%
        SWAP abc(X%), abc(X%+1)
        SWAP array1(), array2()
        DIM aaa(25), bbb(10,10,10): SWAP aaa(), bbb()

The last example demonstrates that arrays of different sizes and even with
differing numbers of dimensions can be swapped.

SYS
Syntax: SYS <swi expression>, <expression 1>, ... ,
                <expression n> [ TO <variable 1> , ... ,
                <variable n> [ ; <flag variable>] ]

The SYS statement is only fully supported by the RISC OS version of the
interpreter. It is used to issue a SWI (RISC OS operating system call) from
a BASIC program.  On other platforms, support is minimal.

<swi expression> identified the SWI to call. This can be a number or a
string giving the name of the SWI. <expression 1> to <expression n> are the
parameters for the call. They can be numbers or strings. BASIC strings are
converted to null-terminated strings for the call. It is not possible to
check that the types of the parameters supplied are correct for the SWI call
so it is up to the programmer to ensure they are right.

Values can be returned from the SWI call. They are stored in the variables
<variable 1> to <variable n>. The type of the variable is used to decide on
the type of the value returned. Strings returned by the SWI are converted to
BASIC strings. The processor flags can also be returned by the call if <flag
variable> is supplied. It is possible to discard values returned by  leaving
the position for that parameter after the 'TO' empty. The third example
below illustrates this (the first two values returned by the SWI are not
wanted).

On Matrix Brandy, calling OS_Write0 with R1 and R2 set to 42 will result in
the string pointed to in R0 being sent to the controlling terminal instead
of the SDL window.  This can be useful for some debugging scenarios.

Examples:
        SYS "OS_Write0", "abcdefgh"
        SYS 3
        SYS "OS_Byte", 134 TO , , row

TEMPO
Statement for controlling the RISC OS sound system.

THEN
Syntax: THEN

The THEN keyword is used in an IF statement. Refer to the section above on
the IF statement for more information.

Example:
        IF X%=1 THEN X%=2

TINT
Syntax: TINT <expression> , <tint expression>

The TINT statement only has an effect in 256 colour screen modes. It sets
the tint number <expression> to <tint expression>. <tint expression> can
take the values 0, 64, 128 or 192.

There are four colours settings used by the interpreter as follows:

        Text foreground colour
        Text background colour
        Graphics foreground colour
        Graphics background colour

Each of these has a tint value associated with it that is used in 256 colour
screen modes. This statement allows the tint values to be changed without
having to change the colours as well. The values to use to identify the tint
to change are as follows:

        0       Text foreground
        1       Text background
        2       Graphics foreground
        3       Graphics background

Example:
        TINT 0, 64

TO
Syntax: TO <expression>

The TO keyword is used in FOR loops to give the final value for the loop
variable. Refer to the section on the FOR statement above for more
information.

Example:
        FOR N% = 1 TO 10: NEXT

TRACE
Syntax: a) TRACE ON
        b) TRACE OFF
        c) TRACE TO <expression>
        d) TRACE CLOSE
        e) TRACE PROC
        f) TRACE GOTO
        g) TRACE VDU

The TRACE statement is used to help debug BASIC programs. It controls the
various trace options possible.

a) This form turns on the line number trace. This lists the number of each
   line executed.

b) This turns off all the traces.

c) This sends the trace output to the file named by the string expression
   <expression>. Normally output goes to the screen but it is directed to a
   file if this statement is used.

d) This closes the trace file. Trace output continues on the screen.

e) TRACE PROC displays the names of each procedure or function as it is
   entered and left.

===>PROC<name>  indicates that the procedure has been entered.
PROC<name>--->  indicates that the procedure has been left.

The trace can be turned off with the statement:

        TRACE PROC OFF

f) TRACE GOTO lists the origin and destination line numbers every time a
   branch occurs in a program, for example, whenever a procedure or function
   is called or there is a jump to the top of a loop. It can be used to see
   the path through the program in a more concise form than just displaying
   the number of every line executed. The output from the trace is of the
   form:
        [<line number 1>-><line number 2>]

This says that a branch has occured from <line number 1> to <line number 2>.

This trace can be turned off with the statement:

        TRACE GOTO OFF

g) TRACE VDU redirects output to the controlling terminal's stderr output
   stream.  This can be turned off with the statement:

        TRACE VDU OFF

Sending Trace Output to a File
------------------------------
'TRACE TO' is used to send trace output to a file. The handle of the file
can be found by using TRACE as a function. If it is not zero, output is
going to the file with this handle. It is possible to put extra data into
the trace file, for example:

        IF TRACE THEN BPUT#TRACE,"initialisation finished"

TRUE
Syntax: TRUE

The TRUE keyword returns the value BASIC uses to represent 'true' (-1).

Example:
        flag = TRUE

UNTIL
Syntax: UNTIL <expression>

The UNTIL keyword forms part of a 'REPEAT UNTIL' loop. Refer to the section
on the REPEAT statement for more information.

Example:
        REPEAT
          X%+=1
        UNTIL X%=10

VDU
Syntax: VDU <expression 1> , ... , <expression n>

The VDU command sends output to the screen. The numeric expressions
<expression 1> to <expression n> are evaluated one by one and the result
sent to the screen driver. The main purpose of this command is to send
screen control codes (the so-called 'VDU commands').

The amount of data sent for each expression depends on what follows the
expression. If there is a comma after it or it is the last expression in the
statement, one byte of data (the least significant byte of the result) is
sent. If there is a semicolon after it, two bytes of data are sent, the two
least significant bytes of the result. The least significant byte is sent
first, for example:

        VDU 31, 10, 10

This VDU command sends three bytes of data to the screen driver.

        VDU 29, 640; 512;

This example sends five bytes, 29 as one byte, 640 as two bytes as it is
followed by a ';' and 512 as two bytes.

If a '|' is used instead of a comma or semicolon, nine zeroes are sent.
This is useful when using the VDU 23 commands as nine bytes of data has to
be provided for these when the actual command might need only one or two
bytes. The extra zeroes are ignore or treated as no-ops.

Examples:
        VDU 31, 1, 1, ASC"a", 31, 2, 2, ASC"b"

The VDU statement allows any VDU command to be issued but the most common
ones are more conveniently handled by BASIC statements, for example, VDU 17
can be used to change the colour used for displaying text but the COLOUR
statement is easier.

VOICE
Statement for controlling the RISC OS sound system.

VOICES
Statement for controlling the RISC OS sound system.

WAIT
Syntax: a) WAIT
        b) WAIT <expression>

a) This version of the statement causes the program to be halted until the
   next vsync interrupt. It is used to synchronise drawing output on the
   screen with the hardware to make the output look neater.

Example:
        WAIT

b) This version is used to make the program wait for a period of time.
   <expression> is a numeric expression that gives the time for which the
   program will pause in centiseconds. Pressing the 'escape' key (either
   'Esc' or control C, depending on the environment) will cause the program
   to resume execution.

Example:
        WAIT 500

This will make the program pause for five seconds.

WHEN
Syntax: WHEN <expression> [,<expression>] :

Part of a 'CASE' statement. Refer to the section on the 'CASE' statement
above for more details.

WHILE
Syntax: WHILE <expression>

The WHILE statement marks the start of a WHILE loop. The format of one of
these is:

        WHILE <expression>
        <statements>
        ENDWHILE

The numeric expression <expression> is evaluated and if it is not zero the
loop entered. The program then continues until it comes across an ENDWHILE.
This is the end of the loop. The expression <expression> is evaluated again
and as long as the result is not equal to zero the program branches back to
the first statement after the WHILE statement.

Note that the first ENDWHILE found is considered to be the end of the loop.
It is possible for different ENDWHILEs to be used in the same loop, for
example, it is possible to write code such as:

        WHILE X%<10
          X%+=1
        IF X%<5 THEN ENDWHILE ELSE ENDWHILE

If the expression <expression> is zero the first time the WHILE statement is
executed, the loop is skipped. Note that the interpreter searches for the
first ENDWHILE it can find and assumes that that is the end of the loop.
This could give a problem if code like the example above is used.

The interpreter allows loops to be nested incorrectly and silently ignores
this sort of error, for example:

        WHILE X%<10
          X%+=1
          REPEAT
            Y%+=1
        ENDWHILE

The interpreter will not complain about the missing 'UNTIL' part of the
nested REPEAT loop.

Note also that the effects of any LOCAL DATA or LOCAL ERROR statements
encountered in the loop will be reversed when the program leaves the WHILE
loop.

WIDTH
Syntax: WIDTH <expression>

This statement sets the number of characters printed on each line by the
PRINT statement to <expression> characters. It automatically wraps round to
the next line when that number is reached. The default is the width of the
screen or text window.

Example:
        WIDTH 40


Commands
~~~~~~~~
Commands can only be entered on the command line with the exceptions of LIST
and LVAR which can be used in programs as well. As with keywords, commands
can often be abbreviated by typing the first few characters of the command
name and following that with a dot, for example, 'l.' is the abbreviated
form of the 'list' command. The section 'BASIC Keywords, Commands and
Functions' at the end of these notes gives the abbreviated versions of each
command.

On the command line, commands can be entered in mixed case (as opposed to
keywords, which have to be in upper case). If in a program they are treated
as normal keywords and have to be in upper case. This can give rise to
unexpected results, for example the program:

        10 list = 1.23
        20 PRINT list

will print the number 1.23, but if:

        list = 1.23

is entered on the command line it gives a syntax error as 'list' is seen as
a command. 'list' is in lower case in the program and therefore it is not
identified as the 'list' command. It is a variable called 'list' in the
program. It is best to avoid the use of commands as variable names in
programs where possible.

The commands available are:

APPEND
Not implemented.

AUTO
Syntax: AUTO [<base number>[,<step size>]]
This command generates line numbers for typing in a program. Where not
specified, <base number> and <step size> both default to 10.

CRUNCH
Ignored, not implemented.

DELETE
Syntax: DELETE <line number 1> [ , <line number 2> ]

The DELETE command is used to delete a single line or a range of lines from
a BASIC program. If a single line number is given then only that line is
removed. If two line numbers are provided then all lines in that range are
erased. It is not possible to retrieve lines that have been deleted in
error. Leaving the start and end lines out is permissible, in this case
lines from the start of the program and to the end of the program
respectively will be deleted. Leaving both out (just specifying the ,) will
delete the entire program.

Example:
        DELETE 100

EDIT
Syntax: EDIT [ <line number> ]

If a line number is supplied after the EDIT command, that line is
transferred to the command line where it can be edited.

If no line number is given, the program in memory is transferred to a text
editor where it can be more easily edited. When the program is saved, the
interpreter loads it back into memory.

The program is transferred to the editor using the current LISTO settings to
format it. This is not always the best way to do it so there is a variation
on the EDIT command, EDITO that can be used instead.

Examples:
        EDIT 100
        EDIT

EDITO
Syntax: EDITO <expression>

EDITO is a variation of the EDIT command. It allows the format of the
program to be controlled when it is transferred to the editor. <expression>
is a numeric expression that gives the 'LISTO' value to be used to format
the program. As with EDIT, the program is loaded back into memory when the
program is saved in the editor and the editor exited from.

The expression <expression> controls the format. The LISTO values useful in
this context are:

        1  Insert a space after the line number.
        2  Indent program structures such as block IF statements.
        8  Omit line numbers.

The LISTO value is obtained by adding together these numbers. If
<expression> is 10, the program is transferred to the editor without line
numbers and with structures indented. 

Example:
        EDITO 8

HELP
Syntax: HELP

HELP displays some information on the program in memory and LISTO and TRACE
debug options.

INSTALL
Syntax: INSTALL <expression 1>, <expression 2> , ... , <expression n>

This command loads the BASIC libraries named by the string expressions
<expression 1> to <expression n> into memory. If only the names of the
libraries are supplied, that is, the directory in which they live are not
given explicitly, the interpreter searches for them in the directories given
by the pseudo-variable FILEPATH$.

The libraries are permanently loaded into memory, unlike libraries that are
loaded via the LIBRARY statement which are discarded under some
circumstances. It is not possible to unload these libraries. On the other
hand the same library can be loaded via LIBRARY and it will be searched
before the version loaded using INSTALL.

The library search order is:

1)  Search libraries loaded via LIBRARY in the reverse order to that in
    which they were loaded.
2)  Search libraries loaded via INSTALL in the reverse order to that in
    which they were loaded.

Note that libraries are seen as an extension to the program in memory rather
than separate entities. They can have their own private variables (declared
using LIBRARY LOCAL) but any other variables created in procedures and
functions in the library will be added to those the program creates.

Example:
        INSTALL "proclib"

LIST
Syntax: LIST [ <line number 1> [ , <line number 2> ] ]

The LIST command lists lines in the BASIC program. If no line number is
given then the whole program is listed. If one line number is supplied then
just that line is displayed. If two line numbers are given then all lines in
that range are shown.

The lines are formatted according to the current setting of LISTO. One
useful option when listing a large number of lines is LISTO 32, which causes
the interpreter to pause when twenty lines have been listed until either the
space bar or return is pressed.

The line numbers can be given by expressions and, unlike other commands,
LIST can be used in a running program.

Examples:
        LIST
        LIST 100,200

        DEF PROCerror
        PRINT REPORT$;" at line ";ERL
        LIST ERL
        ENDPROC


LISTIF
Syntax: LISTIF <search string>

The LISTIF command provides a simple string search facility. <search string>
is the string to look for. Every line where the string is found is listed.

There are no wild card facilities.

Example:
        LISTIF PROCerror
        LISTIF abc%

LISTO 
Syntax: LISTO <expression>

LISTO is primarily used to control how programs are formatted when they are
listed. It also provides the default format used when transferring a program
to a text editor or when saving a program.

<expression> gives the new LISTO value. This is formed by adding together
one or more of the following values:

        1  Insert a space after the line number.
        2  Indent program structures such as block IF statements.
        8  Omit the line number.
        16 List keywords in lower case.
        32 Pause after displaying twenty lines when listing program.

The LISTO value is obtained by combining these, for example, indent
structures, omit line numbers and list keywords in lower case would be
2+8+16 = 26.

As noted above, the LISTO value is used by default when transfering programs
to an editor or saving them. This might not always be the best format so the
commands affected, EDIT and SAVE, have variations where the LISTO value to
be used for that command invocation is given.

Really, the LISTO values are bit settings and the LISTO value is obtained by
OR'ing them together.

Examples:
        LISTO 26
        LISTO (2+8+16)
        LISTO (LISTO+1)

LOAD
Syntax: LOAD <string expression>

The LOAD command is used to load a program into memory. Any existing program
and any variables created are discarded before the new program is read.

If the name is just the name of the file, that is, it does not contain any
directory names, the interpreter looks first in the current directory and
the searches through the directories listed by the pseudo-variable FILEPATH$
to find the program.

The name of the file is recorded and will be used as the name to use by
default by the SAVE command when the program is saved. Note that the name
(as shown by 'HELP') will normally include the name of the directory in
which the program was found.

Example:
        LOAD "abc"
        LOAD FNget_name

LVAR 
Syntax: LVAR [ <letter> ]

The LVAR command is used to list the variables, procedures and functions
that have been created or called in the program. If a letter is supplied
then only items whose name starts with that letter are listed. Note that
only a single letter can be given: it is not possible to give a pattern for
the names to be listed.

Variables are listed with their current values. The dimensions of arrays are
given but not the values of the elements. The types of the parameter of
procedures and functions are given. Some entries for procedures and
functions give the  line where they were found and no parameters. These are
procedures and functions that the interpreter has found in the program but
that have not been called yet.

Examples:
        LVAR
        LVAR x

NEW
Syntax: NEW [ <expression> ]

The NEW command has two purposes. Its main use is to discard the program in
memory and any variables that have been created. If the keyword NEW is
followed by an expression, it not only does this but changes the size of the
BASIC workspace to <expression> bytes.

The size of the BASIC workspace is fixed. It can be specified when the
interpreter starts via the command line option '-size'. The only way to
change it when the interpreter is running is via the NEW command.

Libraries loaded via INSTALL are retained over the change of workspace
size but the program in memory is lost and cannot be recovered.

Example:
        NEW 
        NEW 1000000

OLD
Syntax: OLD

The OLD command is used to attempt to recover a program in memory.
It is not supported in Matrix Brandy.

Example:
        OLD

RENUMBER
Syntax: RENUMBER [ <start expression> [ , <step expression> ] ]

The renumber command renumbers the lines of a program in memory. <start
expression> and <step expression> give the line number to use for the first
line and the increment from line to line. One or both can be omitted, in
which case they both default to ten.

<start expression> is in the range zero to 65279.
<step expression> is in the range one to 65279.

The renumber command will renumber the lines of the program and any explicit
references to line numbers on GOTO, GOSUB, ON GOTO, ON GOSUB and RESTORE
statements. Line numbers which are given by expressions cannot be dealt
with. Any line number references that refer to lines in the program that are
missing are left unchanged and a warning message put out. If the highest
line number allowed (65279) is exceeded the command renumbers the program
again with a start value of one and a step of one.

Examples:
        RENUMBER
        RENUMBER 1000
        RENUMBER 100,1

SAVE
Syntax: SAVE [ <string expression> ]

The SAVE command saves the program in memory in the file named by <string
expression>. The file is saved as plain text so that it can be edited with
any text editor.

<string expression> can be omitted. If this happens, the command looks for a
file name in two places:

1) It checks the first line of the program. If there is a '>' that is
   followed by some text, that text is used as the name of the file. (This
   follows an Acorn convention where the first line of a file gives its
   name).

2) If the first check fails, the name saved from the last 'LOAD' or 'SAVE'
   command is used.

An error is reported if a name cannot be found.

The program is saved in text form using the current LISTO settings to format
it. If this is not what is desired, the SAVEO command can be used.

The name <string expression> is saved for use by later SAVE commands if it
is supplied.

Examples:
        SAVE "abcdefgh"
        SAVE A$+"/abc"
        SAVE

SAVEO
Syntax: SAVEO <expression> [ , <string expression> ]

The SAVEO command is just like the SAVE command. It saves the program in
memory in the file named <string expression>. The difference between it and
SAVE is that the LISTO value to be used to format the program when writing
it to the file is specified by <expression>. The LISTO values useful in this
context are:

        1  Insert a space after the line number.
        2  Indent program structures such as block IF statements.
        8  Omit line numbers.

The LISTO value is obtained by adding together these numbers. If
<expression> is 10, the program is saved without line numbers and with
structures indented. 

As with SAVE, <string expression> can be omitted. If this happens, the
command looks for a file name in two places:

1) It checks the first line of the program. If there is a '>' that is
   followed by some text, that text is used as the name of the file. (This
   follows an Acorn convention where the first line of a file gives its
   name).

2) If the first check fails, the name saved from the last 'LOAD' or 'SAVE'
   command is used.

An error is reported if a name cannot be found.

The name <string expression> is saved for use by later SAVE commands if it
is supplied.

Examples:
        SAVEO 10 , "abcdefgh"
        SAVEO 3

TEXTLOAD
Syntax: TEXTLOAD <string expression>

This command is a synonym for the LOAD command in this interpreter. Refer to
the section on the LOAD command above for more details.

TEXTSAVE
Syntax: TEXTSAVE [ <string expression> ]

This command is a synonym for the SAVE command in this interpreter. Refer to
the section on the SAVE command above for more details.

TEXTSAVEO
Syntax: TEXTSAVEO <expression> [ , <string expression> ]

This command is a synonym for the SAVEO command in this interpreter. Refer
to the section on the SAVEO command above for more details.

TWIN
Syntax: TWIN

This command is a synonym for the EDIT command in this interpreter. Refer to
the section on the EDIT command above for more details.

TWINO
Syntax: TWINO <expression>

This command is a synonym for the EDITO command in this interpreter. Refer
to the section on the EDITO command above for more details.


The Program Environment
~~~~~~~~~~~~~~~~~~~~~~~
The interpreter provides a partial implementation of the operating system
under which the Acorn interpreter runs, RISC OS. The implemention is limited
to supporting the control codes used for screen output and the file handling
used by the program. It is not an attempt to write a RISC OS emulation
layer.


Screen Output
~~~~~~~~~~~~~
The interpreter implements a RISC OS VDU driver for screen output so some
details of how these work and the facilities available follow.

VDU Driver
----------
The VDU driver is the portion of RISC OS that handles screen output. RISC OS
mixes text and graphics on the same screen. The screen size can be measured
in text coordinates or graphics coordinates.

Text coordinates have their origin at the top left-hand corner of the screen
and extend to the left and downwards:

        (0,0)
          +----------+
          |          |
          |          |
          +----------+
                  (79,31)


Graphics coordinates have their origin at the bottom left-hand corner of the
screen and extend to the left and upwards:

                (1279,1023)
          +----------+
          |          |
          |          |
          +----------+
        (0,0)

The values in the diagrams are just examples.

Text coordinates are just character positions on screen. The range of the
coordinates varies according the screen resolution.

Graphics coordinates are more complex. Going back to the days of the BBC
Micro, the range of the coordinates was fixed at 0 to 1279 in the X
direction and 0 to 1023 in the Y direction. This was independent of the
screen resolution; the operating system mapped the graphics on to it. Later
the mapping was changed when the range of screen resolutions available was
increased and larger sizes became available. Up to a resolution of 640 by
512 pixels, the graphics coordinates are in the range given earlier (with
a couple of exceptions). For sizes larger than that, the general rule is
that the graphics coordinate range is twice that of the pixels, for example,
the graphics coordinate range for a screen resolution of 800 by 600 is 1600
by 1200 (0 to 1599 and 0 to 1199).

Graphics coordinates in the X and Y direction are in the range -32768 to
32767.

The screen resolution and number of colours can be set using the 'MODE'
command. This can be either a number that identifies the mode to use or a
string that gives its details.

Colours
-------
RISC OS supports colour depths of 1, 2, 4, 8, 15 and 24 bits per pixel. The
interpreter support 1, 2, 4 and 8 bit. The way colours are dealt with in
2-colour (1 bit), 4-colour (2 bit) and 16-colour (4 bit) modes is straight
forwards but manipulating colours in 256 colour modes is slightly awkward
due to the way the colour system was originally designed back in the days of
the BBC Micro using an 8-bit VDU stream.

2, 4 and 16 Colour Modes
------------------------
There are logical colours and physical colours. The colour corresponding to
each logical colour can be changed by means of VDU 19. The number
corresponding to each physical colour is as follows:

        0 (8)   Black
        1 (9)   Red
        2 (10)  Green
        3 (11)  Yellow
        4 (12)  Blue
        5 (13)  Magenta
        6 (14)  Cyan
        7 (15)  White

(Note: depending on the capabilities of the host hardware, colour numbers 8
to 15 may simply repeat colours 0 to 7. On RISC OS they give flashing
numbers, on other platforms they give bright versions of the lower-numbered
colours.)

256 Colour Modes
----------------
In 256-colour modes the colour is broken into two components, the colour and
a 'tint' value used to modify it. The colour portion is six bits and the
tint two bits. The colours in these modes are constructed from sixty three
colours, each of which has four brightness levels. Unlike the other colour
depths, the 256 colour palette is essentially fixed and the colour number
made up of the colour and tint determines which of these fixed colours to
used.

The tint value affects the brightness of the colours. It changes the level
of all three (red, green and blue) colours components at the same time. It
has four values: 0, 1, 2 and 3 but these are written as 0, 64, 128 and 192.

The VDU drivers works in terms of the following colours when writing text or
plotting graphics:

        Text foreground colour
        Text background colour
        Graphics foreground colour
        Graphics background colour


Text and Graphics Windows
-------------------------
It is possible to define text and graphics windows so that output goes to a
restricted portion of the screen. Effectively the windows by default occupy
the entire screen but they can be changed at any time.

Text-only Modes
---------------
Three of the screen modes, modes 3, 6 and 7, do not support graphics. There
are a hangover from the days of the BBC Micro.


VDU Commands
~~~~~~~~~~~~
The VDU commands are the escape sequences that the interpreter uses to
control output, for example, to move the cursor to a specific location on
the screen. It is customary to refer to these as 'VDU commands'.

The ASCII character codes in the range 0 to 31 are used. The format of a VDU
code is a single command byte followed by up to nine bytes of data. The
complete list follows:

0       Does nothing
1       Send next character to the printer
2       Enable sending of characters to the printer
3       Disable sending sending of character to the printer
4       Display text at the text cursor position
5       Display text at the graphics cursor position
6       Enable the VDU drivers
7       Sound the console bell
8       Move the cursor back one character
9       Move the cursor forwards one character
10      Move the cursor down one line
11      Move the cursor up one line
12      Clear the text screen
13      Move the cursor to the start of the line
14      Enable page mode
15      Disable page mode
16      Clear the graphics window
17      Change the current text colou
18      Change the current graphics colour
19      Map logical colour to physical colour
20      Reset logical colours to default values
21      Disable the VDU driver
22      Change the screen mode
23      Various commands
24      Define the graphics window
25      Issue a graphics command
26      Restore default text and graphic windows
27      Do nothing
28      Define the text window
29      Define the graphics origin
30      Send cursor to top left-hand corner of window
31      Send cursor to given position in window

Brandy's VDU driver does not support all of these on all target platforms.
The following table says what works where. The column marked 'Text' says
whether the code is supported (yes), flagged as an error (no) or ignored
(ignore) in text-only versions of the program. The column 'Graphics' gives
the same information for versions that support graphics (including the text-
mode build with Tektronix support enabled).

        Code    Text            Graphics
        ----    ----            --------
        0       yes             yes
        1       yes*            yes*
        2       yes*            yes*
        3       yes*            yes*
        4       ignored         yes
        5       no              yes
        6       ignored         yes
        7       yes             yes
        8       yes             yes
        9       yes             yes
        10      yes             yes
        11      yes             yes
        12      yes             yes
        13      yes             yes
        14      ignored         yes
        15      ignored         yes
        16      no              yes     
        17      yes             yes
        18      no              yes
        19      yes             yes
        20      yes             yes
        21      ignored         yes
        22      yes             yes
        23      yes             yes
        24      no              yes
        25      no              yes
        26      yes             yes
        27      yes             yes
        28      yes             yes
        29      no              yes
        30      yes             yes     
        31      yes             yes
* VDU codes 1-3 are only implemented on UNIX/Linux hosts with CUPS enabled,
and are ignored on other non-RISC OS platforms. On RISC OS, VDU is simply
passed through to the OS and Matrix Brandy does not attempt to emulate any
codes.

Details of the supported commands follow.

VDU 0
Does nothing.

VDU 1
This sends the next character to the printer stream.

VDU 2
This enables the printer on RISC OS and Linux.
Under Linux, it prints to the default printer using 'lpr', therefore to set
a specific printer, use:
SYS "Brandy_dlcall","setenv","PRINTER","<printer name>",1

VDU 3
This disables the printer.

VDU 4
Display text at the text cursor position.

VDU 5
Display text at the graphics cursor position. Text is sent to the current
graphics cursor position with the graphic cursor defining the position of
the top left-hand corner of the character. The graphics cursor position in
the X direction is updated by the width of a character expressed in graphics
units. If the edge of the window is reached output continues on the next
line, that is, the graphics Y coordinate is decreased by the height of a
character expressed in graphics units and the X coordinate is reset to the
edge of the graphics window.

Note that text written in this mode overwrites what is currently on the
screen without clearing the background of each character.

VDU 6
This re-enables VDU output after it has been disabled with VDU 21.

VDU 7
Sound the console bell.

VDU 8
Move the cursor back one character. The text cursor is moved back one
character, moving up a line and wrapping around to the right-hand edge of
the text window if it is at the left-hand edge of the window. If the cursor
is at the top left-hand corner of the window it wraps around to the end of
the line and scrolls the window down by one line.

If text output is being sent to the graphics cursor the actions are
basically the same but they affect the graphics cursor instead and leave the
text cursor unchanged. The only difference is that the cursor wraps around
to the bottom right-hand corner of the window if it was originally
positioned in the top left-hand corner instead of scrolling the screen.
Changes in the X and Y coordinates are by the width and height of a
character expressed in graphics units respectively.

VDU 9
Move the cursor forwards one character. The actions performed follow the
same pattern as VDU 8. The text cursor is moved forwards by one character,
moving down a line and wrapping around to the left-hand edge of the text
window if it was originally positioned at the right-hand edge of the window.
If it was originally positioned at the bottom right-hand corner of the
window it is move to the left-hand edge and the window is scrolled up one
line.

If text output is being sent to the graphics cursor the actions affect the
graphics cursor instead of the text cursor. As in the case of VDU 8, the
only difference is when the graphics cursor is at the bottom right-hand
corner of the graphics window. It wraps around to the top left-hand corner.

VDU 10
Move the cursor down one line. The text cursor is moved down the window by
one line. If it was originally on the bottom line of the text window it
remains on that line and the window is scrolled upwards by one line. If text
is being sent to the graphics cursor, the Y coordinate of the graphic cursor
position is decreased by the height of a character expressed in graphics
units. If the graphics cursor was originally at the bottom of the window it
wraps around to the top.

VDU 11
Move the cursor up one line. Again this follows the same pattern as VDU 10.
The text cursor is moved up by one line unless it was originally positioned
on the top line of the window, in which case it is left there and the window
is scrolled down by one line.

If output is going to the graphics cursor, the Y coordinate of the cursor is
increased by the height of a character expressed in graphics units unless
the cursor was located at the top of the window, in which case it is moved
to the bottom.

VDU 12
In VDU 4 mode, this clears the text window. The text window is set to the
text background colour.  In VDU 5 mode, this is equivalent to VDU 16 (CLG).
In VDU 5 mode, the graphics cursor is moved to the top left of the screen
for printing text at the graphics cursor.

VDU 13
Move the cursor to the start of the line. The cursor is moved to the left-
hand edge of the window on the current line. If output is being sent to the
graphics cursor it is the graphics cursor that is moved otherwise it is the
text one.

VDU 14
Enable paged mode, where scrolling is paused until the SHIFT key is pressed.

VDU 15
Disable paged mode, reversing the effect of VDU 14.

VDU 16
Clear the graphics window. The entire graphics window is set to the current
graphics background colour.

VDU 17
Change the current text colour. This is followed by one byte of data, the
new colour number. If this is less than 128 the foreground colour is
changed, otherwise the background colour is the one altered, the number of
the colour to use being given by the colour number AND 127.

The colour number is reduced modulo the number of colours available in the
current screen mode in 2, 4 and 16 colour modes. In 256 colour modes it is
reduced modulo 64. This alters the colour value but not the tint (see the
section '256 Colour Modes' above for an explanation of this).

VDU 18
Change the current graphics colour. This is followed by two bytes of data:

Byte    1       Plot action
        2       Colour number

The 'plot action' controls how graphics are plotted on the screen.

If the colour number is less than 128 the foreground graphics colour is
changed, otherwise the background colour is updated The colour number used
is the colour number AND 127, as with VDU 17. The colour number is then
reduced modulo the number of colours available in the current screen mode in
2, 4 and 16 colour modes. In 256 colour modes it is reduced modulo 64 to
change the colour value. It does not affect the tint (see the section 256
Colour Modes' above for more information on this).

VDU 19
Map logical colour to physical colour.

This requires five bytes of data after the command as follows:

Byte    1       Logical colour number
        2       Physical colour number
        3       Red component
        4       Green component
        5       Blue component

The logical colour number is reduced modulo the number of colours available
in the current screen mode in 2, 4 and 16 colour modes.

If the physical colour number is in the range zero to fifteen the physical
colour corresponding to the given logical colour is changed to the value
supplied. The red green and blue colour components are ignored. This version
of the VDU command only has an effect in 2, 4 and 16 colour modes.

If the physical colour number is sixteen, the colour for the given logical
colour number is changed to the one with the red, green and blue components
supplied in bytes 3, 4 and 5.

Physical colour numbers greater than 16 are ignored in versions of the
interpreter that do not run under RISC OS.

VDU 20
Reset logical colours to default values.

VDU 21
Disable VDU output. All codes are ignored except VDU 6.

VDU 22
Change the screen mode. This takes one byte of data, the new screen mode. It
causes the text and graphics windows to be set to cover the whole screen,
resets the colour palette to its default for that mode and moves the text
and graphics cursors to their respective origins.

VDU 23
VDU 23 has two purposes. Firstly, it allows any of the characters with codes
in the range 32 to 255 to be redefined and, secondly, it is the code used
for a range of commands that affect the operation of the VDU drivers.

VDU 23 requires nine bytes of data. The format is:

Byte    1       Command or character code
        2 to 9  Command or character data

If the first byte, the command byte, is in the range 32 to 255 VDU 23 is
being used to define the layout of the character with that code. The eight
bytes of data that follow contain the image for that character. If the
command byte is in the range 0 to 31 then it is a command for the VDU
driver. Eight bytes of data must be supplied but the command might ignore
them.

Some of the VDU 23 commands are supported:

        23,0    Control some cursor effects.
        23,1    Hide or show the text cursor.
        23,7    Scroll rectangle on screen
        23,16   Define cursor movement
        23,17   Set the 'tint' value in 256 colour screen modes.
        23,18   Control soft Teletext implementation.
        23,22   BB4W/BBCSDL custom screen mode (not under RISC OS)

23,0
----
This is only minimally implemented, to support cursor control (on the BBC
Micro as CRTC6845 register 10).

23,1
----
The two values defined are:

        23,1,0  This removes the text cursor
        23,1,1  This displays the text cursor

23,6
----
The format of this command is:
VDU 23,6,n1,n2,n3,n4,n5,n6,n7,n8

Tnis sets the dotted line pattern used by dotted PLOT commands.

23,7
----
The format of this command is:
VDU 23,7,<extent>,<direction>,<movement>,0,0,0,0,0

where:
<extent> says what to scroll:
        0:      Scroll the current text window
        1:      Scroll the entire screen

<direction>:
        0:      Scroll right
        1:      Scroll left
        2:      Scroll down
        3:      Scroll up
        4:      Scroll in positive X direction
        5:      Scroll in negative X direction
        6:      Scroll in positive Y direction
        7:      Scroll in negative Y direction

<movement>:
        0:      Scroll by one character cell
        1:      Scroll by one character cell vertically, or one byte
                horizontally (NOT SUPPORTED), option ignored.

23,16
-----
The format of this command is:
VDU 23,16,x,y,0,0,0,0,0,0

This allows the direction of the cursor movement after a character is
printed to be specified. The new direction is specified with (old value AND
y) EOR x, and the new status is interpreted as:
b7      0 Normal value, 1 undefined.
b6      VDU5 mode, 0 has the text wrap at the edge of the screen, 1 has no
        wrap.
b5      0 Cursor moved in positive X direction after a character is printed.
        1 Cursor does not move after a character is printed.
b4      0 Cursor movement in the postive Y direction past the bottom of the
          text window causes the window to scroll in VDU 4 mode.
        1 Cursor movement in the postive Y direction past the bottom of the
          text window always causes the text cursor to be moved to the
          opposite edge of the window.
b3,2,1  define the cursor direction as follows:
0 0 0   X direction is right, Y direction is down
0 0 1   X direction is left, Y direction is down
0 1 0   X direction is right, Y direction is up
0 1 1   X direction is left, Y direction is up
Options with b3 = 1 are not supported, but are listed below what is
intended:
1 0 0   X direction is down, Y direction is right
1 0 1   X direction is down, Y direction is left
1 1 0   X direction is up, Y direction is right
1 1 1   X direction is up, Y direction is left

b0      0 Disables scroll protection, the text cursor moving off the
          positive edge of the window will always move directly to the next
          line, scrolling the window if necessary. (BBC Master/Arc
          *configure scroll)
        1 Enables scroll protection, the text cursor moving off the positive
          edge of the window waits at the dge of the window until the
          movement is needed. (BBC Master/Arc *configure noscroll)

23,17
-----
The format of this command is:

VDU 23,17,<option>,<tint>,0,0,0,0,0,0

where:

<option> says what to set:
        0       Set foreground text tint value
        1       Set background text tint value
        2       Set foreground graphics tint value
        3       Set background graphics tint value
        5       Swap foreground and background text colours

<tint> sets the new tint value. Only the top two bits are significant,
giving values of 0, 64, 128 and 192.

23,18
-----
See docs/Mode7.txt

23,22
-----
This defines a custom mode. Inspired by BB4W/BBCSDL but not an exact
replica. The format of this command is:
VDU 23,22,<xpixels>;<ypixels>;<xchars>,<ychars>,<colours>,<flags>

As Matrix Brandy uses an 8x8 character set for all screen modes (other than
7), the implementation is approximate.
<colours> - valid values are 0 (for 256), 2, 4 and 16.
<flags> - only bit 7 is implemented, sets black on white text.

VDU 24
Define the graphics window.

This requires eight bytes of data after the command as follows:

Bytes 1 and 2   x coordinate of left-hand side of window.
Bytes 3 and 4   y coordinate of bottom of window.
Bytes 5 and 6   x coordinate of right-hand side of window.
Bytes 7 and 8   y coordinate of top of window.

Each pair of bytes is treated as a two byte signed integer with the least
significant byte sent first. The coordinates are given relative to the
current screen origin. The command is ignored if any of the coordinates lie
outside the screen.

VDU 25
Issue a graphics command. Any graphics operation such as drawing a line or
plotting a circle goes can be carried out using VDU 25. The code is followed
by five parameter bytes as follows:

Byte    1       Graphics PLOT code
        2       Low byte of first parameter
        3       High byte of first parameter
        4       Low byte of second parameter
        5       High byte of second parameter

See the section 'PLOT Codes' below for details of the graphics commands
allowed.

VDU 26
Restore default text and graphic windows. The text and graphics windows are
set to full screen. The text cursor is moved to the top left-hand corner of
the screen and the current graphics position set to (0, 0), which is at the
bottom left-hand corner of the screen. The graphics origin is also reset to
this position.

VDU 27
Does nothing.

VDU 28
Define the text window.

This command requires four bytes of data as follows:

Byte    1       column number of left-hand side of window.
        2       Row number of bottom of window.
        3       Column number of right-hand side of window.
        4       Row number of top of window.

If any of the coordinates are off the screen the command is ignored.

VDU 29
Define the graphics origin.

This requires four bytes of data after the command as follows:

Bytes 1 and 2   x coordinate of graphics origin.
Bytes 3 and 4   y coordinate of graphics origin.

The pair of bytes is treated as a two byte signed integer with the low-order
byte send first. The coordinates are absolute, that is, they are not
specified relative to the current graphics origin.

VDU 30
Send cursor to top left-hand corner of window. The text cursor (or the
graphics cursor if text is being plotted at the graphics cursor) is sent to
the top left-hand corner of the window.

VDU 31
Send cursor to given position in window.

This requires two bytes of data after the command:

Byte    1       Column number
        2       Row number

The text cursor (or the graphics cursor if text is being plotted at the
graphics cursor) is sent to the position corresponding to text coordinate
(column, row) on the screen.

PLOT Codes
~~~~~~~~~~
Plot codes form the heart of the graphics support. Normally use of these is
hidden behind BASIC statements such as 'MOVE', 'DRAW' and 'CIRCLE' but they
can be used directly in programs by means of the 'PLOT' statement and VDU
25.

The codes are in the range 0 to 255. Each code can really be thought of as
containing three fields which specify the operation, how the graphics
coordinates are to be interpreted and how to treat the graphics colours. The
graphic operation is given by (plot code DIV 8). How to treat the
coordinates and colours is given by (plot code MOD 8). It is easier to
understand plot codes if they are written in binary. They can be expressed
in this way as:

        xxxxx y zz

where 'xxxxx' is the graphics operation, 'y' says how to treat the
coordinates and 'zz' how to handle the colours. 'y' and 'zz' are defined as
follows:

'y' values:
        0       Treat coordinate as relative
        1       Treat coordinate as absolute

'zz' values:
        0       Only move the graphics cursor.
        1       Plot graphics using graphics foreground colour.
        2       Plot graphics using logical inverse of colour at each point.
        3       Plot graphics using graphics background colour. 

Brandy's VDU driver does not support the full range of PLOT codes. The ones
implemented are:

          0-  7 Draw a solid line
          8- 15 Draw a solid line excluding the final point
         16- 23 Draw a dotted line
         24- 31 Draw a dotted line excluding the final point
         32- 39 Draw a solid line excluding the start point
         40- 47 Draw a solid line excluding the start and final points
         48- 55 Draw a dotted line excluding the start point
         56- 63 Draw a dotted line excluding the start and final points
         64- 71 Plot a single point
         80- 87 Draw a filled triangle
         96-103 Draw a filled rectangle
        112-119 Draw a filled parallelogram
        128-135 Flood fill background
        144-151 Plot a circle outline
        152-159 Draw a filled circle
        160-167 Draw a circular arc
        184-191 Move or copy a rectangle
        192-199 Draw an ellipse outline
        200-207 Plot a filled ellipse

Typical plot codes used are 4 (move graphics cursor), 5 (draw a line) and 69
(plot a point).

Mode Variables
~~~~~~~~~~~~~~
The VDU function can be used to find out information about the current
screen mode being used, for example, the width of the screen in characters
or in pixels. It is used as in the following example:

        width% = VDU 1
        PRINT"Screen width in characters is "; width%

The allowed values and what they return are as follows:

  0  ModeFlags          0 if mode is capable of graphics
                        1 if mode is text only.
  1  ScrRCol            Width of screen in characters - 1
  2  ScrBRow            Height of screen in characters - 1
  3  NColour            Number of colours allowed - 1
 11  XWindLimit         Width of screen in pixels - 1
 12  YWindLimit         Height of screen in pixels - 1
128  GWLCol             Graphics window left limit in pixels
129  GWBRow             Graphics window bottom limit in pixels
130  GWRCol             Graphics window right limit in pixels
131  GWTRow             Graphics window top limit in pixels
132  TWLCol             Text window left limit in characters
133  TWBRow             Text window bottom limit in characters
134  TWRCol             Text window right limit in characters
135  TWTRow             Text window top limit in characters
136  OrgX               Graphics X origin in RISC OS graphics units
137  OrgY               Graphics Y origin in RISC OS graphics units
153  GFCOL              Graphics foreground colour
154  GBCOL              Graphics background colour
155  TForeCol           Text foreground colour
156  TBackCol           Text background colour
157  GFTint             Graphics foreground tint value
158  GBTint             Graphics background tint value
159  TFTint             Text foreground tint value
160  TBTint             Text background tint value
161  MaxMode            Highest screen mode number supported

The names in the second columns are what the mode variables are labelled in
RISC OS documentation.

If the value passed to the function is not one of the above, the function
returns 0.

The mode variables that return graphics information will return zero in
versions of the program that do not support graphics.

The RISC OS version of the program supports the full range of mode
variables. The ones given above represent only a selection of them. The
complete list can be found on pages 703 to 705 and 710 and 711 of volume 1
of the RISC OS Programmer's Reference Manual.


BASIC Keywords, Commands and Functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

BASIC Keywords
--------------
This is a list of all of the BASIC keywords and their minimum abbreviations.
The '.' after each abbreviated name is considered to be part of the name.

Keyword         Abbreviation    Keyword         Abbreviation

AND             A.              BEATS           BE.
BPUT            BP.             CALL            CA.
CASE            CAS.            CHAIN           CH.
CIRCLE          CI.             CLG             CLG
CLEAR           CL.             CLOSE           CLO.
CLS             CLS             COLOUR          C.
DATA            D.              DEF             DEF
DIM             DIM             DIV             DI.
DRAW            DR.             ELLIPSE         ELL.
ELSE            EL.             END             END
ENDCASE         ENDC.           ENDIF           ENDI.
ENDPROC         E.              ENDWHILE        ENDW.
ENVELOPE        ENV.            EOR             EOR
ERROR           ERR.            FALSE           FA.
FILL            FI.             FN              FN
FOR             F.              GCOL            GC.
GOSUB           GOS.            GOTO            G.
HIMEM           H.              IF              IF
INPUT           I.              LET             LET
LIBRARY         LIB.            LINE            LIN.
LOCAL           LOC.            MOD             MOD
MODE            MO.             MOUSE           MOU.
MOVE            MOV.            NEXT            N.
NOT             NOT             OF              OF
OFF             OFF             ON              ON
OR              OR              ORIGIN          OR.
OSCLI           OS.             OTHERWISE       OT.
OVERLAY         OV.             PLOT            PL.
POINT           POINT           PRINT           P.
PROC            PROC            QUIT            Q.
READ            REA.            RECTANGLE       REC.
REM             REM             REPEAT          REP.
REPORT          REPO.           RESTORE         RES.
RETURN          R.              RUN             RU.
SOUND           SO.             STEP            S.
STEREO          STER.           STOP            STO.
SWAP            SW.             SYS             SY.
TEMPO           TE.             THEN            TH.
TINT            TIN.            TO              TO
TRACE           TR.             TRUE            TRU.
UNTIL           U.              VDU             V.
VOICE           VOICE           VOICES          VO.
WAIT            WA.             WHEN            WHE.
WHILE           W.              WIDTH           WI.

BASIC Commands
--------------
Following is a list of all of the BASIC commands and their minimum
abbreviations.

APPEND          AP.             AUTO            AU.
CRUNCH          CR.             DELETE          DEL.
EDIT            ED.             EDITO           EDITO
HELP            HE.             INSTALL         INSTAL.
LIST            L.              LISTIF          LISTIF
LISTO           LISTO           LOAD            LO.
LVAR            LVA.            NEW             NEW
OLD             O.              RENUMBER        REN.
SAVE            SA.             SAVEO           SAVEO
TEXTLOAD        TEX.            TEXTSAVE        TEXTS.
TEXTSAVEO       TEXTSAVEO       TWIN            TWIN
TWINO           TWINO


Functions and Pseudo Variables
------------------------------
Following is a list of all of the BASIC functions and pseudo variables and
their minimum abbreviations.

ABS             AB.             ACS             AC.
ADVAL           AD.             ARGC            ARGC
ARGV$           ARGV$           ASC             AS.
ASN             ASN             ATN             AT.
BEAT            BEAT            BGET            B.
CHR$            CHR$            COS             COS
COUNT           COU.            DEG             DE.
EOF             EOF             ERL             ERL
ERR             ERR             EVAL            EV.
EXP             EXP             EXT             EXT
FILEPATH$       FILE.           GET             GET
GET$            GE.             INKEY           INKEY
INKEY$          INK.            INSTR(          INS.
INT             INT             LEFT$(          LE.
LEN             LEN             LN              LN
LOG             LOG             LOMEM           LOM.
MID$(           M.              OPENIN          OP.
OPENOUT         OPENO.          OPENUP          OPENU.
PAGE            PA.             PI              PI
POS             POS             PTR             PTR
RAD             RA.             RIGHT$(         RI.
RND             RN.             SGN             SG.
SIN             SI.             SQR             SQR
STR$            STR.            STRING$(        STRI.
SUM             SU.             SUMLEN          SUMLEN
SYS(            SYS(            TAN             T
TIME            TI.             TIME$           TIME$
TOP             TOP             USR             US.
VAL             VA.             VERIFY(         VE.
VPOS            VP.             XLATE$          XL.