
-------------------------------------------------------------------------------

        Z X 8 1   C O R A L   B A S I C   I N T E R P R E T E R

                              version 7.0
                 copyright by Carlo Delhez, 1987 - 1992

          English manual first started 27th of September 1992
                   manual version 0.04 as of 92-12-08

-------------------------------------------------------------------------------

ZX81 Coral Basic Interpreter was first marketed by Terminal Software, Baarle
Nassau, Netherlands. The original Dutch manual is ISBN 90-6883-041-4, first
printed November 1987.

-------------------------------------------------------------------------------


INTRODUCTION

CBI is an acronym for Coral Basic Interpreter. It combines the efficiency
of a new and fast Pseudo Screen Editor with the ease of a powerful extension
of the ZX81 BASIC.

CBI provides you with a new Full Entry Editor which can be used in Line
Mode or Pseudo-Screen Mode. All the disadvantages of the (rather slow) regular
ZX81 editor have vanished, e.g. as a result of the Auto Repeat on all keys,
yet all its useful features, such as Direct Syntax Check and Pull Down Edit,
are still available! Moreover, the Full Entry Editor is completely
space-insensitive, so any computer freak can easily use a ZX81 now without
actually having to know which keys to press to obtain the various keywords.

Additionally, the ZX81 BASIC has been extended with 43 new commands and
many `old' commands have been revised for faster or better operation.
The new possibilities include:

(1) Several useful programming aids, such as automatic line numbering,
    deletion of large blocks of program lines by a single command,
    data protection against NEW, CLEAR and RUN, program renumbering,
    tracing and deceleration of program execution, etc.

(2) The possibility to use Pascal- and C-like structures, making commands
    like GOTO and GOSUB completely superfluous: Procedures with two-way
    data transport (any number of strings or numerical variables may
    be used for data exchange), conditional loop structures (DO, LOOP,
    EXIT, WHILE, UNTIL), expanded IF statement that allows for conditional
    execution of a block of program lines and also offers an ELSE condition.
    And ofcourse, all these structures may be nested at will!

(3) Efficient data manipulations by way of commands like DATA, READ and
    RESTORE; easy stack manipulations via POP, PUSH, DUP, CLR STACK.

(4) Useful applications for machine code programmers such as DPOKE, DPEEK
    and CALL, and also the unique possibility to expand the ZX81 BASIC
    even further with your own machinecode routines which may read the
    required parameters directly from BASIC.

(5) Faster and improved graphical capabilities.

Even though CBI offers so many advanced features, the actual code is only
some 5k in length and is stored above RAMtop (by default). CBI is suited
to be used with all existing ZX81 BASIC and machine code programs.
Programs written in CBI can also be used on a `normal' ZX81, provided
that you don't use the new commands in your program.


STARTING CBI

By default, the code of CBI is stored above RAMtop. Before loading the
program, you must reserve space for the code. Type the following commands
to achieve this:

                POKE 16388,8
                POKE 16389,107
                NEW

Now you can load the program:

                LOAD "CBI"

After loading, press any key to clear the ZX81. CBI can now be activated
by a call to address 27400:

                RAND USR 27400

If all goes well, the normal message 0/0 should appear (yet one line higher
than usual) and just below it a black block: the cursor. CBI is now ready
to be used.

