Quick Reference to GSoft BASIC 
GSoft BASIC, the FREE Version! 1.2

(This document is formatted for a monospaced font like Courier.)

Contents
--------

Programs
Statements
Functions
Variable Types and Names
Expressions
PRINT USING Format Specifiers

Programs
========

   GSoft BASIC programs consist of a series of lines.  Each line may begin with a line number, and this line number may be used as a destination point for statements that jump to another location, like GOTO.  Line numbers are optional, however.

   GSoft BASIC also supports the use of named labels for GOTO and other statements that transfer control to a specific line.  Label names follow the same rules as identifiers.  A line label must be the first item on a line; it is followed by a colon.

   Each line contains one BASIC statement, optionally followed by a colon character and another statement, and so on.

   Subroutines declared with SUB or FUNCTION, if any, appear after the main part of the BASIC program.  The main program must end with an END statement if there are subsequent SUB or FUNCTION declarations.

Statements
==========

! any-ascii-characters
----------------------

   The ! statement starts a comment.  All characters from the ! character to the end of the line are ignored.

   See also REM.

ALLOCATE '(' l-value [ ',' expression ] ')'
-------------------------------------------

   Allocates memory from the computer's memory.  l-value is set to a pointer to the allocated memory.  expression is the number of bytes of memory to reserve.  If expression is not used, enough memory is reserved for one value of the type l-value.

   See also DISPOSE, SIZEOF.

BREAK
-----

   Enters an ORCA compatible high-level language source-level debugger, breaking on the current line.

   Do not use this command unless an ORCA compatible debugger is installed!  ORCA compatible debuggers work by intercepting the 65816 COP instruction.  There is no way for GSoft BASIC to tell if a debugger is installed or not, so it will issue the COP instruction whether or not a debugger is actually present.  If there is no debugger installed, this causes the computer to crash.  While this does no actual harm, the only way to recover is to reboot.

CALL identifier [ parameter-list ]
----------------------------------

   Calls a subroutine defined by a SUB statement or a tool defined in a tool interface file.  See SUB for details.

CASE
----

   See SELECT.

CLEAR
-----

   Erases all types, variables and strings.  Variables are removed whether they were created with the DIM statement or by being used without encountering a DIM statement.

CHDIR pathname
--------------

   Changes the default prefix to pathname.

CLOSE [ '#' expression ]
------------------------

   Closes a file.

   If a file number is used, CLOSE closes the specific file specified by the expression.  If no file number is used, CLOSE closes all files that have been opened by OPEN.

   See also OPEN.

CONST identifier = expression
-----------------------------

   Creates and assigns a value to a constant that works and acts like a variable, but cannot be changed.

CONT
----

   Continues execution after a STOP or END command.

DATA any-ascii-characters
-------------------------

   Creates DATA for READ statements.  More than one piece of data can be created with a single DATA statement by separating the data with commas.

   See also READ, RESTORE.

DEF FN identifier '(' identifier [ ',' identifier ]* ')' '=' expression
-----------------------------------------------------------------------

   Creates a local function.

   Parameters and the value returned by the function can be any numeric or string type.  Types are assigned using trailing type characters, as in A$ for a string.

   When the function is called using a FN term in an expression, each parameter in the call is evaluated and assigned to the corresponding parameter variable.  The expression is then evaluated.  The expression must result in a value that is type compatible with the function name.  The expression can use constants, parameter variables, other variables that do not have the same name as a parameter, and other functions.

   Functions created with DEF FN are local to the main program or procedure in which they are created.

DIM identifier [ subscript ] [ AS type ] [ ',' identifier [ subscript ] [ AS type ] ]*
--------------------------------------------------------------------------------------

   Creates a variable.  The variable can be an array or a single value.  For arrays, a subscript is given.  The result of each expression is converted to an integer and used as the maximum subscript value for the array.  The minimum subscript value is always 0.

   If no type is given, the last character of the name determines the variable type.  Types assigned with the AS clause may be used with arrays or single values.

DISPOSE '(' l-value ')'
-----------------------

   Disposes of memory previously allocated with ALLOCATE.

   It is an error to dispose of memory using a pointer that was not assigned by ALLOCATE or to dispose of the same memory twice. BASIC cannot catch this error.  An error of this type may eventually lead to corrupted memory or a crash.

   See also ALLOCATE.

DO [ WHILE expression | UNTIL expression ]
------------------------------------------
LOOP [ WHILE expression | UNTIL expression ]
--------------------------------------------

   The DO and LOOP commands form a loop, executing all statements between them until certain conditions are met.  Conditions can be used on either or both the DO and LOOP clause, or on neither one.

   Execution begins at the DO statement.  If the statement is a DO WHILE statement, the expression is evaluated, and if it is true (any non-zero numeric value is treated as true) the statements between DO and LOOP are executed.  If the condition is false (zero is treated as false) execution continues with the first statement after the LOOP statement.

   If the DO statement is a DO UNTIL statement, the expression is evaluated, but this time the statements between DO and LOOP are evaluated if the expression is false.  If the expression is true, execution skips to the first statement after the LOOP statement.

   If the LOOP statement is eventually executed, and there is no condition, execution jumps back to the DO statement.

   If the LOOP statement is a LOOP WHILE, the expression is evaluated.  If it is true, execution jumps back to the DO statement.  If it is false, execution continues with the statement after the LOOP statement.

   If the LOOP statement is a LOOP UNTIL, the expression is evaluated.  If it is false, execution jumps back to the DO statement.  If it is true, execution continues with the statement after the LOOP statement.

