Instructions for !Whizz
=======================

*Please* read this file carefully before using the compiler for the first
time !!

Copyright & disclaimer
----------------------

!Whizz and all associated files are  Darren Windsor. The compiler may be
distributed freely but should be done so in whole. No fee should be charged
for its ditribution (except for a small fee for postage / handling). Please
do not alter any of the files in the compiler - if you find a bug please
email me the details.

The author assumes no liability for the loss of data arising from the use or
misuse of the software supplied.

By using the software you acknowledge this diclaimer !

Summary of use
--------------

Quick start guide - please read the 'code' requirements before compiling
anything !!

1. Load up the compiler.

2. Click on the icon bar icon with the left hand mouse button.

3. Drag your BASIC source (text) file to the window.

4. Click on 'compile'.

5. Once compilation is complete drag the save icon to a filer window to save
the object code.

6. Double click on the object code to run. (Make sure the WIMP slot is large
enough to run the file).

Code Requirements
-----------------

!Whizz will compile BASIC text files only, *NOT* tokenized BASIC (type &ffb
files). To convert a tokenized BASIC file to text load it into the BASIC
interpreter and type the following command :

    TEXTSAVEO 8,"<destination filename>"
    
This will strip the line numbers from the program (as the compiler doesn't
recognise them you *must* ensure that they are removed). This also means that
you should have no references to line numbers in your code (eg. no GOSUBS or
GOTOs).

In order to compile properly your BASIC code will need to follow certain
requirements :

1. The code must be free of errors. Unfortunately the compiler does not check
for syntax errors, missing variables, etc. You should therefore fully path
test your code using the BASIC interpreter before compiling it.

2. The run path *must* terminate with an 'END' command. (This need not be
at the end of the source file). This is very important ! Missing off the
'END' will result in the program not being compiled correctly.

3. Real (floating point) numbers are not supported so only use integers
(integer values, variables, arrays etc.) Real numbers and floating point
variable / array names should be recognised by the compiler (eg. number,
number(10)) but this hasn't been tested in a while so try and stick to
integer variables for now (eg. number%, number%(10)).

4. Any variables referenced in a procedure / function which are not global
nor local to the procedure / function should be explicitly passed. eg.
        
        DEFPROCprocedure1
        LOCAL number%
        number%=10
        PROCprocedure2
        ENDPROC
        
        DEFPROCprocedure2
        PRINT number%       : number% assumed to be a gobal variable and
                              *not* the variable under the same name in
                              'procedure1'.
        ENDPROC
        
        It should be implemented like this :
        
        DEFPROCprocedure1
        LOCAL number%
        PROCprocedure2(number%)
        ENDPROC
        
        DEFPROCprocedure2(number%)
        PRINT number%       : number% has been passed so this holds the
                              same value as in 'procedure1'. '10' would be
                              printed.
        ENDPROC
        
5. Passing 'by reference' to functions / procedures using the RETURN keyword
is not currently supported. ie. the following would not compile :

        var%=0
        PROCprocedure(var%)
        PRINT var%
        
        DEFPROCprocedure(RETURN var%)
        var%+=1
        ENDPROC
        
6. IF statements *must* be in the form of IF..THEN..[ELSE]..ENDIF constructs
and not single line statements. eg.

        *NOT* allowed :
        
                         IF a%=b% c%=3
                         
                         nor as :
                         
                         IF a%=b% THEN c%=3
                         
        It should be implemented as :
        
                         IF a%=b% THEN
                              c%=3
                         ENDIF
                         
Note that the 'IF', 'THEN' and 'ENDIF' statements are compulsory whereas the
'ELSE' statement is optional.

7. Arrays and areas of memory when DIMensioned must be of an explicit size,
specified by using *immediate integers* only. ie.

       The following is *not* allowed :

       size%=10
       x%=5
       y%=2
       buffer_size%=255

       DIM array1%(size%)
       DIM array2%(x%,y%)
       DIM array3%(10*3)
       DIM block% buffer_size%
       
       The code should be implemented as :
       
       DIM array1%(10)
       DIM array2%(5,2)
       DIM array3%(30)
       DIM block% 255
       
8. The 'Supported' file provides details on each of the BASIC commands and
how well (if at all) that each is supported by the compiler. Ensure that your
programs do not include any of the unsupported commands before attempting to
compile them. Be warned - no checking is done by the compiler to make sure
that all commands included in the source file are supported !!

Out of all the supported commands the following restrictions apply :

a. DEFFN/PROC
   ----------

Function / procedure names should not begin with 'library_routine' - these
names are reserved for the compiler's library. Remember to explicitly pass
any variables used in the function / procedure unless they are global or
local to the function / procedure.

b. PRINT
   -----

PRINT commands must not include semi-colons or TAB( commands. Use '+'
operators instead of semi-colons where possible :

       string$="Hello"
       
       PRINT "Hello ";string$       : REM Wouldn't compile
       PRINT "Hello "+string$       : REM Would compile
       
       PRINT TAB(5);"Hello"         : REM Wouldn't compile
       PRINT "     Hello"           : REM Would compile
       
c. TIME$ / TIME
   ------------
   
These can only be used to read the time, not to set it. ie.

   PRINT TIME$                      : REM Would compile
   today$=TIME$                     : REM Would compile
   PRINT TIME                       : REM Would compile
   current_time%=TIME               : REM Would compile
   
   TIME$="Thu,13 Jan 2000.18:29:41" : REM Wouldn't compile
   TIME=100                         : REM Wouldn't compile
   
d. EXT#
   ----
   
Can only be used to read the length of a file, not set it. ie.

    PRINT EXT#fhandle%              : REM Would compile
    length%=EXT#fhandle%            : REM Would compile
    
    EXT#fhandle%=100                : REM Wouldn't compile
    
e. VDU
   ---
   
';' and '|' are not supported and shouldn't be used with the command. Only
comma separated number lists should be used.

Example code
------------

Examples of each of the supported BASIC commands is included in the 'Example'
program file. I recommend that you look through this before trying to compile
your own programs. If you don't have a StrongARM machine then be prepared to
wait a long time for the example code to compile (on an ARM600 it takes
around 10 minutes ! On a StrongARM it takes about 1 minute).

As a final note please do not try and compile the compiler's !RunImage; it
uses pass by reference which isn't currently supported.