NOTE 1 : In some cases the ZX81 may switch from CBI to its `normal'
         operating system (i.e. the K-cursor reappears). This happens for
         example after the NEW command. In such cases, CBI can be restarted
         by typing the command  RAND USR 27400  again. If this doesn't bring
         you back to the CBI cursor, type  POKE 16393,0  first, and then
         try again. If this still doesn't work, reset the ZX81 and reload
         CBI.

NOTE 2 : If you wish to restart CBI without leaving it, the command
         POKE 16393,0  must be typed. This will refresh all the system
         variables held by CBI.

NOTE 3 : As CBI is quite an extensive and advanced piece of software, it
         may still contain bugs. If you have problems with CBI or discover
         bugs, please contact me at the address at the bottom of this
         document.


THE NEW COMMANDS

In the following section, all new commands offered by CBI are summed up
alphabetically with required syntax, brief explanation of usage and - where
needed - one or more examples.

The required syntax is written down with special symbols. These are:

- bln           : boolean value (zero for false or non-zero for true);
                  a boolean value is used by conditional commands like IF.
                  example:  X<Y AND Y>100
- data_list     : a list containing any number of numerical expression and/or
                  string expressions, with successive entries separated by
                  commas (','). String expressions need to be preceeded by
                  a period ('.') as well.
                  example:  81,.("ZX"+STR$ 81),92,."CBI"
- name          : consists out of alphanumerical symbols; the first symbol
                  must be a letter (not a number).
                  example:  PROFIT89NET
- sw            : switch word; can be ON or OFF.
- swv           : switch value; can be 1 (for ON) or 0 (for OFF).
- var           : name of a numerical variable that need not be declared yet.
                  example:  OLDX
                       or:  A(10,3)
- $var          : name of a string variable that need not be declared yet.
                  example:  R$
                       or:  X$(3)
- x y z         : numerical expressions.
                  example:  127
                       or:  3*R/(2*Q*B(1)+1)
                       or:  COS(PI*H/6)
- [...|...]     : represents a choice between two possible items.
                  example: [ UNTIL | WHILE ]
- {...}         : optional part of the sytax; may - but need not - be omitted.
- {x}           : numerical expression or nothing; when no numerical expression
                  is typed by the user, the value x=0 will be assumed.


------  AUTO x STEP y  --------------------------------------------------------

Each time the cursor appears on the screen, a line number will be printed
automatically. The line number starts with value x and is incremented in
steps y. The auto-function ends when an empty line is entered (i.e. by
pressing NewLine immediately after the line number) or when the line
number exceeds 9999. AUTO also works with numerical INPUT statements (may
be used to show a default value which may be altered by the user).

Example:        AUTO 50 STEP 10         generates 50,60,70,...
                AUTO 92 STEP 9999       generates 92 only


------  BREAK sw  -------------------------------------------------------------

Enables the user to enable/disable the break key function. When the edit
mode is entered (e.g. after an error message), break is automatically enabled
again. When the break key is disabled, a program can also not be halted by
typing STOP for an INPUT value.

Example:        10 BREAK OFF
                20 DO UNTIL INKEY$="S"
                30 LOOP

This program can only be stopped by pressing "S". Note that the break key
always remains enabled during LOAD and SAVE.


------  CALL x  ---------------------------------------------------------------

Calls the machine code program at address x. CALL replaces RAND USR and
similar commands.

Example:        CALL 2602       wipes the screen (ROM routine for CLS).


------  CHAR x  ---------------------------------------------------------------

Equivalent to PRINT CHR$ x; but takes care of automatic scrolling when the
screen gets filled in CBI-mode and is suited for all characters (including
the new CBI keywords).

Example:        10 FOR K=0 TO 255
                20  CHAR K
                30 NEXT K               prints the entire character set.


------  CLR STACK  ------------------------------------------------------------

Clears the entire stack. CLR STACK should be used after having interrupted a
subroutine or a procedure by Break and you don't want to resume its execution.
This prevents unwanted `stack growth'.

Example:        10 GOSUB 30
                20 STOP
                30 CLR STACK
                40 RETURN

You'll get error 7/40 because CLR STACK deleted the return line number.


------  CURSOR x  -------------------------------------------------------------

Lets CHR$(x) act as a cursor in the CBI line editor. Use only single-position
characters (no keywords) and also no control codes (like NewLine).

Example:        CURSOR 131              gives 'half' a cursor.


------  DATA data_list  -------------------------------------------------------

Provides the data for a READ statement. It is necessary to issue a RESTORE
command at least once in the program in order that the data-pointer has a
proper value.

Example:        10 RESTORE
                20 READ N$
                30 READ NUMBER
                40 PRINT N$;NUMBER
                50 DATA ."ZX",81


------  DEF PROC name  --------------------------------------------------------

Starts the definition of a procedure named 'name'. This definition must be
ended by an END PROC statement. The procedure may be called by the command

        name{:data_list}

and in case the data_list is added, the data-pointer will be set to point to
it, so that the parameters in the list may be read by READ commands.
When a DEF PROC is encountered during execution of a program, its entire
definition block will be skipped (i.e. not executed). Procedure definitions
may be nested, but this is not advised. DEF PROC should not be used as a
direct command.

Example:        10 DEF PROC ENIGMA
                20  READ X$
                30  FOR K=1 TO LEN X$
                40   LET X$=X$(2*K-1)+X$
                50  NEXT K
                60 END PROC .X$( TO LEN X$/2)
                65
                70 ENIGMA:."DESREVER"
                80 READ E$
                90 PRINT E$


------  DELETE x TO y  --------------------------------------------------------

Removes all the lines with number x through y from the program. Neither line x
nor line y need actually exist. DELETE may only be used as a direct command.

Example:        DELETE 0 TO 9999        deletes entire program


------  DO { [UNTIL|WHILE] bln }  ---------------------------------------------