ELSE
----

   See IF.

END
---

   Stops execution of a program.

   See also IF, SELECT CASE, FUNCTION, SUB, TYPE.

ERROR expression
----------------

   Behaves exactly as if a run-time error occurred.  The expression designates the error number, which can be read using the ERR function.

See also ERR, ERL.

FOR identifier '=' expression TO expression [ STEP expression ]
---------------------------------------------------------------
NEXT [ identifier ] [ ',' identifier ]*
---------------------------------------

   The FOR-NEXT loop executes a series of statements a specific number of times.

   The expressions are evaluated.  The first expression is assigned to the control variable, which is the identifier immediately after FOR.  It must be a single numeric value; arrays, record fields and pointers are not allowed.  The remaining expressions are evaluated once and the results stored.  The statements between the FOR and NEXT statements are then executed.

   When the NEXT statement is encountered, the value after STEP (or 1 if STEP is not used) is added to the loop control variable.  If the step value is positive, and the control value is less than or equal to the value of the expression after TO, execution loops to the statement after the FOR statement; otherwise, execution continues with the statement after NEXT.  If the step value is negative and the control value is greater than or equal to the expression after TO, execution loops to the statement after the FOR statement; otherwise, execution continues with the statement after NEXT.

   The NEXT statement can be used to end more than one FOR statement.  In this case, a comma is used.  Generally the loop control variables are listed, but this is not required.

FUNCTION identifier [ parameter-definition-list ] [ AS type ]
-------------------------------------------------------------
[ statement ]*
--------------
END FUNCTION
------------

   Defines a function. 

   The identifier is the name of the function, used when it is called.  This is followed by the parameter list, if any, and the type returned by the function.  The statements that appear between the FUNCTION statement and the END FUNCTION statement are executed as if they were a program, then the last value set for the function is returned to the caller.

   The parameter list consists of one or more parameter declarations separated by commas.  Each parameter declaration is a variable, optionally followed by AS and a type.  If no type is given explicitly, the type is derived from the name of the variable. For example, I% would be an integer.

   Arrays, records, pointers, strings and all numeric types are allowed as parameters. Pointers, strings and numeric types are allowed as return values.  While records and arrays cannot be returned directly, you can return pointers to either type-but insure that the value is dynamically allocated, and not a local variable!

   Inside the function, all parameters work as if they were variables preset to the value passed when the function is called.  If the function is called with the name of a variable whose type exactly matches the parameter, and the value is changed inside the function, the value of the original variable is also changed.  If the types do not match exactly, or if the function is called with an expression, or if the variable passed is surrounded by parentheses, the original value is not changed.

   Variables declared inside the function survive until the function returns, but no longer.  If the function is called again, an entirely new set of variables is allocated.  Variables from outside the function cannot be accessed from inside, except for parameters, as noted above.  Types defined in the main program are, however, available in the function as well as the program.

   The value returned by the function is set by assigning a value to the function name.  This can be done more than one time; the last value set is the one returned.  If no value is set, 0 is returned for numeric functions, a null string for strings, and a null pointer for pointers.

GET [ '#' expression ',' [ expression ] ',' ] l-value
-----------------------------------------------------

   Reads a single value from the keyboard or a disk file.

   If no file is specified, the variable must be a string.  A single character is read from the keyboard, converted to a string, and saved in the variable.  If no characters have been typed, GET waits for a key before returning.

   If a file is given, GET reads binary information from the file.  While strings are still treated as single characters, any other data type can be read, including integers, real numbers, records or pointers.

   See also PUT, INPUT.

GOSUB line-number
-----------------

   Control jumps to the first line whose number matches line-number.  line-number must be an integer constant or a named label.  When a RETURN statement is encountered, control jumps to the statement after GOSUB.

   Subroutines can be nested up to 24 levels deep.

   If GOSUB is used in a procedure, the destination line must be in the same procedure.

GOTO line-number
----------------

   Control jumps to the first line whose number matches line-number.  line-number must be an integer constant or a named label.

   If GOTO is used in a procedure, the destination line must be in the same procedure.

HCOLOR= expression
------------------

   Sets the pen color to one of the 16 colors used on the 320-mode graphics screen.  Unless they have been deliberate changed with QuickDraw II calls, the colors are:

   Number  Applesoft Color  GSoft BASIC Color
     0       black            black
     1       green            green
     2       violet           purple
     3       white            white
     4       black            dark gray
     5       orange           orange
     6       blue             blue
     7       white            red
     8                        beige
     9                        yellow
    10                        brown
    11                        light blue
    12                        lilac
    13                        Periwinkle blue
    14                        light gray
    15                        dark green

HGR
---

   Starts QuickDraw in 320 graphics mode (if it has not already been started), switches the display to the graphics screen, clears the screen to black, and sets the pen color to white.

   See HPLOT, HCOLOR=, and TEXT.

HOME
----

   Clears the text screen and places the cursor at the top left of the screen.
See also HTAB, VTAB.

HPLOT [ expression ',' expression ] [ TO expression ',' expression ]*
---------------------------------------------------------------------

   If the initial location is given, the pen is moved to that location and a single point is drawn.  If one or more TO clauses follow, lines are drawn from the previous point to the location after TO.

   See HGR and HCOLOR=. 

HTAB expression
---------------

   Sets the horizontal cursor position on the text screen.  This changes the location of the flashing input cursor and the location where the next characters will be written on the text screen.

   Columns are numbered from 1 at the left of the screen to 80 at the right.  Numbers outside this range are legal, and are converted to the closest existing screen column.

   The vertical position is not changed.

   See also CSRLIN, HOME, POS, and VTAB.

