ZBASIC VERSION 0.2 USER'S GUIDE, February 20, 1997
ZBASIC was created by Mikolaj Franaszczuk (phantom@pifran.ab.umd.edu)

Contents:

List of files

Section 1 - What is Zbasic?
Section 2 - What's new from version 0.1
Section 3 - How to compile a Zbasic program
            A. Command line
            B. Compiling + errors
            C. Final compiling

Section 4 - General syntax of Zbasic
            A. In general
            B. Labels
            C. Basic rules:
                a - Rule 1: spaces
                b - Rule 2: commas
                c - Rule 3: cases
                d - Rule 4: indents
                e - Rule 5: remarks
                f - Rule 6: direct assambler code
            D. Variables
                a. in general
                b. operations
                c. substitutions
                d. displaying
                e. memory

Section 5 - Command summary
Keyboard Scan codes
Final Notes

LIST OF FILES:

Included in the zip file should be the following files:

zbasic.txt - this help file
zbasic.exe - the compiler
comp.bat - batch file for easier compiling
example1.zba - Zbasic example code
example1.asm - Zbasic example code assembled into ASM form
example1.txt - Text file explaining what the example program does

SECTION 1 - What is Zbasic?
        Zbasic is a relatively high-level programming language for
the TI-85 calculator. It was created for people who wish to program
things for Zshell, but don't feel like learning the complicated
assambler for it. Zbasic is based on Basic for computers, and thus it
is very easy to learn and use. This user's guide is very detailed, however
knowledge of any type of Basic (inluding TI-Basic) would be very useful.
Of course, there are many limitations to using Zbasic instead of the
assambler. First of all, the programs take up a little (up to 30%) more
space than an equivalent program written in an optimal way in assambler,
and they run slightly slower. Also, with the limited number of commands,
it is not possible to write everything that is possible in pure assambler.
However, I think that the benefit of an easy to learn and use language,
outweight those limitations. To use Zbasic, you need: TASM, Zshell 4.0,
string85.com (it comes woth Zshell), a TI-85 calculator and of course
TI-Graph link software and hardware.

SECTION 2 - What's new from version 0.1
        For those of you that used version 0.1, here is a summary of
