Matrix Brandy
~~~~~~~~~~~~~

Contents
~~~~~~~~
        Introduction
        Copyright
        Disclaimer
        Using the Interpreter
        Running Programs
        Programs and Libraries
        Differences Between Brandy and RISC OS's Interpreter
        Identifying the Environment Under Which Brandy is Running
        I/O Redirection
        Using BASIC as a Script Language Under NetBSD and Linux
        The SYS Statement
        The 'key' Command
        Performance
        Important Error Messages
        Known Problems
        Miscellaneous Comments
        Conclusion
        Contact


Introduction
~~~~~~~~~~~~
Matrix Brandy is a BASIC V/VI interpreter. It is source code compatible with
Acorn's BASIC V/VI interpreter and runs under a number of different
operating systems. It currently works with NetBSD (arm32 and i386), Linux
(x86, z86-64 and arm32) and Microsoft Windows. The aim of this project is to
write a BASIC interpreter that is compatible with the Acorn interpreter and
that runs almost identically across all supported operating systems,
emulating features of the RISC OS environment where necessary so that a
program will run unchanged using the Acorn interpreter under RISC OS or this
one under any other OS. No attempt has been made to support features of
operating systems other than RISC OS, for example, it is not possible to
make operating system calls from within a program except under RISC OS. The
program is simply a BASIC interpreter and that is all.
 
These notes describe how to use the program and discuss differences between
it and Acorn's interpreter. They also detail the extensions to BASIC V/VI
that have been implemented and finish with some miscellaneous remarks about
the program and a list of the known bugs.


Copyright
~~~~~~~~~
Brandy is copyright (C) 2000-2014 David Daniels.
Matrix Brandy modifications are copyright (C) 2018-2024 Michael McConnell
and contributors.

The program is distributed under the terms of the GNU GPL.

Brandy, and Matrix Brandy, is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option) any
later version.

Matrix Brandy is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
more details.

You should have received a copy of the GNU General Public License along with
Matrix Brandy; see the file COPYING.  If not, write to the Free Software
Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.


Disclaimer
~~~~~~~~~~
The Matrix Brandy BASIC interpreter is provided 'as is' and people using it
do so entirely at their own risk. No liability whatsoever will be accepted
for any loss or damage arising from the use of this software.


Using the Interpreter
~~~~~~~~~~~~~~~~~~~~~
To invoke the interpreter, type:

        brandy [ <options> ] [ <filename> ]

where <filename> is the optional name of the program to load and
<options> is one or more of the following:

-help                   Print a summary of these options.

-version                Print the version of Matrix Brandy.

-nocheck                Don't try to check for new versions of Brandy on
                        interactive mode startup.

-size <size>            Set the size of the BASIC workspace to <size> bytes
                        when starting the interpreter.  The minimum size
                        allowed is 16384 bytes and anything below this value
                        will be set to it. The maximum size is 4294966272
                        bytes (1K short of 4GB), The size may have a
                        suffix of 'k', 'm' or 'g' to denote that the size is
                        in kilobytes, megabytes or gigabytes respectively,
                        for example, '-size 100k' will set the workspace
                        size to 100 kilobytes (102400 bytes) and '-size 8m'
                        will set it to eight megabytes (8388608 bytes).

-fullscreen             (SDL build only) Start Brandy in fullscreen mode.

-nofull                 (SDL build only) Never use fullscreen mode.

-swsurface              (SDL build only) Use a software SDL surface.

-tek                    (Text-mode 'tbrandy' build only) Enable Tektronics
                        graphics.

-path <directory list>  This specifies a list of directories that the
                        interpreter will search when looking for libraries
                        and programs. The directory names are separated by
                        commas. The pseudo-variable 'FILEPATH$' is set to
                        this value. See the section below on FILEPATH$ for
                        more details.

-load <filename>        Load BASIC program <filename> when the interpreter
                        starts.

-chain <filename>       Load and run the BASIC program <filename>. Remain in
                        the interpreter when the program has finished
                        running.

-quit <filename>        Load and run the BASIC program <filename>. Leave the
                        interpreter when the program has finished running.

-lib <filename>         Load BASIC library <filename> when the interpreter
                        starts. This option can be repeated as many times as
                        required to load a number of libraries. This is
                        equivalent to typing 'INSTALL <filename>' at the
                        interpreter's command line. The libraries are loaded
                        in the order given on the command line. Note that
                        the search order is the reverse of this.

-ignore                 (If strict mode enabled by default) Ignore certain
                        'unsupported feature' errors.
                        This option allows some unsupported features that do
                        not affect the basic running of the program to be
                        ignored.

-strict                 (If ignore mode enabled by default) The interpreter
                        will report an error whenever it comes across a
                        BASIC V/VI feature that it does not support, and
                        some obvious BASIC program bugs that are ignored by
                        the Acorn interpreter.

-nostar                 Do not check commands issued via OSCLI to see if
                        they are dealt with by Brandy. Pass all commands to
                        the underlying operating system.

-lck                    Allow use of lower-case in keywords.

--                      Subsequent options are passed to the BASIC program,
                        rather than being considered as options to the
                        interpreter.

<filename>              Load and run the BASIC program <filename>. Remain in
                        the interpreter when the program has finished
                        running.

The case of the names of the options is ignored. It depends on the operating
system under which the interpreter is running as to whether or not the names
of files are case sensitive.

Most of these items can be put into a configuration file, those that cannot
be used are -load, -chain, -quit, -version, --help or a supplied program to
run.  This configuration file lives, depending on your platform, in
$HOME/.brandyrc
%APPDATA%\brandyrc
<Brandy$Dir>.brandyrc

Some tunables can also be set in this file. For more details see Config.txt.

Minimum Abbreviations
---------------------
Options can be abbreviated. The interpreter only checks the first
few characters of the option name to identify it.