IF expression THEN statement
----------------------------

   The expression is evaluated.  If the result is not zero, the statement following THEN is executed.  If the result of the expression is zero, the statement is not executed.

IF expression GOTO line-number
------------------------------

   The expression is evaluated.  If the result is not zero, the GOTO is executed, causing processing to skip to the specified line.  If the result of the expression is zero, processing continues with the statement following the if statement.

   line-number must be an integer constant or a named label.

IF expression THEN
------------------
[ ELSE IF expression ]*
-----------------------
[ ELSE ]
--------
END IF
------

   The expression following IF is evaluated. If the result is not zero, lines between this statement and the first ELSE are executed, and all others are skipped.  If the result is zero, expressions in subsequent ELSE IF statements are evaluated, in turn, until one of them results in a non-zero value.  When a non-zero expression result is found, the statements from that expression to the following ELSE or ELSE IF are executed, and all others are skipped.

   If no expressions evaluate to non-zero, and there is an ELSE clause, the statements between ELSE and END IF are executed.  If there is no ELSE clause, no statements are executed.

INPUT [ '#' expression ',' ] [ string-expression ';' ] l-value [ ',' l-value ]*
-------------------------------------------------------------------------------

   Reads a comma-delimited value from the keyboard or a disk file.

   If string-expression appears, it is used as a prompt string.  It is written to standard output without a carriage return, then the input is read.  If no prompt string is given and input is from the keyboard, a ? character is written as a default prompt string.

   One or more values can be read with a single INPUT statement by separating the variables with commas.  These values can be any number type or a string.

   Multiple input values are separated by carriage returns or commas.  Any spaces appearing between input values are ignored.

   See also LINE INPUT.

INVERSE
-------

   Subsequent characters are printed using the inverse character set.

   See also MOUSETEXT, NORMAL.

KILL filename
-------------

   Deletes the file or directory filename.

[ LET ] l-value '=' expression
------------------------------

   The expression is evaluated, and the result stored in the location indicated by l-value.

LINE INPUT [ '#' expression ',' ] [ string-expression ';' ] l-value [ ',' l-value ]*
------------------------------------------------------------------------------------

   Works almost exactly like INPUT.  The exception is how the two handle commas.  LINE INPUT ignores them, reading all characters up to the end of a line.

   See also INPUT.

LOADLIBRARY expression
----------------------

   Loads a user tool from disk.

   expression is the tool number to load.  GSoft BASIC looks for a file with the name UserToolXXX, where XXX is the tool number.  It looks first in the local directory, which defaults to the location of the GSoft BASIC interpreter.  The local directory can be changed before using LOADLIBRARY using the CHDIR command.  If the tool is not found in the local directory, GSoft BASIC looks in the System directory at the path *:System:Tools:UserToolXXX.

   See also UNLOADLIBRARY.

LOOP
----

   See DO.

MKDIR pathname
--------------

   Creates a new directory with the name pathname.

MOUSETEXT
---------

   Subsequent characters are printed using the mouse text character set.

   See also INVERSE, NORMAL.

NAME filename AS filename
-------------------------

   Renames the file, directory or disk.  The first file name is the original file name, and the second is the new file name.

NEXT
----

   See FOR.

NORMAL
------

   Subsequent characters are printed using the normal character set.

   See also INVERSE, MOUSETEXT.

ON expression GOTO line-number [ ',' line-number ]*
---------------------------------------------------

   The expression is evaluated and truncated to an integer.  Numbering from one, the corresponding line number is selected from the list of line numbers, and execution jumps to that line.

   If there is no corresponding line number, execution continues with the statement after the ON-GOTO statement.

ON expression GOSUB line-number [ ',' line-number ]*
----------------------------------------------------

   The expression is evaluated and truncated to an integer.  Numbering from one, the corresponding line number is selected from the list of line numbers, and execution jumps to that line.  Execution returns to the line after the ON-GOSUB statement when a RETURN statement is executed in the subroutine.

   If there is no corresponding line number, execution continues with the statement after the ON-GOSUB statement.

ONERR GOTO line-number
----------------------

   This statement has no immediate effect.  If, later in the program, an error is encountered, execution jumps to the line line-number.  From there, you can use ERR and ERL to identify the type and location of the error.

   The destination line must appear in the main program, not in a subroutine or function.

   See also ERR, ERL, RESUME.

OPEN filename FOR io-kind AS '#' expression [ LEN expression ]
--------------------------------------------------------------

   Opens the file filename.

   The file may be opened in any of the following ways by substituting the token shown for the io-kind field.

   I/O kind   use
   --------   ---
   OUTPUT     The file is opened for output. If the file already exists, any old contents are lost.
   INPUT      The file is opened for input.  The file must already exist, but the file type does not matter. Input starts from the beginning of the file.

   APPEND     The file is opened for output. If the file already exists, the old contents are not lost. New information is written after all of the old information.

   RANDOM     The file is opened for random access.  The LEN field is required; each record written to or read from the file will use that number of bytes.

   BINARY     The file is opened for input and output.

   The value following # is used in subsequent file commands to identify the opened file.  This value can range from 1 to 32767. No two open files may use the same file number, but once the file is closed, the number is available for use by another OPEN statement.

   If used, the LEN expression gives the internal buffer size used to cache input and output.  This field is required for random access files, and matches the length of one random access record.  For all other file types, larger values use more RAM but generally result in faster disk input and output, while lower values save RAM but result in slower input and output.

   See also CLOSE, GET, EOF, LOC, LOF, PRINT, PRINT USING, PUT, SEEK.

