GABasic Manual
--------------

Introduction:

Gabasic a basic compatible compiler, created to make powerfull programs
It works in Protected Mode, allowing to use all the computer memory

This manual will teach you how to use Gabasic commands, you must have
experience in qbasic programming.

Arrays, Strings and variables
-----------------------------

This works in the same way that quickbasic, look this examples:

Dim array(10) as long, array2(20) as integer
Dim array(10) as string * 8
Dim array(20) as byte
Dim array%(20), array2&(30)
Dim var1, var%, var3 as integer, var4 as long
tvar = 1
tvar2% = 2 * 3
text$ = "Welcome"

                               Strings Commands
                               ----------------

Gabasic supports: CHR$, MID$, STR$, INKEY$, UCASE$, LCASE$

You can't use a string inside the same string, if you don't know what i mean,
take a look at this:

The string format in Gabasic is different that in qb, in Gabasic
the 4 first bytes are the size, and next is the string data, you must worry
about this only if you are going to write to the string using peek
and poke.

Qbasic  mode                                 Gabasic mode
------------                                 ------------

a$ = a$ + chr$(1)                            a$ =+ chr$(1)

a$ = chr$(0) + a$ + c$                       b$ = a$
                                             a$ = chr$(0) + b$ + c$

                                 Variables
                                 ---------

This works exactly like qb, you can use a = a + 1

* Some advantages:

    Instead of use:                                     You can use:

    a = a + 1                                              a =+ 1
    a = a -1                                               a =- 1

Both methods are allowed in Gabasic

   Operations Supported
   Math:  +, -, *,  /, \
   BITS: <<(SHL), >>(SHR), SHL, SHR, ROL, ROR, AND, XOR, OR, NOT

IF/ELSE/END IF         DO/LOOP
--------------         --------
IF

Gabasic supports If and Do, but only with one paramenter
If supports AND, but using the '&' character like

IF a = 1 & b = 2 THEN
   Print "R"
END  IF

Gabasic doesn't support OR

Select Case is not supported (yet)

                                     DO
                                     --

Gabasic doesn't support LOOP while, until.
The condition always must be next to Do
Do doesn't support &(and)
Example:

Do not while endloop = true

Loop

File Handling
-------------

To open a file use:

  OPEN {file name} FOR {mode} AS {number}

You must not use # in the file number, also, Gabasic supports math operations
in the  file number like: OPEN "gfx.dat" FOR BINARY AS lastfile - 1

To close a file use: CLOSE {file number}

  GET AND PUT

  GET: There are 2 get type:  GET, XGET

  GET

  Use:    GET {file number}, {n. of bytes to read}, {File pointer}, {Destination }
  {Bytes to read} and {File pointer} are optional.
  If you skip {Bytes to read} on a string, it will fill all the string with data (like it works in qb). You can put the data in strings, arrays, and variables

Examples:

   Get 1, 20, 2, a$ (this will read 20 bytes)
   Get 1, , a$  (this is exactly like qb)
   Get 1, 2, , a$
   Get 1, , a%

  XGET

  Use:    XGET {file number}, {n. of bytes to read}, {File pointer}, {Memory Address}

  This works in the same way as GET, the only diference is that you fill
  {Destination} with a memory address, this is very usefull.

  Example:

' This Program will read an uncompressed 256 colors tga file
' This is an example of XGet

file$ = "demo.tga"
xsize% = 0
ysize% = 0

open file$ for binary as 1
  get 1, 13, xsize%                 ; Get the sY ize
  get 1, 15, ysize%                 ; Get the X size

cls
print "Xsize: " + str$(xsize%)
print "Ysize: " + str$(ysize%)  ; Print the size
waitkey

SCREEN 13
  Dat$ = ""
  addrs = varptr(Dat$) + 4
  get 1, 1, 768 + 18, Dat$        ; Skip the Palette

  for i = Ysize% to 1 step - 1
     xget 1, xsize%, , i * 320 + 0A0000h          ; Let's put the data into de video memory
  next i

waitkey
screen 0
close 1
end

PUT: This work exactly like GET or XGET

  Use:    PUT {file number}, {n. of bytes to write}, {File pointer}, {Source}
          XPUT {file number}, {n. of bytes to write}, {File pointer}, {Source(memory address)}
  {Bytes to write} and {File pointer} are optional.

SEEK and LOF

   This works like qb:

    x = SEEK(filenumber)
    x = LOF(filenumber)

MEMORY
------

   Gabasic supports PEEK, POKE, VARPTR, SADD

   Gabasic works in pmode, so there aren't segments anymore. If you want to
   know the linear address of a segment:address memory location, use this
   formula:

   Address = Segment << 4 + Offset

INP/OUT
-------

    INP and OUT are supported

GRAPHICS
--------

    Only SCREEN 13 (320x200x256 Vga) is supported right now.
    Screen 14(640x480x256 Svga) only support pset and point.
    The following commands are supported:

    LINE x1, y1, x2, y2, color
    PSET x, y, color
    BOX x1, y1, x2, y2, color
    FILLBOX x1, y1, x2, y2, color
    VGET x1, y1, x2, y2, array
    VSPUT x, y, array
    VPUT x, y, array
    SETCLIP x1, y1, x2, y2

LIST OF  KEYWORDS (with a small description)
-----------------