-chain          -c
-fullscreen     -f
-help           -h
-ignore         -ig
-lib            -li
-load           -lo
-nocheck        -noc
-nofull         -nof
-nostar         -nos
-path           -p
-quit           -q
-size           -s
-strict         -st
-swsurface      -sw
-tek            -t
-version        -v

Parameters for BASIC Programs
-----------------------------
The interpreter assumes that any unrecognised options are meant to be for
the BASIC program and ignores them.


Running Programs
~~~~~~~~~~~~~~~~
The name of the program to run can be specified on the command line. If no
name is given, the interpreter starts with a '>' prompt. Programs can be
loaded, edited and run from here. Briefly, the commands to use are as
follows:

QUIT [<exit code>]
Leaves the interpreter.  If an exit code is supplied, this is returned to
the operating system where supported. Default is 0.

LOAD <filename>
Load program <filename> into the BASIC workspace.

SAVE <filename>
Save the program in the BASIC workspace in file <filename>.

RUN
Run the program.

LIST
LIST <line number>
LIST <line number> , <line number>
The first version lists the entire program. The second one lists just the
line supplied. The third lists lines with line numbers in the range given.

EDIT
This transfers the program in memory to a text editor where it can be more
easily edited. The program is reloaded when the editor is quitted.

EDIT <line number>
This copies the line specified to the command line where it can be edited.

DELETE <line number>
DELETE <line number> , <line number>
The first version of DELETE deletes a single line from the program, line
<line number>. The second version is used to delete a block of lines. Note
that it is not possible to recover any lines deleted. 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.

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.

RENUMBER
Renumbers the lines of a program.

NEW
Discard the program in the BASIC workspace.
WARNING: Unlike the Acorn interpreter, OLD cannot be used to retrieve a
program discarded with NEW.

Editing Programs
----------------
Any BASIC statement typed in without a line number is executed immediately.

BASIC statements typed in which start with a line number are either added to
the program or replace the line if the line number duplicates ones already
in the program.

The 'EDIT' command can be used to transfer a program into a text editor
where it can be edited more easily.

The file 'basic' contains more details of these commands and others as well
as information on BASIC V/VI.


Programs and Libraries
~~~~~~~~~~~~~~~~~~~~~~

Loading and Saving Programs
---------------------------
The interpreter can read BASIC programs that have been saved as plain text
or tokenised using Acorn BASIC or Russell BASIC tokens. It always stores
them as plain text. The reasons for working with text files are that it is
not a large overhead to tokenise and expand programs, it is more portable
and it allows programs to be edited with any text editor.
 
Line numbers can be left out when creating a program in a text editor. The
interpreter will add them when it reads the program. The line numbers added
start at 1 and go up by 1 so that the line numbers given in error messages
match up with the lines of the program in a text editor.
 
One feature of the interpreter is that it notes the name of the file on a
'LOAD' command and uses that name if the 'SAVE' command is used without
specifying a filename. The interpreter also supports the case where the
filename is supplied on the first line of the program. This take precedence
over the name saved from the 'LOAD' command.

Libraries
---------
The interpreter supports libraries of procedures and functions that can be
loaded using either the 'INSTALL' command or the 'LIBRARY' statement in a
program. Those loaded via the 'INSTALL' command will be permanently loaded
and are available until the run of the interpreter finishes. The command
line option '-lib' can be used to specify libraries that will be 'INSTALL'ed
when the interpreter starts. Libraries loaded by the 'LIBRARY' statement are
read at the time the statement is encountered and will be discarded when a
further RUN statement is issued, when NEW or CLEAR are used or when the
program is edited. Effectively they are only available when a BASIC program
is running.
Examples:

        INSTALL "catlib"

        LIBRARY "doglib"

Libraries loaded using 'INSTALL' cannot be discarded. However the same
library can be loaded via 'LIBRARY' and it will effectively take precedence
as libraries loaded this way are searched first.

Libraries can be held as plain text, with or without line numbers, or can be
tokenised.

Local Variables in Libraries
----------------------------
It is possible for libraries to have variables and arrays that are private
to that library. This is an extension to BASIC V/VI. These are covered in
more detail below.


Differences Between Matrix Brandy and Acorn's Interpreter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Matrix Brandy is compatible with the Acorn interpreter and should produce
the same results as the Acorn one. However perfect compatibility cannot be
achieved for a number of reasons, for example, the lack of graphic commands
in some versions of the program greatly limits which programs will work.
There are also some enhancements that could lead to incompatibilites, for
example, Brandy allows strings to be up to 65536 characters long compared to
the Acorn interpreter's limit of 255. The list of differences are as
follows:

1)  The SDL build implemention supports a subset of the graphics commands
    and some sound.
2)  Brandy has no support for machine code programs. It does not support
    either the 'CALL' statement nor the 'USR' function (except for a limited
    number of calls to BBC-style OS interfaces, notably OSBYTE and OSWORD).
    The built-in assembler has not been implemented.
3)  The 'APPEND' command has not been implemented.
4)  The 'OVERLAY' statement has not been implemented.
5)  INKEY(-128) to INKEY(-255) are not implemented (and were only
    implemented on the original 6502 MOS). While INKEY(-1) to INKEY(-127)
    aim to match the Acorn keynumbers as closely as possible, there are
    inevitably a small handful of differences due to physical keyboard
    hardware differences.
6)  Not all of the VDU commands have been implemented.
7)  'PRINT' leaves something to be desired.
8)  The TRACE option 'TRACE STEP' has not been implemented yet.
9)  A new TRACE option 'TRACE VDU' has been added, this redirects TRACE
    output to the controlling terminal.
10) Some 'LISTO' options have not been implemented yet.
11) The 'END=' version of the END statement is not supported.
12) Brandy behaves differently to the Acorn interpreter after an error when
    the program contains ON ERROR or ON ERROR LOCAL statements to trap
    errors.