POKE expression ',' expression
------------------------------

   The value of the second expression is converted to an integer.  The least significant 8 bits are stored in the memory location specified by the first expression.

   See also PEEK, WAIT.

POP
---

   Removes one GOSUB return address from the stack.  In effect, this turns the most recent GOSUB into a GOTO.

PRAGMA AUTODIM '=' ( "ON" | "OFF" )
-----------------------------------

   Turns automatic dimensioning on or off.  The default is on.

   When automatic dimensioning is turned off, variables must be declared in a DIM statement or a CONST statement before being used the first time.

PRAGMA STOPS '=' ( "ON" | "OFF" )
---------------------------------

   Turns pausing and stopping programs using CTRL-S, CTRL-C, ESC and Command-. on or off. The default is ON.

PRAGMA TOOLCHECKS '=' ( "ON" | "OFF" )
--------------------------------------

   Turns the run-time checks for tool shutdown on or off.  The default is ON, which causes GSoft BASIC to flag an error if it detects a tool startup call but does not see a matching tool shutdown call before the program completes.

PRINT [ '#' expression ]
      [ expression
        | SPC '(' expression ')'
        | TAB '(' expression ')'
        | ';'
        | ',' ]*
--------------------------------

   The various expressions are evaluated and printed.

   Output is normally printed to the text screen.  Using # followed by a number sends the output to a file, instead.

   SPC is a special function that prints spaces.  The expression is evaluated and the specified number of spaces are printed.

   TAB is a special function that prints spaces until the tab column is reached.  For example, if the expression evaluates to 10, spaces are inserted until column 10 is reached, forcing the next character printed to show up in column 10.  Columns number from 1.

   The semicolon character is used to separate multiple expressions without printing characters between them.  If used at the end of the line, a new line is not started before the next PRINT statement begins to print.

   The comma character is used to separate expressions and provide easy column alignment.  Spaces are inserted until a space is printed in a column divisible by 16.

PRINT [ '#' expression ] USING format-string ';' expression [ ( ',' | ';' ) expression ]* ( ',' | ';' )
-------------------------------------------------------------------------------------------------------

   The format string is printed.  Whenever a character that starts a format model is encountered in the format string, one expression from the list that follows the format string is evaluated. The result is rounded, truncated, or converted to fit in the space provided by the format model and printed.

   See the PRINT USING on page 169 for a complete description of format models.
Output is normally printed to the text screen.  Using # followed by a number sends the output to a file, instead.

PUT '#' expression ',' [ expression ] ',' l-value
-------------------------------------------------

   Writes values to files.  It is usually used for binary or random access files, although technically it can be used with any file type.

   The first expression is the file number, assigned when the file is opened with OPEN.

   The next expression is the location in the file to write the value.  For random access files, this is the record number; for all other files, this is a byte number.  In both cases, the first value in the file is numbered 1.

   l-value is the value to write to the file.

READ l-value [ ',' l-value ]*
-----------------------------

   Reads one or more values from a DATA statement.  The READ and DATA statements must appear in the same subroutine or must both be in the main program.

   See also DATA, RESTORE.

REM any-ascii-characters
------------------------

   The REM statement starts a comment.  All characters following the command up to the end of the line are ignored.

   See also !.

RESTORE
-------

   Restores the DATA counter, so the next READ statement reads from the first DATA statement in the current subroutine.

   See also DATA, READ.

RESUME
------

   RESUME is used in ONERR-GOTO handlers to return to the line where the error occurred.  It returns to the start of the offending line.

RETURN
------

   Returns from the most recent GOSUB, transferring control to the statement following the GOSUB statement.

RMDIR filename
--------------

   Deletes the file or directory filename.

SEEK '#' expression ',' expression
----------------------------------

   Sets the file so the next read or write occurs at the position indicated by the second expression.

   For random access files, the file is divided into chunks based on the length specified when the file is opened.  For all other file types, the file is divided into bytes. In each case, the first chunk is numbered 1, with the remaining chunks numbered sequentially.

SELECT CASE expression
----------------------
[ CASE case-range [ ',' case-range ]* ]*
----------------------------------------
[ CASE ELSE ]
-------------
END SELECT
----------

   The expression in the SELECT CASE statement is evaluated.  Expressions in the subsequent CASE statements are examined; when an expression is found that matches the original, all statements between the matching CASE statement and the following CASE or END SELECT are executed.

   Multiple expressions can be used on a single CASE statement, making it easy to use the same code for several different values.  You can also specify a range of values by separating the lowest allowed value and highest allowed value with TO.  Unlike many languages, expressions are not limited to scalar quantities; real numbers and strings are allowed as CASE values.

   If no matching expression is found, and a CASE ELSE statement is used, statements between the CASE ELSE and END SELECT are executed.  If no matching expression is found and no CASE ELSE is used, execution continues with the statement following END SELECT.

SETMEM '(' expression ',' expression ')'
----------------------------------------

   Sets the size of a memory buffer.  The first expression is the memory buffer to set; this is 0 for the variable buffer and 1 for the program buffer.  The second expression is the new size for the buffer in bytes.