all the new things in version 0.2, so that you don't have to read the
entire user's manual again. Of course, besides the things mentioned below,
some minor bugs were fixed (which you propably didn't notice anyway).

a. General syntax
        Everything is pretty much the same, except for one thing. You may
now put remarks on any line, not just after commands. In other words, a whole 
line may just be a remark. Also, anything followed by the pound sign (#), is 
assumed to be directely in assambler, and will be put into the compiled
version as typed (minus the # of course).

b. New commands
        Here is a list of new commands: 
VLINE
HLINE
CONTRAST
GETCON
EXITOE

The description of each of them 
is in the "Command Summary" section, with stars next to them. 

Also, here are some commands with I am not quite done yet, and propably
do not work correctely yet. I am not providing a detailed description
for then, and please DO NOT ask me any questions about problems you are
having with them!

PAUSE - pauses the program until the user presses enter
CP - compares registers
GETR - stores a value of a register in a variable

SECTION 3 - How to compile a Zbasic program

A. Command line:

The command line suntax is: zbasic [q] (program)
For example, if you have a program called game1.zba, you would
compile it like this: zbasic game1.zba
The optional q will disable the progress display during compilation.
For example: zbasic q game1.zba
You can always just type in "zbasic", and the program will remind
you of the syntax. By the way, an ending of .zba is the standard
for zbasic program files, although any other extention can be used,
as long as it is a 3 letter extention.

B. Compilation + Errors

During the compilation, you should see a list
of commands scroll down on the screen. If an error is encountered,
Zbasic will stop compiling, and it will tell you on what line the
error is. You may than exit by pressing "e", or continue compiling by
pressing any other key. Note that if any error were encountered, at the end
an ASM file will NOT be created, and Zbasic will inform you how many errors
there were. Warning: Zbasic does not yet detect all errors, so it might create
an ASM file that is bad, and TASM might not compile it! TASM even might compile 
it, but it will hang your calculator - I am not responsible for any of that.
Also, always leave some memory free (at least 2-3 kilobytes) on your calculator
before running a program. If a compilation is succesfull, an assembled 
version of the code will be put into a file with an .asm ending. For example, 
if you were compiling game1.zba, the result will end up in game1.asm. 

C. Final compiling

You must then use TASM to compile the 
assambled code into binary format, like this:
tasm -80 -g3 -r8 -q game1.asm
Then, it must be converted into string format using string85 like this:
string85 game1
Note that neither tasm.exe nor string85.com are included in the Zbasic zip file.
You must get them on your own (string85.com should come with Zshell).
Please not that the Zbasic compiler assumes you have Zshell version 4, and
RAM version 10 (although it should work with other RAM versions). I have included
the comp.bat file in the zip package to help you easily do all the compilations
mentioned above in one step. Note that for it to work, you must have your zbasic
code file (it must end in .zba), tasm.exe, zbasic.exe, comp.bat and strig85.com 
files in the same directory. If you do simply type in: comp prog and the file
will be compiled automatically. For example, lets say you have the Zbasic code
in game1.zba. When you type in comp game1, the ASM code will turn up in game1.asm, 
and the string file ready for transfer will be in game1.85s. Note that if there
were error in the zba code or the asm code, the files mentioned will obviously
not be generated.

SECTION 4 - General syntax of Zbasic

A - In general

The command line in Zbasic has a basic format like this:
command (parameter 1) (parameter 2) (parameter 3)

The very first line of a program is what will appear in the Zshell menu after 
the name of the program. Note that it is EXACTELY what will appear, so commas, 
upper-lower case, and indents DO matter. Each program MUST have a first line 
that indicates what will appear in the Zshell menu. 

B - Labels
Labels are placed exactely like in the assambler or normal Basic: 
a line label follwed be a colon.
Example: jumphere:
You may use anything as a label, as long as there are no spaces in it, no 
quotation marks in it, and it does not begin with the word "need" 
(example - need10: would be an ILLEGAL label). 

C - Basic Rules:

a. Rule 1 (spaces)
A space (and only ONE space must seperate all the parameters and the command)
correct example: PRINT "hello" 10 30
incorrect example: PRINT   "hello   10     30

b. Rule 2 (commas)
Commas are optional so:
PRINT "hello 10 30
is the same exact thing as:
PRINT "hello", 10, 30
(You STILL need the one space between parameters though)

c. Rule 3 (cases)
There is no difference between lowercase and uppercase commands so:
PRINT "hello" 10 30
is the same exact thing as:
PrInt "hello" 10 30

d. Rule 4 (indents)
You can indent as much as you want, so:
PRINT "hello" 10 30
is the same exact thing as:
        PRINT "hello" 10 30

e. Rule 5 (remarks)
Anything after an apostrophe (') is considered a remark so:
PRINT "hello" 10 30 'This line print hello
is the same exact thing as:
PRINT "hello" 10 30
You may not put remarks after the first line (the text that will appear in
the Zshell menu).

Here is an example using all of the above rules:
PRINT "hello" 10 30
is the same exact thing as:
        PrinT "hello", 10, 30 'This prints something

f. Rule 6 (direct assambler code) 
        Anything after a pound sign (#) is assumed to be in the assambler
language, and it will be placed directely into the compiled program as such.
For example: #     ld A, 5
will put "ld A, 5" straight into the compiled code.

D - Variables:

a. in general:
There are 2 types of variables in Zbasic. You do not have to declare them
before you use them. However, I would suggest making them equal to a definite
value before you use them, since an old value might still be stored in the
memory spot assigned to the variable. One type of variable is an 8 bit (1 byte) 
variable. The other is a 16 bit (2 byte) variable. The range of the 1 byte 
is from 0 to 256. The range of the 2 byte is from 0 to about 65000. Variables 
can be any word, followed by "%" to indicate a 1 byte variable, or "!" to 
indicate a 2 byte variable. Examples:
key%
bignumber!
small%
The name of the variable can be anything as long as it does not contain
spaces or quotation marks in it. You can use variables as parameters for
any command. For example:
PRINT "hello", xcoord%, ycoord%

b. operations:
Addition and subtraction can be preformed on the variables using regular
mathematical symbols. For example:
xcoord% = xcoord% + 10
will add 10 to the current value in the variable xcoord%.
ycoord% = xcoord% - ycoord% - 20
will subtract ycoord% from xcoord% and then subtract 20 from the result
and store it in ycoord%. Note that there must be EXACTELY ONE space between
each symbol, number and variable in the command. You CANNOT mix addition
and subtraction in a single command line. For example:
xcoord% = xcoord% + ycoord% - 10
is WRONG. You must do it in two steps:
xcoord% = xcoord% + ycoord%
xcoord% = xcoord% - 10

c. substitution:
You can also do simple substitution on variables. For example:
xcoord% = 10
will set the variable xcoord% equal to 10
ycoord% = xcoord%
will make the variable ycoord% equal to the value of the variable xcoord%

d. displaying:
You may only display 2 byte variables. For example:
PRINT xcoord%, 10, 20
is WRONG
PRINT xcoord!, 10, 20
is CORRECT

Once you use a variable for the first time, as a 1 byte or 2 byte variable, it
must stay that type for the enitre program.

e. memory:
There are 50 "spots" for variables. A 1 byte variable takes up 1 "space" and
a 2 byte one takes up 2 "spaces". Therefore, you can have a maximum of:
50 1 byte variables OR
25 2 byte variables OR
30 1 byte variables and 10 2 byte variables (1 * 30 + 2 * 10 = 50)
and so on.
Be sure NEVER to exceed that 50 "space" limit!

SECTION 5 - COMMAND SUMMARY

In the syntax lines, things in parentheses are required parameters.
Things in brackets are optional ones. Commands with stars next to them
are new commands, which did not exist in version 0.1.

SCREEN:
        Sets the graphic mode for (and only for) displaying pixels and
        drawing boxes. 

        syntax: SCREEN (mode)
        example: SCREEN 1

        Values:
                1 - Black on white      
                0 - White on black

        Note: When the program starts, the screen is set to 1 by default.

END:
        Quits the program and returns to Zshell.

        syntax: END
        example: END

CLS:
        Clears the entire screen.

        syntax: CLS
        example: CLS

        Note: The screen is NOT automatically cleared when the program starts.

PRINT:
        Prints text or the value stored in a variable to the screen at given
        coordinates.

        syntax1: PRINT ("string") (x coordinate) (y coordinate)
        example1: PRINT "hello" 4 5
        syntax2: PRINT (variable) (x coordinate) (ycoordinate)
        example2: PRINT text! xc% 6

        The x and y coordinates are in screen pixels. The scrren is 128
        pixels wide and 64 pixels high. Only 2 byte variables may be
        printed to the screen. All 5 digits of th variable will be always
        displayed. For example if text! is equal to 16, on the display it
        will look like 00016.

GOTO:
        Jumps to a spot in the program specified by the label.

        syntax: GOTO (label:)
        example: GOTO jumphere:

        The label cannot contain spaces, commas or quotation marks. 

DELAY:
        Halts the program for a short period of time.

        syntax: DELAY (time)
        example: DELAY 100

        The time halted is very short. The maximum value is 255, and it
        will halt the program only for about a half a second. It is useful
        when something starts working too fast, which is sometimes the case
        with the assambler. 

GETKEY:
        Stores the code of the last key pressed into a specified variable
        and continues executing the program.

        syntax: GETKEY (variable)
        example: GETKEY key%

        It always stores the last key pressed (even if it was an hour ago), 
        not the current key, if any, being pressed. Also, the keycodes are
        NOT the ones that are used in TI-BASIC. They are the ones used for
        ZShell assembly.  
       
WAITFK:
        Halts the program and waits until a key is presses, stores the keycode
        into a specified variable, and resumes executing the program.

        syntax: WAITFK (variable)
        example: WAITFK key%

        The keycodes used are the ones for Zshell assembly code, NOT the ones
        used in TI-Basic.

PSET:
        Plots a pixel at the given coordinates.

        syntax: PSET (x coordinate) (y coordinate) [black or white]
        example: PSET x% 5 1

        The x and y coordinated are in pixels. The screen is 128 pixels wide
        and 64 pixels high. The "black or white" parameter does not have to
        be specified. If it is not, the pixel color is dependent on the current
        screen mode (see SCREEN command). If it is specified, it overrides the
        screen mode. If the "black or white" parameter is 1, the pixel plotted
        will be black, if it is 0, it will be white.

BOX:
        Draws a box on the screen and fills it.

        syntax: BOX (upper left x coordinate) (u-l y coord.) (lower right x coord.) (l-r y coord.) [black or white]
        example: BOX ux%, 30, 100, ly%

        The x and y coordinates are in pixels. The screen is 128 pixels wide
        and 64 pixels high. See the PSET command for information about the
        optional "black or white" parameter.

DO-LOOP:
        Does everything between DO and LOOP over and over again.

        syntax: DO
                (program code)
                (program code)
                ...
                LOOP
        example: DO
                 CLS
                 PRINT "hello" x% 10
                 x% = x% + 1
                 LOOP

        The DO-LOOPs can be nested in each other. Remember that unless
        you have a GOTO command that will exit to somewhere outside the loop,
        it will go on FOREVER, and you will have to take the batteries out of
        your calculator to stop it:
        good example:
        DO
                CLS
                PRINT "hello", x%, 10
                x% = x% + 1
                IF x% = 100 THEN
                        GOTO outside
                END IF
        LOOP
        outside:

FOR-NEXT:
        Repeats a set of commands a specified number of times.

        syntax: FOR (variable to increment) = (starting value) TO (ending value) [STEP] [number to increment by]
                (program code)
                (program code)
                ...
                NEXT (variable to increment)
        example: FOR a% = 1 TO 11 STEP 2
                 CLS
                 PRINT "hello", a%, a%
                 NEXT a%

        In the above example, the variable a% is initialized at 1. All the
        code between FOR and NEXT is executed. 2 is added to the variable a%
        The code between FOR and NEXT is executed again. When a% will equal
        11, the program will contine executing after the NEXT statement. 
        The "STEP 2" is not required. If it is omitted, the variable will
        be incremented by 1 every time. For statements can be nested in each
        other.

IF-END IF:
        Checks if a statement is true, and if it is, execute the code between
        IF and END IF.

        syntax: IF (value or variable 1) (either = or <>) (value or variable 2) [THEN]
                (program code)
                (program code)
                ...
                END IF
        example: IF a% = 10 THEN
                        CLS
                        PRINT "hello", 10, 20
                 END IF

        In the above example, is the value of variable a% is equal to 10,
        the screen is cleared and hello is displayed. If they are not equal,
        nothing happens. Instead of the equal sign, you can use "<>" which means
        "not equal to". The "THEN" is optional. If statements can be nested in
        each other.

* HLINE: 
        Draws a horizontal line.

        syntax: HLINE (y coordinate) (left x coordinate) (right x coordinate) [black or white]
        example: HLINE 25, 10, rx%, 1

        The x and y coordinates are in pixels. The screen is 128 pixels wide
        and 64 pixels high. See the PSET command for information about the
        optional "black or white" parameter.

* VLINE:
        Draws a vertical line.

        syntax: VLINE (x coordinate) (upper y coordinate) (lower y coordinate) [black or white]
        example: VLINE 25, 10, ly%, 0

        The x and y coordinates are in pixels. The screen is 128 pixels wide
        and 64 pixels high. See the PSET command for information about the
        optional "black or white" parameter.

* CONTRAST:
        Changes the contrast of the screen.

        syntax1: CONTRAST (contrast value)
        syntax2: CONTRAST I
        syntax3: CONTRAST D
        example: CONTRAST 20

        CONTRAST I increases the contrast by 1. CONTRAST D decreases the
        contrast by 1. The higher the contrast, the darker the screen. You
        should set the contrast to anywhere between 10 and 40, depending on
        your battery power.

* GETCON:
        Stores the current contrast in a variable.

        syntax: GETCON (variable to store in)
        example: GETCON con%

* EXITOE:
        Pauses the program, waits until the exit key is pressed and quits
        to Zshell.

        syntax: EXITOE
        example: EXITOE

KEYBOARD SCAN CODES:
        Like previously mentioned in this guide, the keyboard scancodes 
differ from those in TI-BASIC. Here is a list of the ones you should use
in Zbasic:

------------------------
|  53  52  51  50  49  |
|                      |              
|                04    |
|                      |              
|  54  55  56  02  03  |
|                      |              
|  48  40  32    01    |
|                      |              
|  47  39  31  23  15  |
|                      |              
|  46  38  30  22  14  |
|                      |              
|  45  37  29  21  13  |
|                      |              
|  44  36  28  20  12  |
|                      |              
|  43  35  27  19  11  |
|                      |              
|  42  34  26  18  10  | 
|                      |              
|  xx  33  25  17  09  |
------------------------

Keys of interest:

up    = 4
down  = 1
left  = 2
right = 3

enter = 9
2nd   = 54
exit  = 55
more  = 56

Note that there is no keycode returned for the "ON" button.

FINAL NOTES:

Take a look at example1.txt for information about the sample code
included in the zip file.
More commands and options will be coming in future versions.
You can e-mail me at phantom@pifran.ab.umd.edu
about any comments, questions, ideas or especially bugs.






        