13) OLD is not implemented.
14) Strict mode may cause a program to report an error that would otherwise
    be ignored, and would typically indicate a bug in the BASIC program.

The following differences only apply on non-RISC OS builds:
15) Support of the 'SYS' statement is minimal.
16) Cursor editing is not available. A line editor is available in its
    place.
17) EXIT <FOR|REPEAT|WHILE> from BB4W, BBCSDL and BBCTTY allow for
    immediately breaking out of a loop.

The major omissions in the versions of the interpreter are some graphics.
The built-in assembler and support for machine code programs are missing
too. Apart from that, the interpreter is essentially a full implementation
of the Acorn interpreter.

The interpreter has the following extensions:

1)  Strings can be up to 65536 characters long.
2)  Statements can be up to 1024 characters long.
3)  Libraries can have their own private variables.
4)  The OSCLI statement has been extended to allow the output from operating
    system commands to captured.
5)  (If enabled with the -lck option or SYS"Brandy_AllowLowercase",1)
    The case of commands such as 'LIST' and 'RUN' is ignored, so 'LIST'
    could be entered as 'list' or 'List'. The downside is that variable
    names that are the lower case equivalents of commands will now be seen
    as commands, something that seems to happen all too frequently.
6)  There is a new pseudo-variable 'FILEPATH$' that gives a list of
    directories to be searched when loading programs and libraries (see the
    section on this below).
7)  There are two functions for dealing with command line parameters, 'ARGC'
    and 'ARGV$' (see the section below).
8)  There are two new string functions, 'VERIFY' and 'XLATE$' (see the
    section below).
9)  'NEW' can be followed by a parameter, the new size of the BASIC
    workspace. This allows it to be changed from the default of 64M (see
    section on this below).
10) The 'RUN' command can be followed by the name of a program to run. It
    behaves just like the statement 'CHAIN', as with Z80, 80x86 and PDP11
    BASICs.
11) The 'RUN' command can also be followed by a line number to start program
    execution at that line.
12) 'TRACE GOTO' prints out the source and destination line numbers of any
    branches in the program.
13) 'TRACE VDU' redirects trace output to the controlling terminal's stderr
    output stream.
14) 'TRACE PROC' shows returns from procedures and functions as well as when
    they are called.
15) Individual TRACE options may be turned off and on, for example,
    'TRACE PROC OFF' will turn off the only the procedure trace and leave
    any other running.
16) There is an extra 'LISTO' option, 32. When this option is in effect,
    listing of a program pauses every twenty lines with the prompt
    '-- more --'. Press the space bar to show the next twenty lines,
    'return' to print just the next line or the 'Escape' key to stop the
    command.
17) 'LISTO' can be used as a function to find out the current setting of
    'listo'.
18) There are a couple of extra 'LIST' commands. 'LISTB' dumps memory in
    byte form between the two addresses specified. 'LISTW' is the same, but
    dumps memory as words. These were added for debugging but will probably
    be left in.
19) The 'EDIT' command on its own invokes a text editor to edit the program.
    Under Linux and NetBSD it calls 'vi' and currently does not work under
    Windows.
20) 'EDIT' followed by a line number allows that line to be edited using the
    built-in line editor.
21) When a program is loaded via a 'LOAD' command the name of the file is
    kept and saving the program using the 'SAVE' command with no argument
    will save the program using that name.
22) Programs are always saved as plain text.
23) The latest extended versions of COLOUR, GCOL, MODE and DIM are
    supported. VDU can also be used as a function to read RISC OS mode
    variables. COLOUR can also be used as a function to return a number that
    represents the closest match to the colour whose colour components were
    passed to the function.
24) Under RISC OS on the Risc PC or later, the 32-bit builds use a Dynamic
    Area rather than the WimpSlot for workspace, so BASIC's workspace can
    be as large as the available memory.
25) 'DIM' allows a byte array or numeric array to be created "off-heap", in
    a separately allocated memory pool.

There is quite a list here but really apart from the longer maximum string
and statement lengths, local variables in libraries and the change to 'NEW',
most of these are really cosmetic changes.

Local Variables in Libraries
----------------------------
Libraries can have their own private variables and arrays. The variables are
only accessible in the library in which they were declared.

The LIBRARY LOCAL statement is used to declare the variables. The syntax 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.

FILEPATH$
---------
This is an extra pseudo variable. It gives a list of directory names that
the interpreter will search when looking for programs and libraries. The
names are separated by commas with no intervening blanks or other white
space characters, for example:

        FILEPATH$="/home/dave,/usr/local/basic/lib"

The format of the directory names is operating system-dependent and the
program assumes that they are correct.

FILEPATH$ can be treated like any other string variable except that only the
'=' assignment operator is allowed, thus:

        FILEPATH$="/usr/local/basic/lib"

is fine but:

        FILEPATH$+=",/usr/local/lib"

is not supported and will give an error.

The interpreter first of all tries to find the program or library using the
name as supplied. If it cannot find it and the name is just the name of a
file, that is, it does not contain any directories, it then looks in each of
the directories given by FILEPATH$ until either it finds the file or it
reaches the end of the list. If the file can be found, the name of the file
as far as the interpreter is concerned is the name as orginally supplied
with the name of the directory in which it was found prepended to it, for
example:

        load "earthworks"

If this program was found in the directory '/home/dave' the name of the
program would show up as '/home/dave/earthworks' in the output from 'help'.
Saving the program without specifying a new file name would write to the
file '/home/dave/earthworks'.

As FILEPATH$ is a pseudo variable, its value is not affected by CLEAR or
NEW. The initial value of FILEPATH$ can be set using the command line option
'-path'.

The main purpose of FILEPATH$ is to provide a search path for libraries but
it is also used when looking for programs. It would be useful here for
'CHAIN'.