SHARED identifier [ '(' ')' ] [ ',' identifier [ '(' ')' ] ]*
-------------------------------------------------------------

   Any variable or constant that appears in the main program can be accessed from any subroutine by using the SHARED statement. The SHARED statement tells GSoft BASIC to use the variable by the same name in the program rather than creating a new, local variable.

   You can share any kind of variable, including an array. Since you can create an array and a non-array with the same name, though, SHARED needs some way to distinguish between the two. Just as with passed parameters, if you are sharing an array, follow the name with an open and close parenthesis, like this:

      SHARED A()

Do not include a subscript, and do not include commas between the parenthesis, even if the array uses more than one subscript.

STOP
----

   Stops execution of the program.  If line numbers are used, the line number is printed.

   You can stop a program at a problem point and examine or even change variables, then resume execution with the command CONT.

SPEED expression
----------------

   Sets the output speed for characters written to the screen.

   A speed of 255 writes characters as rapidly as possible; this is the default.  A value of 0 introduces a long delay after each character is written.  Intermediate values cause progressively longer or shorter delays.

SUB identifier [ parameter-definition-list ]
--------------------------------------------
[ statement ]*
--------------
END SUB
-------

   Defines a subroutine. 

   The first identifier is the name of the subroutine, used when it is called.  This is followed by the parameter list, if any.  The statements that appear between the SUB statement and the END SUB statement are executed as if they were a program.

   The parameter list consists of one or more parameter declarations separated by commas.  Each parameter declaration is a variable, optionally followed by AS and a type.  If no type is given explicitly, the type is derived from the name of the variable.  For example, I% would be an integer.

   Arrays, records, pointers, strings and all numeric types are allowed as parameters.

   Inside the subroutine, all parameters work as if they were variables preset to the value passed when the subroutine is called.  If the subroutine is called with the name of a variable whose type exactly matches the parameter, and the value is changed inside the function, the value of the original variable is also changed.  If the types do not match exactly, or if the subroutine is called with an expression, or if the variable passed is surrounded by parentheses, the original value is not changed.

   Variables declared inside the subroutine survive until the subroutine returns, but no longer.  If the subroutine is called again, an entirely new set of variables is allocated.  Variables from outside the subroutine cannot be accessed from inside, except for parameters, as noted above.  Types defined in the main program are, however, available in the subroutine as well as the program.
Subroutines are called with the CALL statement.

TEXT
----

   If the graphics screen is visible, the display is shifted back to the text screen.  If the text screen is visible, nothing is changed.

TYPE identifier
---------------
  [ ( field-name [ AS type ] )
    | ( CASE [ expression ] ) ]+
--------------------------------
END TYPE
--------

   Creates a new type with the name identifier.  This type is a record, containing one or more fields. Each field has a distinct type, and the fields may have differing types.

   Each field appears on a separate line.  field-name is the name of the field, while type is the type for the field.  If the type is not specified, the type is taken from the type character appearing at the end of the identifier, just as the type is derived for a variable. For example, I% is an integer field, while R is a single-precision real number field.

TYPE identifier AS type
-----------------------

   Creates a new type with the name identifier.

UNLOADLIBRARY expression
------------------------

   Unloads the specified user tool, freeing the RAM used by the tool.

   See also LOADLIBRARY.

VTAB expression
---------------

   Sets the vertical cursor position on the text screen.  This changes the location of the flashing input cursor and the location where the next characters will be written on the text screen.

   Lines are numbered from 1 at the top of the screen to 24 at the bottom.  Numbers outside this range are legal, and are converted to the closest existing screen line.

   The horizontal position is not changed.

   See also CSRLIN, HOME, HTAB, and POS.

WAIT expression ',' expression
------------------------------

   A logical and is performed between the byte at the memory address specified by the first expression and the value specified by the second expression.  If the result is not zero, execution continues with the next statement.  If the result is zero, the process repeats.

   See also PEEK, POKE.

WHILE expression
----------------
WEND
----

   The expression is evaluated.  If it is not zero, the statements between WHILE and WEND are executed, and the process repeats.  If the expression evaluates to zero, execution continues with the statement after WEND.


Functions
=========

ABS '(' expression ')'
----------------------

   Returns the absolute value of expression.

ASC '(' string-expression ')'
-----------------------------

   Returns the ASCII numeric value for the first character in string-expression.  ASC returns 0 if there are no characters in string-expression.

ATN '(' expression ')'
----------------------

   Returns the arc-tangent of expression.

CDBL '(' expression ')'
-----------------------

   Converts expression to a double precision floating-point value.

CHR$ '(' expression ')'
-----------------------

   Returns a string consisting of a single character whose ASCII value is expression.

CINT '(' expression ')'
-----------------------

   Converts expression to an integer value.

CLNG '(' expression ')'
-----------------------

   Converts expression to a long integer value.

COS '(' expression ')'
----------------------

   Returns the cosine of expression.

CSNG '(' expression ')'
-----------------------

   Converts expression to a single precision floating-point value.

CSRLIN
------

   Returns the line number where the next character will be printed.  Lines are numbered from 1 to 24.

   See also HTAB, POS, and VTAB.

CURDIR$
-------

   Returns the name of the current directory.

DIR$ [ '(' file-name ')' ]
--------------------------

   Returns file names from a directory.

   The first call should specify a parameter.  This can be the name of a specific file or the wildcard character "*".  Full or partial path names may be used.  DIR$ will return the name of the file if there is a file by the given name, or the name of the first file in the directory if the wildcard character is used.

   If the wildcard character is used, subsequent calls may be made without a parameter.  These calls return the names of the remaining files in the directory.  When all files have been returned, DIR$ returns an empty string.

EOF '(' expression ')'
----------------------

   Returns 0 if there is unread information in a file, and -1 if there is not.

   See also GET, LOC, LOF, OPEN, and SEEK.