The DO command indicates the beginning of a (conditional) loop structure,
which has to be ended by a matching LOOP command. The three possible
structures are:

        DO           ... LOOP   : unconditional (infinite) loop
        DO UNTIL bln ... LOOP   : repeat until bln=true (1)
        DO WHILE bln ... LOOP   : repeat while bln=true (1)

It is possible to leap out of each of these three structures by way of an
EXIT command within the loop. The DO...LOOP structures may be nested at will.

Example:        10 INPUT X
                20 LET Y=X
                30 DO UNTIL Y*Y=X
                40  LET Y0=Y
                50  LET Y=(Y+X/Y)/2
                60  IF Y0=Y THEN EXIT
                70  PRINT "SQR(";X;")=";Y
                80 LOOP


------  DPEEK var,x  ----------------------------------------------------------

Double peek (word value), equivalent to the more cumbersome command:

        LET var=PEEK x+256*PEEK (x+1)

Example:        DPEEK DF,16396          lets DF point to the display file


------  DPOKE x,y  ------------------------------------------------------------

Double poke (word value), equivalent to the more cumbersome set of commands:

        POKE x,y-256*INT (y/256)
        POKE x+1,INT (y/256)

Example:        DPOKE 32734,DF+1

has the effect of HOME (also see example at DPEEK for definition of DF).
A number that has been stored by DPOKE can be read by DPEEK and vice versa.


------  DRAW TO x,y  ----------------------------------------------------------

Draws the best possible line from the last plot position to position (x,y).
Note that a line drawn from (a,b) to (c,d) is not exactly the same as a line
drawn from (c,d) to (a,b). For wiping a line drawn by DRAW, UNDRAW must be
applied in the same direction.

Example:        PLOT 0,0
                DRAW TO 63,43           draws a line across the screen


------  DUP var  --------------------------------------------------------------

Copies the value of the top element of the stack into variable var. The stack
itself remains unaltered.

Example:        10 DEF PROC WHERE
                20  DUP RT
                30  PRINT "CALLED FROM ";RT
                40 END PROC
                80 WHERE


------  EDIT x  ---------------------------------------------------------------

Moves line x (or the first line with a number higher than x) into the editor.
May only be used as a direct command.


------  ELSE  -----------------------------------------------------------------

To be used in combination with WHEN - see there.


------  END PROC {data_list}  -------------------------------------------------

Indicates the end of a procedure definition. When the procedure is executed
and the data_list after the END PROC is present, the data pointer will be
set to point to this data_list, so READ commands can be used to read the
data. For an example of a procedure with two-way data exchange see DEF PROC.


------  END WHEN  -------------------------------------------------------------

Indicates the end of a WHEN structure - see WHEN for more details.


------  ERR MSGS sw  ----------------------------------------------------------

When ERRor MeSsaGeS are on, all error messages will be briefly explained in
plain English. Unknown error messages will be commented as 'ERROR?'.

Example:        ERR MSGS ON             enable error messages
                PLOT 100,100            ... B/0 INTEGER OUT OF RANGE


------  ERROR x  --------------------------------------------------------------

When CHR$(x) is a printable, non-control, single-position character, an error
message with this character will be forced. Note that ERROR 28 has no effect.

Example:        ERROR 63                ... Z/0


------  EXIT  -----------------------------------------------------------------

Has two different applications:

 (1)  as direct command: quit CBI (not a very sensible decision!);
 (2)  in a program: jumps out of the current LOOP structure.

For an example of case (2), see the DO command.


------  HOME  -----------------------------------------------------------------

A fast and economic alternative for PRINT AT 0,0;


------  INDENT  ---------------------------------------------------------------

Gives your program a proper, professionally looking lay-out. Use INDENT to
improve the legibility and surveyability of your program; the structure of
your program is much clearer after using this command. When INDENT comes
across a structural error in your program, it will stop its task.
Note that INDENT may only be used as a direct command and sometimes results
in undefined (and unimportant) error messages.


------  LINE var,x  -----------------------------------------------------------

Puts into variable var the address where Basic line x or the first line with
a number larger than x starts. The actual command of that line is then located
at address var+4 (e.g. PRINT).

Example:        LINE FIRST,0            always FIRST=16509, start of basic area


------  LOOP  -----------------------------------------------------------------

Indicates the end of a DO...LOOP structure - see DO for an example.


------  NOSTALGIC sw  ---------------------------------------------------------

Switches between the two possible edit modes:

 (1)  NOSTALGIC ON      : N-mode (nostalgic mode)
 (2)  NOSTALGIC OFF     : CBI-mode (Coral Basic mode, screen editor)

For a more detailed description of N-mode and CBI-mode, please refer to the
section "Using the new Editor".


------  ON/OFF  ---------------------------------------------------------------