Use of FILEPATH$ can effectively be disabled by setting it to the empty
string, that is, by entering 'FILEPATH$=""'.

ARGC and ARGV$
--------------
These functions return parameters from the command line used to start the
interpreter. ARGC returns the number of parameters and ARGV$ the parameters
themselves.

ARGC
----
Returns the number of parameters, for example:

        count = ARGC

ARGV$
-----
Returns parameters. The syntax is:

        ARGV$ <factor>

where <factor> is a numeric value that identifies the parameter to return,
for example:

        FOR N%=1 TO ARGC
        PRINT ARGV$ N%
        NEXT

Parameter numbers are in the range 1 to the value returned by ARGC. ARGV$0
is the name of the BASIC program if it was started from the command line
otherwise it is an empty string.

XLATE$
------
This function is used to translate character strings. There are two forms of
it as follows:

        XLATE$(<string>)
        XLATE$(<string>, <translate table>)

In the first version, the function returns the string <string> converted to
lower case. Note that only ASCII characters are converted. The second
version is more powerful in that <string> is converted according to the
user-supplied translate table <translate table>. This can be either a
character string or a one dimensional string array. The effect is the same
in both cases: each character in the original string is replaced by the
corresponding character in the translate table. If the table is a string,
the character at offset 1 replaces the character with ASCII code 0, the
character at offset 2 replaces the one with ASCII code 1 and so forth. It is
not necessary for the string to be 256 characters long: any character whose
code would place it beyond the end of the string is left unchanged. The use
of a string array is more convenient in that each character is replaced by
the array entry corresponding to its ASCII code. Note that only the first
character of the string in the array is used. If the array entry contains an
empty string then the original character is left unchanged. As with the
character string translate table, the array does not have to contain 256
elements: characters whose ASCII code place them beyond the end of the array
are left unchanged.

Examples:
        PRINT XLATE$("AbCdEfGh")

        DIM table$(255)
        FOR N%=ASC"0" TO ASC"9": table$(N%)="*": NEXT
        PRINT XLATE$("abc123def456", table$())

VERIFY
------
The format of this function is as follows:

        VERIFY(<string 1>, <string 2> [, <start>])

It returns the offset (from one) of the first character in string <string 1>
that is not in string <string 2>. <start> is an optional parameter that
gives the offset at which to start the check. If all the characters in
<string 1> are present in <string 2> the function returns zero; otherwise it
returns the offset of the first bad character.

Examples:
        X% = VERIFY(a$, "0123456789")

        REPEAT A$=GET$: UNTIL VERIFY(a$, "YNyn")=0

        P%=1
        REPEAT
          P%=VERIFY("...x..x..", ".", P%)
          IF P%<>0 THEN PRINT P%
        UNTIL P%=0

If <string 1> is an empty string or the start position is greater than the
string length then the function always returns zero. If <string 2> is an
empty string then the function always returns one or the value of <start>
(if this is supplied).

ARM BBC BASIC 1.26 Extensions
-----------------------------
The following statement types have been extended in this version of the
interpreter:

        COLOUR
        DIM
        GCOL
        MODE
        VDU function

COLOUR
The new 'OF' and 'ON' parts are supported, for example:

        COLOUR OF 255,255,255 ON 0,0,0

DIM
It is now possible for local byte arrays to be created in procedures and
functions. The memory for the byte array is reclaimed when the procedure or
function ends, for example:

        DIM pointer% LOCAL 1000

GCOL
The new 'OF' and 'ON' parts are supported, for example:

        GCOL OF 0,0,0 ON 255,255,255

MODE
The extended form of MODE where the screen size to be used is supplied is
now supported. Example:

        MODE 800,600,8
        MODE "X800 Y600 C256"

VDU Function
VDU can now be used as a function to return the values of mode variables.
Example:

        PRINT "Width in characters is ";VDU 1

All of these extensions are described in the file 'basic'.

COLOUR function
This returns a value that represents the colour with the closest match in
the current screen mode to the colour with the colour components passed to
the function. The value is for use with the COLOUR OF and GCOL OF
statements.
Example:

        red = COLOUR(255, 0, 0)
        blue = COLOUR(0, 0, 255)
        COLOUR OF red ON blue

This could also be written as:

        COLOUR OF 255, 0, 0 ON 0, 0, 255

or even:

        COLOUR OF COLOUR(255, 0, 0) ON COLOUR(0, 0, 255)

The advantage of the new forms of GCOL and COLOUR are that they are mode
independent. They are more flexible than the old versions of the statements
and do away with the need for TINT.

In addition, other extensions from BB4W, BBCSDL, Basalt have been 
implemented:

GET(x,y) and GET$(x,y)
These return the character at a particular point on the screen.
Implemented for SDL builds and RISC OS.

Following on from += and -= operators, Matrix Brandy also supports:
DIV=, AND=, OR=, EOR=

A Matrix Brandy-specific extension:
OPENUP can be used to open a TCP network connection as a client.
See docs/networking.txt for full details on this extension.

Command Line Parameters
-----------------------
The interpreter assumes that any unrecognised parameter on the command line
is meant to be for the BASIC program, for example:

        brandy aprog parm1 parm2 -xyz

would be assumed to consist of the name of the program to run, aprog, and
three parameters for the program, 'parm1', 'parm2' and '-xyz'.

        brandy aprog -size 256k parm1 parm2 -xyz

would be interpreted in exactly the same way. '-size 256k' would be treated
as an option for the interpreter itself.

Beware of cases like:

        brandy aprog -size 256k parm1 -start

Here, '-start' would be seen as '-size' by the program as it only checks for
'-s' to identify '-size'.

Capturing Command Output with OSCLI
-----------------------------------
The OSCLI statement has been extended so that the output from operating
system commands can be read by the program. The syntax of the statement is
now:

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

<command> is a string expression that is the command to be issued. <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.