ERL
---

   Used in an ONERR-GOTO handler, ERL returns the line number of the line where the error occurred.  If the line where the error occurred does not have a number, ERL returns 0.

ERR
---

   Used in an ONERR-GOTO handler, ERR returns an error number indicating the type of the error.

   See Appendix A for a list of the error numbers and their meanings.

EXP '(' expression ')'
----------------------

   Returns the exponent of expression.

FRE '(' expression ')'
----------------------

   Forces garbage collection on the string space, then returns the number of bytes remaining for variables, subroutine stacks, and strings.

   The expression value should be 0, but is actually ignored.

HEX$ '(' expression ')'
-----------------------

   Returns a string showing the internal representation of the expression as a hexadecimal value.

   BYTE values are converted to INTEGER before they are converted to a hexadecimal string.

   INTEGER values are returned as a four digit two's complement number.

   LONG values are returned as an eight digit two's complement number.

   SINGLE values are returned as an eight digit IEEE single-precision floating-point value.

   DOUBLE values are returned as a sixteed digit IEEE double-precision floating-point value.

INT '(' expression ')'
----------------------

   Returns the integer part of a number.

   Unlike CINT, INT does not convert the result to an integer.  Instead, the type of the result matches the type of the argument.  For integer and long arguments, the expression result is returned unchanged.  For single and double precision real numbers, the value returned is the largest integer that is less than or equal to the value of the expression.

LEFT$ '(' string-expression ',' expression ')'
----------------------------------------------

   Returns expression characters from the beginning of a string.  If the length of the string is less than expression, the entire string is returned.

LEN '(' string-expression ')'
-----------------------------

   Returns the number of characters in string-expression.

LOC '(' expression ')'
----------------------

   Returns the number of records or bytes that have been read from or written to a file so far.  At the beginning of a file, LOC returns 0.

LOF '(' expression ')'
----------------------

   Returns the number of records or bytes in a file.

LOG '(' expression ')'
----------------------

   Returns the natural logarithm of expression.

MID$ '(' string-expression ',' expression ',' expression ')'
------------------------------------------------------------

   Returns characters from any position in a string.  The first expression is the index of the first character to return, numbering from 1.  The second expression is the number of characters to return.

   If there are not enough characters, all available characters are returned.  If the character index is larger than the length of the string, a string with no characters is returned.

NIL
---

   Returns a pointer value that is type compatible with all pointers, and that indicates a pointer which is not pointing to any memory location.

   All pointers are initially set to NIL.

   The ordinal value for NIL is 0.

PEEK '(' expression ')'
-----------------------

   Returns the value of the byte located at the address expression.

   See also POKE, WAIT.

POS '(' expression ')'
----------------------

   Returns the column where the next character will be printed.  Columns are numbered starting from 1.

   See also CSRLIN, HTAB, and VTAB.

RIGHT$ '(' string-expression ',' expression ')'
-----------------------------------------------

   Returns expression characters from the end of a string.  If the length of the string is less than expression, the entire string is returned.

RND '(' expression ')'
----------------------

   Returns a random single precision number that is greater than or equal to 0.0 and less than 1.0.

   If expression is a negative number, RND resets the random number generator seed using the argument as a seed value.

   If expression is zero, RND returns the same value it returned on the previous call.

   If expression is a positive number, a pseudo-random number is returned.

SGN '(' expression ')'
----------------------

   Returns -1 if expression is negative, 0 if expression is zero, and 1 if expression is positive.

SIN '(' expression ')'
----------------------

   Returns the sine of expression.

SIZEOF '(' ( type | identifier ) ')'
------------------------------------

   Returns the size required to store one value of a given type, or the size used by the variable identifier.  The size is given in bytes.

SQR '(' expression ')'
----------------------

   Returns the square root of expression.

STR$ '(' expression ')'
-----------------------

   Converts a numeric value to a string using the same formatting rules as the PRINT statement.

   See also VAL.

TAN '(' expression ')'
----------------------

   Returns the tangent of expression.

TOOLERROR
---------

   Returns the error code from the most recent tool, user tool or GS/OS call.  A value of zero indicates there was no error.

VAL '(' string-expression ')'
-----------------------------

   Converts a string that represents a number into a value using the same rules as READ and INPUT.

   See also STR$.

VERSION
-------

   Returns the GSoft BASIC version number encoded as a long integer.  The format is VVMMBBTRR, where

   VV   Major release number.
   MM   Minor release number.
   BB   Bug fix release number.
   T    Release type; 0 for commercial, 1 for development, 2 for alpha and 3 for beta.
   RR   Release number for the current type.

Variable Types and Names
========================

   Variable names start with a letter or underscore and are followed by any number of additional letters, underscore characters and numbers.

   The last character in the name of a variable can be a type indicator, which defines the default type for the variable.  For example, the $ character indicates a string type, so the variable name STR$ is a string variable.  If no type character is used, as in the variable name SUM, the default variable type is SINGLE.  Default types can be overridden using a DIM statement.

   The various types supported in GSoft BASIC, along with the type character for the type and the kind of information the variable holds is shown in the table.

   Character  Type       Values
   ---------  ---------  --------
   ~          BYTE       0 to 255
   %          INTEGER    -32768 to 32767
   &          LONG       -2147483648 to 2147483647
   !          SINGLE     Approximately 1E-38 to 1E38, positive or negative.
   #          DOUBLE     Approximately 1E-308 to 1E308, positive or negative.
   $          STRING     Zero to 32767 characters.