These two reserved CBI keywords can only be used in combination with other
CBI commands, viz. those that need 'sw' as parameter.

Example:        NOSTALGIC ON
                BREAK OFF


------  POP var  --------------------------------------------------------------

Takes the top element off the stack and stores its value in variable 'var'.

Example:        1000 DEF PROC ALTER
                1010  POP CRA
                1020  POP LRA
                1030  IF LRA>=1E4 THEN LET LRA=1E4
                1040  PUSH LRA
                1050  PUSH CRA
                1060 END PROC

This procedure needs to be called just before the end of another procedure
as to make sure that the latter does not cause error B when it was called
by way of a direct command.


------  PROTECT sw  -----------------------------------------------------------

Can be used to disable the commands CLEAR, RUN and NEW in order to protect
programs and variables against against accidental loss.

Example:        PROTECT ON
                LET AMOUNT=99.95
                CLEAR


------  PUSH x  ---------------------------------------------------------------

Stores the number x on top of the stack - see example at POP.


------  READ [var|$var]  ------------------------------------------------------

The READ command is an important tool for data exchange between various parts
of a program. The three different ways in which the READ command can be used
are summed up below. In general, READ takes a data item from the data list
that is specified by the current value of the data pointer. In case no
data item can be found, error G results.

 (1)  Combined with DATA and RESTORE;
      This is the most obvious usage - see DATA for an example.
 (2)  Combined with PROCedures;
      Both while calling a procedure and while returning from it, data
      can be passed - see DEF PROC and END PROC.
 (3)  By way of direct reading and/or setting of the data pointer (address
      32732). The following program is an example of this method:

                10 RAND PI
                20 RESTORE
                30 DATA 0
                40 DPOKE 32732,16514
                50 READ X
                60 PRINT X


------  RESEQ x:y,z  ----------------------------------------------------------

Resequences the program from line x onwards by renumbering this one to line y
and proceeding with steps z. The RESEQ command does not change linenumbers
after GOTO and GOSUB statements; taking into account the numerous possibilities
for structured programming offered by CBI, this seems no restriction.

Example:        RESEQ 0:100,10          renumbers program as 100,110,120,...


------  RESTORE {x}  ----------------------------------------------------------

Positions the data pointer on the first data element found in or after line x.
Note that RESTORE without number looks for the first data element in the
program. See DATA for an example.


------  TRACE swv;{x}  --------------------------------------------------------

In case swv=1 a program will be traced during running: before executing
subsequent lines of Basic, the line number will be displayed in the top
righthand corner and a small pause (in length proportional to x) will be
held. On a normal ZX81, use x=2750 for 1 second.

Example:        TRACE 1;2000            waits approx. 0.72 second


------  UNDRAW TO x,y  --------------------------------------------------------

Works just like DRAW, but uses UNPLOT instead of PLOT.


------  UNTIL/WHILE  ----------------------------------------------------------

These reserved CBI keywords can only be used in combination with a DO...LOOP
structure. See DO for an example.


------  USER x  ---------------------------------------------------------------

Probably the most interesting command for machine code programmers. The USER
command has the effect that subsequent '*' commands are redirected to the
user-definable machine code routine at address x. This allows the user to
easily expand the Basic with self-written routines. For a more detailed
explanation, please refer to the section "Brief Explanation of the USER
Command"


------  WHEN bln DO  ----------------------------------------------------------

This command is an extension of the IF command and allows for conditional
execution of program blocks (instead of just a single command). The stucture
of a WHEN block within a program is as follows:

        WHEN bln DO
         )
         > program lines to be executed when bln=true
         )
        ELSE
         )
         > program lines to be executed when bln=false
         )
        END WHEN

The ELSE with subsequent program lines is optional.
WHEN...END WHEN structures may be nested at will.

Example:        100 INPUT L$
                110 LET V$="AEIOU*"
                120 FOR N=1 TO 6
                130  WHEN L$=V$(N) AND T<6 DO
                140   PRINT L$;" IS A VOWEL"
                150   LET N=6
                160  ELSE
                170   WHEN N=6 DO
                180    PRINT L$;" IS A CONSONANT"
                190   END WHEN
                200 END WHEN

Also note that the '*' command (see USER) cannot be used after the THEN in
an IF statement. Apply a WHEN construction instead.


-------------------------------------------------------------------------------

For all questions or suggestions regarding CBI, please write to

        Carlo Delhez,
        Emmastraat 3,
        4651 BV Steenbergen,
        Netherlands.

        Internet:
        tnndcarlo@cycl.phys.tue.nl  (until May 1994)

-------------------------------------------------------------------------------


<*** End of File ***>