Example:

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

Note that there some problems still to be resolved with OSCLI ... TO. Errors
(or to be more precise, messages written to stderr) are not caught in the
DOS version of the program as DOS does not provide a way to redirect them.
They are therefore missed out.

The NEW Command
---------------
The NEW command has been extended to allow the size of the BASIC workspace
to be changed. By default, Brandy allocates half a megabyte of memory to
hold the program, variables, strings and so forth. This can be changed by
means of the 'NEW' command as follows:

        NEW <size>

where <size> is the new size of the workspace in bytes, for example:

        NEW 1000000

would set the workspace size to 1,000,000 bytes.

Note that using this command will result in the loss of the current contents
of the workspace, including any programs and libraries (except for libraries
loaded by means of the 'INSTALL' command).

The minimum size allowed is 16K bytes. The upper limit is whatever the
operating system on which the interpreter is running allows, to a limit of
4 bytes short of 2GB.

Note that the initial size of the BASIC workspace can also be set using the
command line option '-size'.

SAVE
----
There are two versions of the 'SAVE' command used to save a program. 'SAVE'
uses the current 'LISTO' setting to control the format of the program when
it is written to disk. 'SAVEO' allows the format to be more precisely
specified. The format of the SAVEO command is:

        SAVEO <format> [,<filename>]

where <format> is a number that gives the 'listo' format to be used and
<filename> is the name of the file. The name can be omitted, in which case
the name defaults to either the name used on the last 'LOAD' command or the
name given on the first line of the program. Example:

        SAVEO 10,"test"

would save a program called "test" using 'listo' option 10 (omit line
numbers and indent lines inside loops, block IF statements and so forth).

OLD
---
The OLD command is not supported.

TRACE
-----
Several changes have been made to the TRACE command.

TRACE PROC
----------
This shows both when a procedure or function is entered and when it is
exited. '==>PROCabcd' indicates that PROCabcd has been entered and
'PROCabcd-->' shows that it has been exited.

TRACE VDU
---------
The purpose of this option is to redirect all TRACE output to the
controlling terminal's stderr stream, where it can be examined without
affecting the running program's display. Use 'TRACE VDU OFF' to disable
this.

TRACE GOTO
----------
The purpose of this option is to trace program flow. It logs all jumps in
the code, showing the number of the line at which the branch occured and the
line at which execution continues. It works not just for GOTO statements but
anywhere where a branch can occur, for example, in IF statements.
Example:
consider the following code:

        100 IF X%<10 THEN
        110   PRINT"X% is less than ten"
        120   flag%=TRUE
        130 ELSE
        140   PRINT"X% is greater than or equal to ten"
        150   flag%=FALSE
        160 ENDIF
        170 PRINT flag%

If X% was set to five, the branch trace would show the following entries:

        [100->110][130->170]

and if X% was set to 25, it would look like:

        [100->140]

(Note that the program output has been omitted for clarity here).

In the first case, as X% is less that ten the condition is true and so the
program branches to line 110. When it reaches the ELSE it branches from the
ELSE to the line after the ENDIF. In the second case, as the condition is
false the program flow passes from line 100 to the line after the ELSE. As
there is no branch at the end of the ELSE part of the 'IF' and control runs
straight through to line 170, there is no trace entry.

FOR, WHILE and REPEAT loops, procedure and functions calls and returns,
GOTO, GOSUB, ON GOTO, ON GOSUB, ON PROC and RETURN statements are all traced
by this option. Note, however, that some of the trace entries are not
intuitive, for example, the line number of the start of a WHILE loop will be
that of the statement after the WHILE itself, for example:

        200 X%=7
        210 WHILE X%<10
        220   X%+=1
        230 ENDWHILE

will produce the following trace:

        [230->220][230->220]

The reason for this is tied up in the way WHILE loops work.

It is considered that this trace cuts out much of the 'noise' that results
from simply tracing line numbers.

TRACE <option> [ON | OFF]
-------------------------
Individual trace options can be turned on and off without affecting any
other settings, for example, 'TRACE PROC OFF' turns off the procedure and
function call trace. 'TRACE OFF' turns off all traces. 'TRACE <option> ON'
is provided for consistency. 'TRACE PROC' and 'TRACE PROC ON' both turn on
the procedure and function call trace.

TRACE <line number>
-------------------
This is not supported.

TRACE STEP and TRACE PROC STEP
------------------------------
These have not been implemented yet.

ON ERROR and ON ERROR LOCAL
---------------------------
ON ERROR and ON ERROR LOCAL provide a means for errors to be trapped in a
BASIC program. The documentation for these in the Acorn interpreter says
that the effect is as if there is a GOTO statement that takes you from the
point of the error to the statements after the ON ERROR clause. There is
little (if any) cleaning up after the error. Brandy differs from the Acorn
interpreter in that it tidies up before restarting at the ON ERROR
statement: LOCAL variables and arrays are reset to the state they were in at
the point of the ON ERROR and procedures and functions ended cleanly. The
intention is to provide something closer to exception handling than what the
Acorn interpreter has.

EDIT
----
This is not available on RISC OS.

The EDIT command loads the BASIC program into a text editor. The program is
reloaded by the interpreter when leaving the editor. The editor used by
default varies from operating system to operating system as follows:

Linux           vi
NetBSD          vi
Windows         (not working)

It is possible to override which editor the program uses by means of an
environment variable. Under Linux and NetBSD it looks for the standard
'EDITOR' environment variable. The DOS version checks for 'EDITOR'. Care
should be taken with DOS to choose an editor that runs under DOS and not
Windows due to the way in which DOS/Windows invokes the editor. (The editor
is started as a separate program from the interpreter and the interpreter
itself continues to run rather than being suspended until the editor has
finished.)