Expressions
===========

   Expressions are formed using numbers, variables, and operations.  Operator precedence determines the order of operations.  For example, the multiplication operator * has a higher precedence than the addition operation +, so the value of 1 + 2 * 3 is 7.  Operations of equal precedence are carried out in left-to-right order.

   The precedence for operations, from highest to lowest, is shown in the table.  Operations on the same line have equal precedence.

   .   ^   ()
   @
   +   -   NOT
   ^
   *   /
   +   -
   <   >   <=  >=  <>   =
   AND
   OR

   The operations are:

   .   Use to separate record names from field names.
   ^   (1st line) Dereference a pointer, yielding the value pointed to rather than the value of the pointer itself.
   ()  Parenthesis are used to change the order of operations.  For example, (1 + 2) * 3 is 9.
   @   Returns the address of a value as a pointer to the given type.
   +   (3rd line) Unary addition, as in +6.
   -   (3rd line) Unary subtraction, as in -5.
   NOT Returns 0 (false) if the argument is not zero, and 1 (true) if the argument is 0.
   ^   (4th line) Exponentiation.  For example, 2 ^ 3 is 8.
   *   Multiplication.
   /   Division.
   +   (6th line) Addition.
   -   (6th line) Subtraction.
   <   Less than.
   >   Greater than.
   <=  Less than or equal.
   >=  Greater than or equal.
   <>  Not equal.
   =   Equal.
   AND Returns 1 (true) if both arguments are non-zero, and 0 (false) if either argument is 0.
OR  Returns 1 (true) if either argument is non-zero, and 0 (false) if both arguments are zero.

PRINT USING Format Specifiers
=============================

   The first string in a PRINT USING statement gives the format for the numbers and strings that follow using fields of characters called format models.

   One or more # characters set up a format model for a number.  The number of # characters used determines the minimum width of the output field.  If the number doesn't need all of the output field, spaces are printed before the number; if there isn't enough room for the number, the entire value is still written.

   If the value is a floating-point number, the number is rounded to the closest integer value.  This doesn't convert the value to an INTEGER, it simply rounds the floating-point number to the closest whole number.

   Format Model        Value       Prints
   ------------        -----       ------
   "|##|"                  1       | 1|
   "|##|"                 12       |12|
   "|##|"                123       |123|
   "|###|"                -3       | -3|
   "|###|"             45.67       | 46|
   "|###|"              0.25       |  0|

The Decimal Point
-----------------

   Replacing one of the # characters in a numeric format model with a period turns the output from an integer to a fixed-point output.  The classic use for this format model is to print a dollar amount with exactly two digits to the right of the decimal point.

   If a number is too large to represent in the available space, it prints as # characters.

   SINGLE numbers are precise to slightly more than seven significant digits, and DOUBLE numbers are significant to more than 13 significant digits.  If you provide space for more significant digits than are available, you will get something, but the extra digits are artifacts of the number conversion, not valid values.  This is shown in the last example in the table, which gets the eighth digit right-more by accident than design-but the ninth significant digit is clearly more than the available precision for a SINGLE value.

   Format Model        Value       Prints
   ------------        -----       ------
   "|##.##|"               1       | 1.00|
   "|##.##|"              12       |12.00|
   "|##.##|"             123       |##.##|
   "|##.#|"             -3.4       |-3.4|
   "|##.#|"            -23.4       |##.#|
   "|##.##|"          45.678       |45.68|
   "|##.##|"           9.999       |10.00|
   "|##.##|"          0.0049       | 0.00|
   "|###.######|" 123.456789       |123.456780|

Adding Commas
-------------

   Replacing one or more of the # characters (except the first one!) with a comma causes the number to be printed with a comma between every three digits of the whole number part, counting left from the decimal place.  While it isn't required, it makes sense to put the commas in the same positions they will print.  This makes the format model easier to read.

   Substituting a comma for a # character does not extend the number of characters available to print values, so be sure you leave enough room for the number's significant digits and for the comma characters.  If you need to print eight significant digits, as shown in the first example of the table, you will need a total of ten characters in the format model-eight for the numeric digits, and two for commas.  As the second example shows, the number of commas is not the issue.  The issue is how many commas the PRINT USING statement will need to insert to represent the value.

   Format Model               Value     Prints
   ------------               -----     ------
   "|##,###,###|"               1e6     | 1,000,000|
   "|#,########|"               1e6     | 1,000,000|
   "|##,###,###.##|" 1.2345678912D7     |12,345,678.91|
   "|##,###.####|"      1234.5678D0     | 1,234.5678|

Controlling Positive and Negative Signs
---------------------------------------

   By default, if a number is positive no sign is printed, and if a number is negative a - character is printed before the first digit. You can change this behavior two ways.

   First, you can indicate that both + and - characters should be used for the sign by substituting a + character for the first # character.  The number will always be preceded by a sign.

   The second option is to replace the last # character with a + character or - character.  If you use a - character, the last character will be a - for negative numbers and a space for positive numbers.  If you use a + character, the last character will still be - for negative numbers, but it will be + for positive numbers.

   Leading - signs are not used in format models.  A - character appearing before a format model is treated like any other character that is not used in a format model: It is simply printed.

   Format Model        Value       Prints
   ------------        -----       ------
   "|####.##|"         -1.23       |  -1.23|
   "|+###.##|"         -1.23       |  -1.23|
   "|+###.##|"          1.23       |  +1.23|
   "|###.##-|"         -1.23       |  1.23-|
   "|###.##-|"          1.23       |  1.23 |
   "|###.##+|"         -1.23       |  1.23-|
   "|###.##+|"          1.23       |  1.23+|