GETEXEPATH$:                                Returns the exe path and name like c:\gabasic\test.exe
COMMAND$:                                   Returns the command line arguments
SETSTRING maxsize:                          Set the maximun string size
DIM name AS TYPE:                           Defines a variable, array, string
REDIM name(newsize):                        Resizes an array
CONST name = value:                         You know this
OUT/W/D port, value:                        Write data to a port
PEEK/W/D (address):                         Read data from address
POKE/W/D address, value:                    Write data to address
INP/W/D (address):                          Read data from port
MEMCOPY/W/D src, dest, times:               Copy data from one memory location to another
MEMFILL/W/D dest, times, value:             Fill one memory location with data
SETVECT interrupt, address:                 Set the interrupt address
GETVECT (interrupt):                        Get the interrupt address
OPEN name FOR BINARY AS filenumber:         You know this
CLOSE filenumber:                                    ""
GET filenumber, {bytes}, {file pointer}, dest:       "" 
XGET filenumber, {bytes}, {file pointer}, memory:    ""
PUT filenumber, {bytes}, {file pointer}, dest:       ""
XPUT filenumber, {bytes}, {file pointer}, memory:    ""
KILL name:                                    Deletes a file
SEEK (filenumber):                            Get the next write/read location
LOF (filenumber):                             Get the file size
DO condition
LOOP
FOR var = firstvalue TO lastvalue {STEP}
NEXT {var}
IF Condition
ELSE
END IF
END
GOSUB Label
GOTO  Label
RET/RETURN
PSET x, y, color:                              Writes a pixel
SCREEN mode:                                   Sets the screen mode
COLOR foreground, background                   Sets the screen color
SETCOL color, r, g, b:                         Set a color of the palette
LINE x1, y1, x2, y2, color:                    Draws a line
FILLBOX x1, y1, x2, y2, color:                 Draws a filled box
BOX x1, y1, x2, y2, color:                     Draws a box
HLINE x1, x2, y, color:                        Draws a horizontal line
VLINE y1, y2, x, color:                        Draws a vertical line
SETCLIP x1, y1, x2, y2:                        Set the clip area
SETVOFFS address:                              Set the video address(for double buffering)
VGET x1, y1, x2, y2, array():                  Gets a sprite
VPUT x, y, array():                            Put a sprite(skipping the transparent color)
VSPUT x, y, array():                           Put a solid sprite
SETTRANSCOLOR color:                           Set the transparent color to use with VPUT
PRINT text$
LOCATE y, x
CLS
SLEEP/WAITKEY:                                 Wait until a key is pressed
ASM
END ASM
EXIT FOR/DO/SUB:                               Exit from a FOR/DO/SUB Block
ASC (text$):                                   Returns the ascii code
ABS (value):                                   Returns the positive number
SGN (value):                                   Returns the 1 if > 0, 0 if = 0, -1 if < 0
LEN (text$):                                   Returns the size of a string
RND (max value):                               Returns a random number
POINT (x, y, color):                           Returns the a pixel color
VARPTR (string/array/variable)                 Gets the array/string/variable address
VAL (string$):                                 Converts a string into a number
CHR$ (number)
MID$ (text$, start, length)
INKEY$/INKEY:                                  Returns the last key pressed
TIMER(doesn't work very well)                  Get the time in hundreths of seconds
LINE INPUT  file number, dest                  Reads a data from a file, dest must be a                                                                                                                                                                                                                   string
PRINT  file number, src                        Writes data to a file
STR$ (text$)                                   Converts a number into a string
SADD (string/array/variable)                   Gets the array/string/variable address

KEYWORDS DESCRIPTION
--------------------

SETSTRING

Usage: SETSTRING maxsize

Sets the maximun size of a string


DIM
Usage: DIM name AS TYPE
           DIML name
           DIMLONG name
           DIMI name
           DIMINT name
           DIMS name
           DIMSTR name

Creates a string, array, or variable

TYPE can be:
  LONG
  INTEGER
  BYTE
  

DIML/DIMLONG define a Long variable
DIMI/DIMINT define a integer variable
DIMS/DIMSTR define a string


REDIM

Usage: REDIM name(newsize)

Change the size of an array


OUT/OUTW/OUTD *

Usage: OUT/W/D Port, Value

Write a value to a port
OUT writes a byte to the port
OUTW writes an integer value to the port
OUTD writes a long value to the port


POKE/POKEW/POKED *

Usage: POKE/W/D Address, value

Write a value to a memory address

POKEW is the integer version of POKE
POKED is the long version of POKE


MEMCOPY/W/D  *

Usage: MEMCOPY/W/D src, dest, times

MEMCOPY copies data from src to dest     a number of times

Example:
   MEMCOPYD 0A0000h, VARPTR(vscreen(0)), 16000


MEMFILL/W/D  *

Usage: MEMFILL/W/D Address, times, value

MEMFILL Fills the memory address with the value

Example:
   MEMFILL 0A0000h, 64000, 15


SETVECT

Usage: Setvect interrupt, address

SECTVECT sets the interrupt address
You can fill address with a memory address, or with a label. Use @ before
the label name.

Example:
SETVECT 09, @newhandler

END

newhandler:
  a = INP(60h)
ASM {
  IRET
} END ASM