Unless the BASIC program contains statements such as GOTO that reference
line numbers, they can be completely ignored in a text editor. Lines can be
added without line numbers or moved around without any problem. The lines of
the BASIC program will be renumbered when the program is reloaded by the
interpreter.

EDITO
-----
There is a variation on the EDIT command, EDITO, that affects how the
program is formatted when it is passed to the editor. The command syntax is:

        EDITO <value>

where <value> controls how the program will be formatted. This takes the
same values as 'LISTO' and it has the same effect. EDITO allows, for
example, a program to be passed to the editor without line numbers.
'EDITO 8' is the command to use here. If EDIT is used, the program is
formatted according to the current 'LISTO' setting. EDITO otherwise works in
the same way as EDIT.

Line Editor
-----------
The Linux, NetBSD and Windows versions of the interpreter have a simple
built-in line editor. Apart from allowing input lines to be edited, there is
also a command line history feature that allows the last twenty or so lines
entered to be recalled. The editing commands are:

LEFT      or Ctrl-B     Move left one character
RIGHT     or Ctrl-F     Move right one character
HOME      or Ctrl-A     Go to start of line
END       or Ctrl-E     Go to end of line
DELETE    or Ctrl-D     Delete right, deleting character under cursor
BACKSPACE or Ctrl-H     Delete left, deleting character to left of cursor
             Ctrl-K     Delete from cursor to end of line
             Ctrl-U     Delete from cursor to start of line
INSERT                  Toggle between 'insert' and 'overwrite' mode
UP        or CTRL-P     Go to previous entry in the command line history
DOWN      or CTRL-N     Go to next entry in the command line history
RETURN    or CTRL-M     Finish editing
             CTRL-J     Finish editing, as with RETURN/CTRL-M
ESCAPE                  Abort editing

The aim is to provide both DOS and Unix (emacs) style editing.

The 'Escape' Key
----------------
In builds other than SDL, the 'Escape' key is not the 'Esc' key but
Control-C, that is, to break into a program press the keys 'Ctrl' and 'C' at
the same time. In graphical SDL builds, the 'Escape' key works as normal.


Identifying the Environment Under Which Brandy is Running
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are three things a program can check to figure out what operating
system is it running under:

1)  Check the contents of !PAGE. If this is set to &D7C1C7C5 then the BASIC
    program is running under Brandy. This value is a constant. Other BASIC
    interpreters store a different value there, for example, ?PAGE on the
    Acorn BASICs returns &0D.

2)  Check what INKEY -256 returns. This has been the documented way of
    checking the OS version since the first version of RISC OS. The values
    returned are:

        &A0     Arthur 1.2
        &A1     RISC OS 2.00
        &A2     RISC OS 2.01
        &A3     RISC OS 3.00
        &A4     RISC OS 3.10 and 3.11
        &A5     RISC OS 3.50
        &A6     RISC OS 3.60
        &A7     RISC OS 3.70 and 3.71
        &A8     RISC OS 4.00, 4.01, 4.02 and 4.03
        &A9     RISC OS 4.32 to 4.37
        &AA     RISC OS 5

    On all platforms including RISC OS, Matrix Brandy returns &4D (ASC"M").

    Older versions of Brandy (and Matrix Brandy older than 1.22.6) added the
    following:

        &F5     Amiga
        &F6     OpenBSD
        &F7     FreeBSD
        &F8     MACOS X
        &F9     Linux
        &FA     DOS with DJGPP DOS extender
        &FB     Beos
        &FC     Windows 32
        &FE     NetBSD

    Matrix Brandy can obtain this via the SYS "Brandy_Platform" call,
    with the above values in the R5 response.

    Other values might be added to this list for other operating systems.
    Traditionally, this identified the *platform* the program is running on,
    not the interpreter. For example, ARM BASIC could be running on a BBC
    second processor, so INKEY-256 could return &FE.  However, there is
    no other reliable way to ascertain whether the interpreter in use is
    ARM BBC BASIC or Matrix Brandy.

    This is open to interpretation, thus Matrix Brandy, along with Richard
    Russell's BBC BASIC for Windows and BBC BASIC for SDL 2.0, have chosen
    to interpret this platform specifier to be a MOS version (or emulation)
    identifier. For reference, BB4W returns &57 (ASC"W"), BBSDL from
    assembly source returns &53 (ASC"S") and from C source returns &73
    (ASC"s"). (Returning &4D on RISC OS stretches this a bit, but allows a
    program to accurately identify Matrix Brandy.)

    To reliably identify Matrix Brandy as of V1.22.12 with suitable
    capabilities for a program that requires a graphical output, you can use
    the following:

        graphics%=0
        IF INKEY(-256)=&4D THEN SYS "Brandy_Platform" TO ,,,graphics%
        IF graphics% = 0 THEN ERROR 0,"This program requires Matrix Brandy
           BASIC with graphics capability".
        REM We got here, so we're good to go.

    Note that Matrix Brandy on RISC OS intercepts the OS_SWINumberFromString
    call to be able to recognise its own internal Brandy_* calls, which use
    SWI numbers which aren't officially legal on RISC OS to ensure they
    don't trample on "real" SWI calls.

3)  The hardware type and general environment type can be found by checking
    what is returned by OS_Byte 0. The USR function and CALL statement are
    not supported except in one special case, to make calls to a subset of
    BBC Micro MOS calls. The following code can be used:

        A% = 0: X% = 1: result% = USR &FFF4
        version% = (result% DIV 256) AND 255

    version% will contain one of the following values:

        6       Acorn hardware (RiscPC, A7000 and so forth)
        8       Unix-type OS
        32      PC (DOS and Windows)

    Again, this list might be extended. Again, not that this tells you the
    *platform* the program is running on, not the interpreter. For example,
    Brandy could be running on RISC OS so OSBYTE 0 would return 6, ARM BASIC
    could be running on a BBC, so OSBYTE 0 would return 0-5.

    In Matrix Brandy, the following may also be used:

        SYS "OS_Byte",0,1 TO ,version%