Dollar Signs
------------

   Replacing the first # character with a $ character causes a $ to be printed before the number and all leading spaces.  Replacing the first two # characters with two $ characters causes a single $ character to be printed right before the first digit.

   If you are using both a leading + sign and a leading $ or $$, you can put them in any order, so long as they all come before the first # character.

   Format Model        Value       Prints
   ------------        -----       ------
   "|$###.##|"         -1.23       |$ -1.23|
   "|$###.##|"          1.23       |$  1.23|
   "|$+##.##|"         -1.23       |$ -1.23|
   "|+$##.##|"          1.23       |$ +1.23|
   "|$$##.##|"          1.23       |  $1.23|
   "|$$##.##|"         -1.23       | -$1.23|
   "|$$+#.##|"          1.23       | +$1.23|

Filling Spaces in Numbers
-------------------------

   If the format model leaves more space to the left of the decimal point than is needed, the extra space is filled with blanks.  In some applications, such as writing checks, it's a good idea to fill in any spaces so someone else doesn't fill them in for you later!

   Replacing the first # character with an * prints an * in the first space. Replacing the first two # characters with ** prints an * in all leading spaces.

   You can mix * characters, $ characters and + or - characters in any order, so long as they all appear before the first # character, and so long as pairs of * or $ characters appear as a pair. In all cases, dollar signs, positive signs and negative signs are placed in the available space just as they always were, and * characters fill any remaining spaces.

   Format Model        Value       Prints
   ------------        -----       ------
   "|*###.##|"         -1.23       |* -1.23|
   "|*###.##|"          1.23       |*  1.23|
   "|**##.##|"         -1.23       |**-1.23|
   "|**##.##|"          1.23       |***1.23|
   "|**$#.##|"         -1.23       |$*-1.23|
   "|$**#.##|"          1.23       |$**1.23|
   "|$+**.##|"         -1.23       |$*-1.23|
   "|+$**.##|"          1.23       |$*+1.23|
   "|$$**.##|"          1.23       |**$1.23|
   "|$$**.##|"         -1.23       |*-$1.23|
   "|$$+**.##|"         1.23       |**+$1.23|
   "|$$-**.##|"        -1.23       |-**$1.23|

Formatting Numbers In Scientific Notation
-----------------------------------------

   Following any number format with ^ prints the number in scientific notation.  The exponent prints as the letter e, a + or - sign, and the numeric exponent.  Use four ^ characters to hold any SINGLE exponent, and five to hold any DOUBLE exponent.  The format model ##.######^^^^ will print all significant digits of any SINGLE number, along with the sign and exponent.  The format model ##.############^^^^^ does the same for DOUBLE values.

   A minimum of three characters are needed to print a one digit exponent; one character for the "e", one for the sign, and one for the digit.  Because of this minimum size, you must use at least three ^ characters to get scientific notation.

   Format Model          Value       Prints
   ------------          -----       ------
   "|##.###^^^|"             1       | 1.000e+0|
   "|##.###^^^|"       -0.1234       |-1.234e-1|
   "|+#.######^^^^|" 123.45678       |+1.234568e+02|

Formatting Strings
------------------

   There are three format models for strings.  The & character prints an entire string, printing all characters, regardless of the size of the string.  The ! character prints the first letter of a string.  Two backslash characters with any number of intervening spaces prints as many of the characters as will fit.  The backslashes count, so a backslash, two spaces and a backslash prints the first four characters from a string.  If the format model is wider than the string, the string is printed, then blanks are printed to fill the available space.

   Format Model          Value       Prints
   ------------          -----       ------
   "|&|"                 "testing"   |testing|
   "|!|"                 "testing"   |t|
   "|\\|"                "testing"   |te|
   "|\ \|"               "testing"   |tes|
   "|\  \|"              "testing"   |test|
   "|\     \|"           "testing"   |testing|
   "|\      \|"          "testing"   |testing |
   "|\       \|"         "testing"   |testing  |

Mixing Text and Format Models
-----------------------------

   All of the examples so far show mixing of text and format models, but only to show where the value being printed started and stopped, making it clear where spaces were printed.  In actual programs it's common to see a format string with more than one format model, and to see significant text mixed in with the format models.

   For example, the program

   PV = 100
   Y = 7
   I = 10
   FV = PV * EXP (Y * LOG (1 + I / 100))
   PRINT USING "$$##.## compounded for # years at #% interest returns $$##.##."; PV, Y, I, FV

prints

   $100.00 compounded for 7 years at 10% interest returns $194.87.

Printing Format Characters as Text
----------------------------------

   You may need to print one of the special format characters from the format string.  To prevent PRINT USING from using a character as a format character, precede it with the underscore character.  To print an underscore, place two underscore characters in the format string.

   For example,

   PRINT USING "_\#_\"; 45

prints

   \45\

even though a backslash character is usually used as a fixed length string format model.

Too Many and Too Few Format Models
----------------------------------

   If there are fewer values than format models, printing stops when the first extra format model is found.  For example,

   PRINT USING "|#|#|#|"; 1, 2

prints

   |1|2|

   Too many values for the available format models reuses the format model.  This is actually a useful feature, allowing you to create multi-column tables with a single format model.  The line

   PRINT USING "|#|"; 1, 2, 3

prints

   |1||2||3|

   The only problem with a format model that will cause the program to stop with an error is providing a string to a number specifier or providing a number to a string format model.