Determining the *interpreter* that is running, as opposed to the platform
the interpreter is running on, is often more complicated and fiddly. In this
case, Matrix Brandy always returns 77 to INKEY(-256).


I/O Redirection
~~~~~~~~~~~~~~~
Under RISC OS, NetBSD and Linux it is possible to use the operating system's
I/O redirection facilities to take input from and write output to a file
rather than use the keyboard and screen respectively. Under NetBSD, for
example, commands could be taken from a file thus:

        brandy <command.list

Or read from one file with output going to a second file using:

        brandy <command.list >output.file

Under RISC OS these would be:

        brandy { < command.list }

and

        brandy { < command.list > output.file }

Under NetBSD and Linux in the text builds, redirecting output to a file
disables all of the VDU commands except for VDU 7, 8, 9, 10, 13 and 27. The
interpreter flags an error if any VDU command apart from the ones listed is
used unless the command line flag '-ignore' is used, in which case it is
just ignored. The reason for this is to make the program only write plain
text to the file. Similarly, redirecting input disables the functions GET
and INKEY as well as the command line editing and recall features.

The current Windows version of the program does not support I/O redirection
at all.

When input redirection is used, each line from the file is read and executed
at Brandy's command line. These can be commands to load and run programs or
BASIC statements. Within the limitations of what can be run as a single
statement from the command line, entire BASIC programs can be run this way.

One useful command is 'QUIT', which can be used to finish the run of the
interpreter. The run is also stopped if the end of the file is reached.

An example might help here. Consider the following:

        LOAD"examples/sieve"
        RUN
        LOAD"examples/hex"
        RUN
        IF X%=10 THEN QUIT
        RUN
        QUIT 100

If this is saved in a file (for example, command.bbc), then typing:

        brandy <command.bbc

would run the interpreter. It would read each line of the file and execute
it. Note how the IF statement is used to end the run of the interpreter
before the end of the file is reached because some condition is true. It
should not be forgotten that after running a program, all of its variables
are still available until it is run again or another program is loaded. At
the end QUIT is used to halt the run of the interpreter and return a status
code of 100 to the operating system. (The interpreter normally returns a
status code of 0.)


Using BASIC as a Script Language Under NetBSD and Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
BASIC is not really designed for use as a script language but it can be used
in this way under NetBSD and Linux. If the first line of a BASIC program
contains the name of the interpreter and the file containing the BASIC
program is made executable, the interpreter will automatically be used to
run the program, for example, conside the following program:

        #!/usr/local/bin/sbrandy
        PROCprint
        QUIT
        :
        DEF PROCprint
        PRINT "Hello"
        ENDPROC

If this is saved in a file (called, for example, 'hello.bbc') and the file
is made executable with the command:

        chmod +x hello.bbc

then typing:

        hello.bbc

will invoke sbrandy and pass the name of the program (hello.bbc) to it.
Brandy ignores the first line as it starts with '#!' but reads the rest of
the program and runs it. Note the use of the QUIT command to exit from the
interpreter once the BASIC program has finished.

One important point to note here is that the example assumes that there is a
copy of the Brandy 'sbrandy' text-mode build in the directory
/usr/local/bin.

Using Brandy in this way is different to I/O redirection. Here, the
interpreter is being invoked with a program. Using input redirection, Brandy
is passed a string of commands that it executes at the command line.

When used in this way, especially when processing files in a typical UNIX
fashion, usually the 'sbrandy' simple text mode interpreter would be the
best choice, especially if run from remote non-interactive SSH sessions or
cron jobs.

The SYS Statement
~~~~~~~~~~~~~~~~~
The SYS statement is used to make calls to the operating system on machines
that run RISC OS. Currently a small handful of RISC OS SWI calls are
emulated by Matrix Brandy. It is also used by Matrix Brandy to obtain
information about the environment and provide tunable settings for the
interpreter.
See docs/sys-calls.txt for more details.


The '*KEY' Command
~~~~~~~~~~~~~~~~~~
A new feature in Brandy 1.16 is that it implements the RISC OS '*KEY'
command to allow strings to be assigned to function keys. This is an
operating system command under RISC OS that is implemented by the
interpreter's MOS interface layer. The command is issued using OSCLI in the
normal way. The format is:

        *KEY <key number> <string>

where <key> is the function key number in the range 0 to 15 and <string> is
the string assigned to that key. Pressing that function key will insert the
string into the keyboard buffer, for example:

        OSCLI "KEY 3 run"

will assign the string "run" to function key 3.

There is a simple escape mechanism to allow control characters to be
included in the string. This is of the form:

        |<letter>

where <letter> is a letter.

The escape sequence '|m' is used to represent a 'newline' character, so:

        OSCLI "KEY 3 run|m"

will set up function key 3 to insert "run" and a newline character into the
keyboard buffer, so that pressing F3 will issue the command.

The string can be enclosed in double quote if desired, for example:

        OSCLI "KEY 4 ""     """: REM Insert five blanks
        or
        *KEY 4 "     "

There is a command line option that can be used to tell the program to pass
all commands to the underlying operating system rather than check them to
see if they are RISC OS commands emulated by the interpreter. This is
'-nostar'. (TBA: Russell BASICs use OSCLI "**....")

There is a complamentary *SHOW command that will display the current
function key definition for a single <key number> or all keys.


Performance
~~~~~~~~~~~
The Acorn ARM BASIC interpreter is written in ARM assembler. Brandy is in C
and there is therefore no chance that it will come remotely close to the
Acorn interpreter in terms of speed. The RISC OS version, for example, runs
between two and five times slower when working with integers and is up to
twelve times slower when floating point numbers are used extensively. That
said, the performance is quite respectable on a faster processor.


Important Error Messages
~~~~~~~~~~~~~~~~~~~~~~~~
Attention should be drawn to three of the error messages that the
interpreter can produce:

The interpreter has gone wrong at line <x> in <y>

This indicates that the interpreter has lost the plot. It says that there is
possibly something wrong with the BASIC program in memory but the more
likely cause is that the interpreter has run across a token that either has
an illegal value or that should not be encountered in the context in which
it was found. In short there is almost certainly a logic error in the
interpreter. <x> and <y> give the line number and name of the module of the
source code of the interpreter at which the problem was detected.

Unsupported BASIC V/VI feature found
Unsupported BASIC V/VI statement type found

The statement contains something that is not supported by this version of
the interpreter. The most likely culprit is a graphics or sound statement.
(It might be possible to make the program run by using the command line
option '-ignore'. This tells the intepreter to ignore 'cosmetic' unsupported
features, such as changing the screen colours.)

These are regarded as fatal errors and cannot be trapped by means of 'ON
ERROR'.


Known Problems
~~~~~~~~~~~~~~
There are no major known bugs in the program but there are a few minor
issues as follows:

1)      'PRINT' could be better implemented. The way in which floating point
        numbers are output could be better.

2)      If an error occurs when renumbering the lines of a program when the
        program is being loaded, the line number of the line in error is not
        listed. The reason is that 'top' has not been updated at this point
        and so searching for the line fails. (Effectively there is no
        program in memory yet as far as the interpreter is concerned.)

3)      Under Linux and NetBSD in the text mode builds, pressing Ctrl-C when
        a program is waiting for input should abort the BASIC program
        immediately but at the moment another character has to be typed
        after pressing Ctrl-C.


Miscellaneous Comments
~~~~~~~~~~~~~~~~~~~~~~
Some miscellaneous comments:

TIME    This function always starts from zero when Brandy starts and is
        therefore useless as a way of seeding the random number generator,
        that is, RND(-TIME) will not give the desired result.

TIME=   This is supported.

TIME$=  This is ignored.

MID$()= There is a difference between Brandy's and Acorn BASIC's
        implementation of 'MID$()='. In Acorn's interpreter, if the starting
        position exceeds the maximum length of a string (255 characters) the
        start of string is overwritten. In Brandy, nothing is changed in the
        original string if the starting position of the new string exceeds
        the length of the original string.

RIGHT$  Brandy does not precisely emulate the BASIC RIGHT$ function. For
        small negative values of the string length Acorn BASIC returns a
        null string but for large negative values it returns the original
        string. 'RIGHT$(A$,-33024)' returns a null string but
        'RIGHT$(A$,-33025)' returns the value of A$. Brandy always returns
        a null string if the length is negative.

Block IF Statements (prior to Matrix Brandy V1.23.2)
        There was what looked like a bug in Brandy at first glance involving
        block IF statements. The following program behaved differently under
        the Acorn interpreter and Brandy:

        X%=10
        IF X%=1 THENREM X is 1
        PRINT"X is 1"
        ELSE
        PRINT"Hello X is ";X%
        ENDIF

        The Acorn interpreter prints 'X is 1' but Brandy prints 'Hello X is
        10'. The reason for this is that Brandy always sees the IF statement
        as a block IF. The REM statement is ignored as programs are always
        run in a 'crunched' form therefore as there is nothing after the
        'THEN' the statement is identified as a block IF. In the case of the
        Acorn interpreter, the 'THEN' is not at the end of the line and it
        is taken as a single line IF.

        If the program is crunched in the Acorn interpreter by typing
        'CRUNCH 31' its behaviour changes. It now prints 'Hello X is 10',
        that is, the IF statement is now seen as a block IF as the REM
        statement has been discarded.

        Thus, Brandy runs programs in a crunched form.

        As of Matrix Brandy 1.23.2, this is NO LONGER the case, and
        following the principle of least surprise to the user, this
        behaviour has been corrected.

Floating Point Number Formats
        There is an incompatibility between the versions of the program that
        run on ARM processors and those that run on, for example, a X86,
        that affects floating point numbers. A file containing floating
        point numbers written on an ARM processor using PRINT# cannot be
        read on a processor with a X86 via INPUT# as the format in which the
        numbers are written to the file is different. On a ARM processor,
        eight byte floating point numbers are held in the order
        'aa bb cc dd ee ff gg hh' but on a X86 they are in the order
        'ee ff gg hh aa bb cc dd'. Whilst this is a minor issue, it might
        cause problems. It will be resolved ina later version of the
        program.


Conclusion
~~~~~~~~~~
It has been said that BASIC is a poor language and that nobody seriously
uses it. In my opinion Acorn's dialect, BASIC V and BASIC VI, is an
excellent one and worth looking at. It has its faults and lacks any support
for current practices such as object oriented programming. On the other hand
the language is simple and the interpreter requires no special packages or
additional libraries on the machine on which it runs. (That said, for BBC /
RISC OS style graphics on non-RISC OS systems, SDL 1.2 is required.) BASIC
V/VI is easy to use and substantial programs can be written using it. It is
good for small, one-off programs or for experimenting. It can also make
programming enjoyable again.  The text-mode versions also lend themselves
well for functioning as scripting languages in (for example) Linux.

This program is a work in progress. It seems to be quite stable but plenty
of bugs still lurk. They are many rough edges and a number of minor features
have only been partially implemented as yet. There is plenty of scope for
improvement.

Contact (Matrix Brandy fork)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If anybody has any suggestions or improvements for the program or finds any
bugs, I can be emailed at:

        mike@matrixnetwork.co.uk

Alternatively post a message on the Matrix Brandy thread on Stardot:
        https://stardot.org.uk/forums/viewtopic.php?f=63&t=15396

In addition, the Matrix Brandy GitHub page is at:
        https://github.com/stardot/MatrixBrandy