Scroll to navigation

BWBASIC(1) General Commands Manual BWBASIC(1)


bwbasic - Bywater BASIC interpreter/shell
               Bywater BASIC Interpreter/Shell, version 2.10
                    Copyright (c) 1993, Ted A. Campbell
                  for bwBASIC version 2.10, 11 October 1993
   The author wishes to express his thanks to Mr. David MacKenzie, 
   who assisted in the development Unix installation and configuration
   for this version.
   The Bywater BASIC Interpreter (bwBASIC) implements a large
   superset of the ANSI Standard for Minimal BASIC (X3.60-1978)
   and a significant subset of the ANSI Standard for Full BASIC
   (X3.113-1987) in C. It also offers shell programming facilities
   as an extension of BASIC. bwBASIC seeks to be as portable
   as possible.
   bwBASIC can be configured to emulate features, commands, and
   functions available on different types of BASIC interpreters;
   see the file INSTALL for further installation information.
   The interpreter is fairly slow.  Whenever faced with a choice
   between conceptual clarity and speed, I have consistently chosen
   the former.  The interpreter is the simplest design available,
   and utilizes no system of intermediate code, which would speed
   up considerably its operation.  As it is, each line is interpreted
   afresh as the interpreter comes to it.
   bwBASIC implements one feature not available in previous BASIC
   interpreters: a shell command can be entered interactively at the
   bwBASIC prompt, and the interpreter will execute it under a
   command shell.  For instance, the command "dir *.bas" can be
   entered in bwBASIC (under DOS, or "ls -l *.bas" under UNIX) and
   it will be executed as from the operating system command line.
   Shell commands can also be given on numbered lines in a bwBASIC
   program, so that bwBASIC can be used as a shell programming
   language. bwBASIC's implementation of the RMDIR, CHDIR, MKDIR,
   NAME, KILL, ENVIRON, and ENVIRON$() commands and functions
   offer further shell-processing capabilities.
   This version of Bywater BASIC is released under the terms of the 
   GNU General Public License (GPL), which is distributed with this 
   software in the file "COPYING".  The GPL specifies the terms 
   under which users may copy and use the software in this distribution.
   A separate license is available for commercial distribution,
   for information on which you should contact the author.
   Be aware that many of these commands and functions will not be
   available unless you have set certain flags in the header files
   (see the expanded reference section below for dependencies).
   ABS( number )
   ASC( string$ )
   ATN( number )
   CALL subroutine-name
   CASE ELSE | IF partial-expression | constant
   CHAIN [MERGE] file-name [, line-number] [, ALL]
   CHDIR pathname
   CHR$( number )
   CINT( number )
   CLOSE [[#]file-number]...
   COMMON variable [, variable...]
   COS( number )
   CSNG( number )
   CVD( string$ )
   CVI( string$ )
   CVS( string$ )
   DATA constant[,constant]...
   DEF FNname(arg...)] = expression
   DEFDBL letter[-letter](, letter[-letter])...
   DEFINT letter[-letter](, letter[-letter])...
   DEFSNG letter[-letter](, letter[-letter])...
   DEFSTR letter[-letter](, letter[-letter])...
   DELETE line[-line]
   DIM variable(elements...)[variable(elements...)]...
   DO [WHILE expression]
   ENVIRON variable-string = string
   ENVIRON$( variable-string )
   EOF( device-number )
   ERASE variable[, variable]...
   ERROR number
   EXP( number )
   FIELD [#] device-number, number AS string-variable [, number AS string-variable...]
   FILES filespec$
   FOR counter = start TO finish [STEP increment]
   GET [#] device-number [, record-number]
   GOSUB line | label
   GOTO line | label
   HEX$( number )
   IF expression THEN [statement [ELSE statement]]
   INPUT [# device-number]|[;]["prompt string";]list of variables
   INSTR( [start-position,] string-searched$, string-pattern$ )
   INT( number )
   KILL file-name
   LEFT$( string$, number-of-spaces )
   LEN( string$ )
   LET variable = expression
   LINE INPUT [[#] device-number,]["prompt string";] string-variable$
   LIST line[-line]
   LOAD file-name
   LOC( device-number )
   LOCATE line, column
   LOF( device-number )
   LOG( number )
   LOOP [UNTIL expression]
   LSET string-variable$ = expression
   MERGE file-name
   MID$( string$, start-position-in-string[, number-of-spaces ] )
   MKD$( number )
   MKDIR pathname
   MKI$( number )
   MKS$( number )
   NAME old-file-name AS new-file-name
   NEXT [counter]
   OCT$( number )
   ON variable GOTO|GOSUB line[,line,line,...]
   OPEN "O"|"I"|"R", [#]device-number, file-name [,record length]
        file-name FOR INPUT|OUTPUT|APPEND AS [#]device-number [LEN = record-length]
   OPTION BASE number
   PRINT [# device-number,][USING format-string$;] expressions...
   PUT [#] device-number [, record-number]
   RANDOMIZE number
   READ variable[, variable]...
   REM string
   RESTORE line
   RIGHT$( string$, number-of-spaces )
   RMDIR pathname
   RND( number )
   RSET string-variable$ = expression
   RUN [line][file-name]
   SAVE file-name
   SELECT CASE expression
   SGN( number )
   SIN( number )
   SPACE$( number )
   SPC( number )
   SQR( number )
   STR$( number )
   STRING$( number, ascii-value|string$ )
   SUB subroutine-name
   SWAP variable, variable
   TAB( number )
   TAN( number )
   VAL( string$ )
   WHILE expression
   WIDTH [# device-number,] number
   WRITE [# device-number,] element [, element ]....
   4.a. Interactive Environment
   An interactive environment is provided if the flag INTERACTIVE
   is defined as TRUE in bwbasic.h, so that a line with a
   line number can be entered at the bwBASIC prompt and it will be
   added to the program in memory.
   Line numbers are not strictly required, but are useful if the
   interactive environment is used for programming.  For longer
   program entry one might prefer to use an ASCII text editor, and
   in this case lines can be entered without numbers. One can use
   DO NUM and DO UNNUM to number or unnumber lines. See also the
   documentation below for the pseudo-command EDIT.
   4.b. Naming Conventions
   Command names and function names are not case sensitive,
   so that "Run" and "RUN" and "run" are equivalent and "abs()"
   and "ABS()" and "Abs()" are equivalent. HOWEVER, variable
   names ARE case sensitive in bwbASIC, so that "d$" and "D$"
   are different variables.  This differs from some BASIC
   implementations where variable names are not case sensitive.
   Variable names can use any alphabetic characters, the period
   and underscore characters and decimal digits (but not in the
   first position). They can be terminated with '#' or '!' to
   allow Microsoft-type names, even though the precision is
   irrelevant to bwBASIC.
   4.c. Numerical Constants
   Numerical constants may begin with a digit 0-9 (decimal), with
   the "&H" or "&h" (hexadecimal) or the "&o" or "&O" (octal).
   Decimal numbers may terminated with 'E', 'e', 'D', or 'd'
   followed by an exponent number to denote exponential notation.
   Decimal constants may also be terminated by the '#' or '!'
   to comply with Microsoft-style precision terminators, although
   the precision specified will be irrelevant to bwBASIC.
   4.d. Command-Line Execution
   A filename can be specified on the command line and will be
   LOADed and RUN immediately, so that the command line
      bwbasic prog.bas
   will load and execute "prog.bas".
   4.e. Program Storage
   All programs are stored as ASCII text files.
   4.f. TRUE and FALSE
   TRUE is defined as -1 and FALSE is defined as 0 in the default
   distribution of bwBASIC. These definitions can be changed by
   those compiling bwBASIC (see file BWBASIC.H).
   4.g. Assignments
   Assignment must be made to variables.  This differs from some
   implementations of BASIC where assignment can be made to a
   function.  Implication: "INSTR( 3, x$, y$ ) = z$" will not
   work under bwBASIC.
   4.h. Operators and Precedence
   bwBASIC recognizes the following operators, with their level
   of precedence given (1 = highest):
      ^                 1       exponentiation
      *                 2       multiplication
      /                 2       division
                       3       integer division
      +                 5       addition
      -                 5       subtraction
      =                 6       equality or assignment
      MOD               4       modulus (remainder) arithmetic
      <>                7       inequality
      <                 8       less than
      >                 9       greater than
      <=                10      less than or equal to
      =<                10      less than or equal to
      >=                11      greater than or equal to
      =>                11      greater than or equal to
      NOT               12      negation
      AND               13      conjunction
      OR                14      disjunction
      XOR               15      exclusive or
      IMP               16      implication
      EQV               17      equivalence
   4.h. Numerical Precision (NOT)
   bwBASIC utilizes numbers with only one level of precision. If
   the flag NUMBER_DOUBLE is defined as TRUE in bwbasic.h, the
   precision implemented will be that of the C "double" data type;
   otherwise (default) the precision will be that of the C "float"
   type.  At a number of points there are commands (or pseudo-
   commands) that seem to recognize Microsoft-style precision
   distinctions, but for the most part these are just work-around
   aliases to allow Microsoft-style programs to be run.
   The "Dependencies" listed in the following reference materials
   refers to flags that must be set to TRUE in bwbasic.h for the
   associated command or function to be implemented.  These flags
   are as follows:
   (core)               Commands and Functions in any implementation of
                        bwBASIC; these are the ANSI Minimal BASIC core
   INTERACTIVE          Commands supporting the interactive programming
   COMMON_CMDS          Commands beyond ANSI Minimal BASIC which are common
                        to Full ANSI BASIC and Microsoft BASICs
   COMMON_FUNCS         Functions beyond the ANSI Minimal BASIC core, but
                        common to both ANSI Full BASIC and Microsoft-style
                        BASIC varieties
   UNIX_CMDS            Commands which require Unix-style directory and
                        environment routines not specified in C
   STRUCT_CMDS          Commands related to structured programming; all
                        of these are part of the Full ANSI BASIC standard
   ANSI_FUNCS           Functions unique to ANSI Full BASIC
   MS_CMDS              Commands unique to Microsoft BASICs
   MS_FUNCS             Functions unique to Microsoft BASICs
   Function:     ABS( number )
   Description:  ABS returns the absolute value of the argument 'number'.
   Dependencies: (core)
   Function:     ASC( string$ )
   Description:  ASC returns the ASCII code for the first letter in
                 the argument string$.
   Dependencies: MS_FUNCS
   Function:     ATN( number )
   Description:  ATN returns the arctangent value of the argument 'number'
                 in radians.
   Dependencies: (core)
   Command:      CALL subroutine-name
   Description:  CALL calls a named subroutine (see SUB and END SUB).
   Dependencies: STRUCT_CMDS
   Command:      CASE ELSE | IF partial-expression | constant
   Description:  CASE introduces an element of a SELECT CASE statement
                 (see SELECT CASE). CASE IF introduces a conditional
                 SELECT CASE element, and CASE ELSE introduces a
                 default SELECT CASE element.
   Dependencies: STRUCT_CMDS
   Command:      CHAIN [MERGE] file-name [, line-number] [, ALL]
   Description:  CHAIN passes control to another BASIC program.
                 Variables declared COMMON (q.v.) will be passed
                 to the new program.
   Dependencies: COMMON_CMDS
   Command:      CHDIR pathname$
   Description:  CHDIR changes the current directory to that indicated
                 by the argument pathname$.
   Dependencies: UNIX_CMDS
   Function:     CHR$( number )
   Description:  CHR$ returns a one-character string with the character
                 corresponding to the ASCII code indicated by argument
   Dependencies: COMMON_FUNCS
   Function:     CINT( number )
   Description:  CINT returns the truncated integer for the argument
   Dependencies: MS_FUNCS
   Command:      CLEAR
   Description:  CLEAR sets all numerical variables to 0, and all
                 string variables to null.
   Dependencies: COMMON_CMDS
   Command:      CLOSE [[#]file-number]...
   Description:  CLOSE closes the file indicated by file-number
                 (see OPEN).
   Dependencies: COMMON_CMDS
   Command:      CLS
   Description:  CLS clears the display screen (IBM and compatibles
                 only as of version 2.10).
   Dependencies: IMP_IQC and IMP_CMDLOC
   Command:      CMDS
   Description:  CMDS is a debugging command that prints a list
                 of all implemented bwBASIC commands.
   Dependencies: DEBUG
   Command:      COMMON variable [, variable...]
   Description:  COMMON designates variables to be passed to a CHAINed
                 program (see CHAIN).
   Dependencies: COMMON_CMDS
   Function:     COS( number )
   Description:  COS returns the cosine of the argument 'number'
                 in radians.
   Dependencies: (core)
   Function:     CSNG( number )
   Description:  CSNG is a pseudo-function that has no effect under
                 bwBASIC.  It replicates a Microsoft-type command
                 that would convert the 'number' to single-precision.
   Dependencies: MS_FUNCS
   Function:     CVD( string$ )
   Description:  CVD converts the argument string$ into a bwBASIC
                 number (precision is irrelevant in bwBASIC since
                 bwBASIC numbers have only one precision).
   Implementation-Specific Notes:
   CVD(), CVI(), CVS(), MKI$(), MKD$(), MKS$(): These functions
   are implemented, but are dependent on a) the sizes for integer,
   float, and double values on particular systems, and b) how
   particular versions of C store these numerical values. The
   implication is that data files created using these functions
   on a DOS-based microcomputer may not be translated correctly
   by bwBASIC running on a Unix-based computer.  Similarly, data
   files created by bwBASIC compiled by one version of C may not be
   readable by bwBASIC compiled by another version of C (even under
   the same operating system). So be careful with these.
   Dependencies: MS_FUNCS
   Function:     CVI( string$ )
   Description:  CVI converts the argument string$ into a bwBASIC
                 number (precision is irrelevant in bwBASIC since
                 bwBASIC numbers have only one precision; see also
                 the note on CVD).
   Dependencies: MS_FUNCS
   Function:     CVS( string$ )
   Description:  CVI converts the argument string$ into a bwBASIC
                 number (precision is irrelevant in bwBASIC since
                 bwBASIC numbers have only one precision; see also
                 the note on CVD).
   Dependencies: MS_FUNCS
   Command:      DATA constant[,constant]...
   Description:  DATA stores numerical and string constants to be
                 accessed by READ (q.v.).
   Dependencies: (core)
   Function:     DATE$
   Description:  DATE$ returns the current date based on the computer's
                 internal clock as a string in the form "YYYY-MM-DD".
                 As implemented under bwBASIC, DATE$ cannot be used for
                 assignment (i.e., to set the system date).
   Note:         bwBASIC presently (v2.10) does not allow assignment
                 to a function.
   Dependencies: COMMON_FUNCS
   Command:      DEF FNname(arg...)] = expression
   Description:  DEF defines a user-written function.  This function
                 corresponds to Microsoft-type implementation, although
                 in bwBASIC DEF is a working equivalent of FUNCTION.
   Dependencies: (core)
   Command:      DEFDBL letter[-letter](, letter[-letter])...
   Description:  DEFDBL declares variables with single-letter names
                 as numerical variables (precision is irrelevant in
   Dependencies: MS_CMDS
   Command:      DEFINT letter[-letter](, letter[-letter])...
   Description:  DEFINT declares variables with single-letter names
                 as numerical variables (precision is irrelevant in
   Dependencies: MS_CMDS
   Command:      DEFSNG letter[-letter](, letter[-letter])...
   Description:  DEFSNG declares variables with single-letter names
                 as numerical variables (precision is irrelevant in
   Dependencies: MS_CMDS
   Command:      DEFSTR letter[-letter](, letter[-letter])...
   Description:  DEFSTR declares variables with single-letter names
                 as string variables.
   Dependencies: MS_CMDS
   Command:      DELETE line[-line]
   Description:  DELETE deletes program lines indicated by the
                 argument(s). If you want to use DELETE for non-
                 numbered programs, first use DO NUM, then DELETE,
                 then DO UNNUM.
   Dependencies: INTERACTIVE
   Command:      DIM variable(elements...)[variable(elements...)]...
   Description:  DIM specifies variables that have more than one
                 element in a single dimension, i.e., arrayed
   Note:         As implemented under bwBASIC, DIM accepts only
                 parentheses as delimiters for variable fields.
                 (Some BASICs allow the use of square brackets.)
   Dependencies: (core)
   Command:      DO NUM|UNNUM
   Description:  DO NUM numbers all lines in a program.  The first
                 line is given the number 10, and subsequent lines
                 are numbered consecutively in multiples of 10. DO
                 UNNUM removes all line numbers from a program.
                 NOTE that these functions do nothing to line
                 numbers, e.g., following a GOSUB or GOTO statement;
                 these commands cannot be used as a replacement for
                 RENUM (available in some systems, but not bwBASIC).
                 With these commands, however, one can develop
                 unnumbered programs by entering new lines with numbers,
                 then running DO UNNUM to remove the line numbers.
                 Together with LOAD and SAVE (q.v.) one can use
                 bwBASIC as a primitive text editor.
   Dependencies: INTERACTIVE
   Command:      DO [WHILE expression]
   Description:  DO implements a number of forms of program loops.
                 DO...LOOP simply loops; the only way out is by
                 EXIT; DO WHILE...LOOP loops while "expression" is
                 true (this is equivalent to the older WHILE-WEND
                 loop, also implemented in bwBASIC); DO...LOOP UNTIL
                 loops until the expression following UNTIL is true.
   Dependencies: STRUCT_CMDS
   Command:      EDIT
   Description:  EDIT is a pseudo-command which calls the text editor
                 specified in the variable BWB.EDITOR$ to edit the
                 program in memory.  After the call to the text editor,
                 the (edited) program is reloaded into memory.  The user
                 normally must specific a valid path and filename in
                 BWB.EDITOR$ before this command will be useful.
   Dependencies: COMMON_CMDS
   Command:      ELSE
   Description:  ELSE introduces a default condition in a multi-line IF
   Dependencies: STRUCT_CMDS
   Command:      ELSEIF
   Description:  ELSEIF introduces a secondary condition in a multi-
                 line IF statement.
   Dependencies: STRUCT_CMDS
   Command:      END IF | FUNCTION | SELECT | SUB
   Description:  END IF ends a multi-line IF statement. END FUNCTION
                 ends a multi-line function definition. END SELECT
                 ends a SELECT CASE statement.  END SUB ends a multi-
                 line subroutine definition.
   Dependencies: STRUCT_CMDS
   Command:      ENVIRON variable-string$ = string$
   Description:  ENVIRON sets the environment variable identified by
                 variable-string$ to string$.
                 It might be noted that this differs from the implementation
                 of ENVIRON in some versions of BASIC, but bwBASIC's ENVIRON
                 allows BASIC variables to be used on either side of the equals
                 sign.  Note that the function ENVIRON$() is different from the
                 command, and be aware of the fact that in some operating systems
                 an environment variable set within a program will not be passed
                 to its parent shell.
   Dependencies: UNIX_CMDS
   Function:     ENVIRON$( variable-string$ )
   Description:  ENVIRON$ returns the environment variable associated with
                 the name variable-string$.
   Dependencies: MS_FUNCS
   Function:     EOF( device-number )
   Description:  EOF returns TRUE (-1) if the device associated with
                 device-number is at the end-of-file, otherwise it
                 returns FALSE (0).
   Dependencies: MS_FUNCS
   Command:      ERASE variable[, variable]...
   Description:  ERASE eliminates arrayed variables from a program.
   Dependencies: COMMON_CMDS
   Function:     ERL
   Description:  ERL returns the line number of the most recent error.
   Dependencies: MS_FUNCS
   Function:     ERR
   Description:  ERR returns the error number of the most recent error.
                 Note that if PROG_ERRORS has been defined when bwBASIC is
                 compiled, the ERR variable will not be set correctly upon
                 errors.  It only works when standard error messages are used.
   Dependencies: MS_FUNCS
   Command:      ERROR number
   Description:  ERROR simulates an error, i.e., displays the message
                 appropriate for that error. This command is helpful
                 in writing ON ERROR GOSUB routines that can identify
                 a few errors for special treatment and then ERROR ERR
                 (i.e., default handling) for all others.
   Dependencies: COMMON_CMDS
   Command:      EXIT [FOR]
   Description:  EXIT by itself exits from a DO...LOOP loop;
                 EXIT FOR exits from a FOR...NEXT loop.
   Dependencies: STRUCT_CMDS
   Function:     EXP( number )
   Description:  EXP returns the exponential value of 'number'.
   Dependencies: (core)
   Command:      FIELD [#] device-number, number AS string-variable$ [, number AS string-variable$...]
   Description:  FIELD allocates space in a random file buffer for device
                 indicated by device-number, allocating 'number' bytes
                 and assigning the bytes at this position to the variable
   Dependencies: COMMON_CMDS
   Command:      FILES filespec$
   Description:  FILES is a pseudocommand that invokes the directory program
                 specified in the variable BWB.FILES$ with the argument
                 filespec$.  Normally, the user must set this variable
                 before FILES can be used.  E.g., for PC-type computers,
                    BWB.FILES$ = "DIR"
                 will work, for Unix machines,
                    BWB.FILES$ = "ls -l"
   Dependencies: COMMON_CMDS
   Command:      FNCS
   Description:  CMDS is a debugging command that prints a list
                 of all pre-defined bwBASIC functions.
   Dependencies: DEBUG
   Command:      FUNCTION
   Description:  FUNCTION introduces a function definition, normally
                 ending with END FUNCTION.  In bwBASIC, FUNCTION and
                 DEF are working equivalents, so either can be used
                 with single-line function definitions or with multi-
                 line definitions terminated by END FUNCTION.
   Dependencies: STRUCT_CMDS
   Command:      FOR counter = start TO finish [STEP increment]
   Description:  FOR initiates a FOR-NEXT loop with the variable
                 'counter' initially set to 'start' and incrementing
                 in 'increment' steps (default is 1) until 'counter'
                 equals 'finish'.
   Dependencies: (core)
   Command:      GET [#] device-number [, record-number]
   Description:  GET reads the next record from a random-access file
                 or device into the buffer associated with that file.
                 If record-number is specified, the GET command reads the
                 specified record.
   Dependencies: COMMON_CMDS
   Command:      GOSUB line | label
   Description:  GOSUB initiates a subroutine call to the line (or label)
                 specified.  The subroutine must end with RETURN.
   Dependencies: (core), but STRUCT_CMDS for labels
   Command:      GOTO line | label
   Description:  GOTO branches program execution to the specified line
                 (or label).
   Dependencies: (core), but STRUCT_CMDS for labels
   Function:     HEX$( number )
   Description:  HEX$ returns a string giving the hexadecimal (base 16)
                 value for the 'number'.
   Dependencies: MS_FUNCS
   Command:      IF expression THEN [statement [ELSE statement]]
   Description:  IF evaluates 'expression' and performs the THEN
                 statement if it is true or (optionally) the
                 ELSE statement if it is FALSE.  If STRUCT_CMDS
                 is set to TRUE, bwBASIC allows multi-line IF
                 statements with ELSE and ELSEIF cases, ending
                 with END IF.
   Dependencies: (core), STRUCT_CMDS for multi-line IF statements
   Function:     INKEY$
   Description:  INKEY$ reads the status of the keyboard, and a single
                 keypress, if available. If a keypress is not available,
                 then INKEY$ immediately returns a null string ("").
                 Currently (v2.10) implemented in bwx_iqc.c only.
   Dependencies: IMP_IQC and IMP_CMDLOC
   Command:      INPUT [# device-number]|[;]["prompt string";]list of variables
   Description:  INPUT allows input from the terminal or a device
                 specified by device-number.  If terminal, the "prompt
                 string" is output, and input is assigned to the
                 appropriate variables specified.
                 bwBASIC does not support the optional feature of INPUT
                 that suppresses the carriage-return and line-feed at the end
                 of the input.  This is because C alone does not provide for any
                 means of input other than CR-LF-terminated strings.
   Dependencies: (core)
   Function:     INSTR( [start-position,] string-searched$, string-pattern$ )
   Description:  INSTR returns the position at which string-pattern$
                 occurs in string-searched$, beginning at start-position.
                 As implemented in bwBASIC, INSTR cannot be used for
   Note:         bwBASIC presently (v2.10) does not allow assignment
                 to a function.
   Dependencies: MS_FUNCS
   Function:     INT( number )
   Description:  INT returns the largest integer less than or equal to
                 the argument 'number'. NOTE that this is not a "truncated"
                 integer function, for which see CINT.
   Dependencies: (core)
   Command:      KILL file-name$
   Description:  KILL deletes the file specified by file-name$.
   Dependencies: UNIX_CMDS
   Function:     LEFT$( string$, number-of-spaces )
   Description:  LEFT$ returns a substring a string$ with number-of-spaces
                 from the left (beginning) of the string). As implemented
                 under bwBASIC, it cannot be used for assignment.
   Dependencies: MS_FUNCS
   Function:     LEN( string$ )
   Description:  LEN returns the length in bytes of string$.
   Dependencies: COMMON_FUNCS
   Command:      LET variable = expression
   Description:  LET assigns the value of 'expression' to the variable.
                 As currently implemented, bwBASIC supports implied LET
                 statements (e.g., "X = 4.5678" at the beginning of
                 a line or line segment, but does not support assignment
                 to multiple variables (e.g., "x, y, z = 3.141596").
   Dependencies: (core)
   Command:      LINE INPUT [[#] device-number,]["prompt string";] string-variable$
   Description:  LINE INPUT reads entire line from the keyboard or a file
                 or device into string-variable$.  If input is from the
                 keyboard (stdin), then "prompt string" will be printed
                 first.  Unlike INPUT, LINE INPUT reads a whole line,
                 not stopping for comma-delimited data items.
   Dependencies: COMMON_CMDS
   Command:      LIST line[-line]
   Description:  LIST lists program lines as specified in its argument.
   Dependencies: INTERACTIVE
   Command:      LOAD file-name
   Description:  LOAD loads an ASCII BASIC program into memory.
   Dependencies: INTERACTIVE
   Function:     LOC( device-number )
   Description:  LOC returns the next record that GET or PUT statements
                 will use.
   Dependencies: MS_FUNCS
   Command:      LOCATE line, column
   Description:  LOCATE addresses trhe curor to a specified line and
                 column. Currently (v2.10) implemented in bwx_iqc.c only.
   Dependencies: IMP_IQC and IMP_CMDLOC
   Function:     LOF( device-number )
   Description:  LOF returns the length of a file (specified by device-number)
                 in bytes.
   Dependencies: MS_FUNCS
   Function:     LOG( number )
   Description:  LOG returns the natural logarithm of the argument 'number'.
   Dependencies: (core)
   Command:      LOOP [UNTIL expression]
   Description:  LOOP terminates a program loop:  see DO.
   Dependencies: STRUCT_CMDS
   Command:      LSET string-variable$ = expression
   Description:  LSET transfers data from 'expression' to the left-hand
                 side of a string variable or random access buffer field.
   Dependencies: COMMON_CMDS
   Command:      MERGE file-name
   Description:  MERGE adds program lines from 'file-name' to the program
                 in memory.  Unlike LOAD, it does not clear the program
                 currently in memory.
   Dependencies: COMMON_CMDS
   Function:     MID$( string$, start-position-in-string[, number-of-spaces ] )
   Description:  MID$ returns a substring of string$ beginning at
                 start-position-in-string and continuing for
                 number-of-spaces bytes.
   Dependencies: MS_FUNCS
   Command:      MKDIR pathname$
   Description:  MKDIR creates a new directory path as specified by
   Dependencies: UNIX_CMDS
   Function:     MKD$( number )
   Description:  MKD$, MKI$, and MKS$ are all equivalent in bwBASIC.
                 They convert the numerical value 'number' into a string
                 which can be stored in a more compressed form in a file
                 (especially for random file access).  Since bwBASIC does
                 not recognize differences in precision, these commands
                 are effectively equivalent.
   Dependencies: MS_FUNCS
   Function:     MKI$( number )
   Description:  Equivalent to MKD$ (q.v.)
   Dependencies: MS_FUNCS
   Function:     MKS$( number )
   Description:  Equivalent to MKD$ (q.v.).
   Dependencies: MS_FUNCS
   Command:      NAME old-file-name AS new-file-name
   Description:  NAME renames an existing file (old-file-name) as
   Dependencies: UNIX_CMDS
   Command:      NEW
   Description:  NEW deletes the program in memory and clears all
   Dependencies: INTERACTIVE
   Command:      NEXT [counter-variable]
   Description:  NEXT comes at the end of a FOR-NEXT loop; see FOR.
   Dependencies: (core)
   Function:     OCT$( number )
   Description:  OCT$ returns a string giving the octal (base 8)
                 representation of 'number'.
   Dependencies: MS_FUNCS
   Command:      ON variable GOTO|GOSUB line[,line,line,...]
   Description:  ON either branches (GOTO) or calls a subroutine
                 (GOSUB) based on the rounded value of variable;
                 if it is 1, the first line is called, if 2, the second
                 line is called, etc.
   Dependencies: (core)
   Command:      ON ERROR GOSUB line|label
   Description:  ON ERROR sets up an error handling subroutine. See
                 also ERROR.
   Dependencies: COMMON_CMDS, STRUCT_CMDS for labels
   Command:      OPEN "O"|"I"|"R", [#]device-number, file-name [,record length]
                      file-name FOR INPUT|OUTPUT|APPEND AS [#]device-number [LEN = record-length]
   Description:  OPEN allocates random access memory for access to a disk
                 file or other device.  Note that two quite different forms
                 of the OPEN statement are supported. In the first form,
                 "O" (note that these letters must be encased in quotation
                 marks) denotes sequential output, "I" denotes sequential
                 input, and "R" denotes random-access input and output.
                 Once OPEN, any number of operations can be performed
                 on a device (see WRITE #, INPUT #, PRINT #, etc.).
   Dependencies: COMMON_CMDS
   Command:      OPTION BASE number
   Description:  OPTION BASE sets the lowest value for array subscripts,
                 either 0 or 1.
   Dependencies: (core)
   Function:     POS
   Description:  POS returns the current cursor position in the line.
   Dependencies: COMMON_FUNCS
   Command:      PRINT [# device-number,][USING format-string$;] expressions...
   Description:  PRINT outputs text to the screen or to a file or device
                 specified by device-number. In the current implementation
                 of bwBASIC, expressions to be printed must be separated by
                 the comma (tabbed output), the semicolon (immediate
                 sequential output) or the plus sign (immediate sequential
                 output by string concatenation).  Expressions separated
                 by blanks or tabs are not supported. If USING is specified,
                 a number of formatting marks may appear in the format
                    !   prints the first character of a string
                    \  prints 2+x characters of a string, where x =
                        the number of spaces between the backslashes
                    &   variable-length string field
                    #   represents a single digit in output format for
                        a number
                    .   decimal point in a number
                    +   sign of a number (will output + or -)
                    -   trailing minus after a number
                    **  fill leading spaces with asterisks
                    $$  output dollar sign in front of a number
                    ^^  output number in exponential format
                    _   output next character literally
                 As currently implemented, the exponential format
                 will be that used by the C compiler.
   Dependencies: (core), COMMON_FUNCS for USING
   Command:      PUT [#] device-number [, record-number]
   Description:  PUT outputs the next available record or the record
                 specified by record-number to the file or device
                 denoted by device-number.
   Dependencies: COMMON_CMDS
   Command:      QUIT
   Description:  QUIT is a synonym for SYSTEM; with INTERACTIVE
                 environment, it exits the program to the 
                 operating system (or the calling program).
   Dependencies: INTERACTIVE
   Command:      RANDOMIZE number
   Description:  RANDOMIZE seeds the random number generator (see RND).
                 Under bwBASIC, the TIMER function (q.v.) can be used
                 to supply a 'number' seed for the random number
   Dependencies: (core)
   Command:      READ variable[, variable]...
   Description:  READ reads values from DATA statements and assigns these
                 values to the named variables.  Variable types in a READ
                 statement must match the data types in DATA statements
                 as they are occurred.  See also DATA and RESTORE.
   Dependencies: (core)
   Command:      REM string
   Description:  REM allows remarks to be included in a program. As
                 currently implemented, the entire line following
                 REM is ignored by the interpreter (thus, even if
                 MULTISEG_LINES is set, a REM line will not be able
                 to find a segment delimiter (":") followed by another
                 line segment with command.  bwBASIC does not currently
                 implement the Microsoft-style use of the single quotation
                 mark to denote remarks.
   Dependencies: (core)
   Command:      RESTORE line
   Description:  RESTORE resets the line and position counters for DATA
                 and READ statements to the top of the program file or
                 to the beginning of the specified line.  (Currently this
                 must be a line number.)
   Dependencies: (core)
   Command:      RETURN
   Description:  RETURN concludes a subroutine called by GOSUB.
   Dependencies: (core)
   Function:     RIGHT$( string$, number-of-spaces )
   Description:  RIGHT$ returns a substring a string$ with number-of-spaces
                 from the right (end) of the string). As implemented
                 under bwBASIC, it cannot be used for assignment.
   Dependencies: MS_FUNCS
   Command:      RMDIR pathname
   Description:  RMDIR deletes the directory path indicated by pathname.
   Dependencies: UNIX_CMDS
   Function:     RND( number )
   Description:  RND returns a pseudo-random number.  The 'number' value
                 is ignored by bwBASIC if supplied. The RANDOMIZE
                 command (q.v.) reseeds the random-number generator.
   Dependencies: (core)
   Command:      RSET string-variable$ = expression
   Description:  RSET transfers data from 'expression' to the right-hand
                 side of a string variable or random access buffer field.
   Dependencies: COMMON_CMDS
   Command:      RUN [line][file-name$]
   Description:  RUN executes the program in memory.  If a file-name$ is
                 supplied, then the specified file is loaded into memory
                 and executed.  If a line number is supplied, then execution
                 begins at that line.
   Dependencies: INTERACTIVE
   Command:      SAVE file-name$
   Description:  SAVE saves the program in memory to file-name$. bwBASIC
                 only saves files in ASCII format.
   Dependencies: INTERACTIVE
   Command:      SELECT CASE expression
   Description:  SELECT CASE introduces a multi-line conditional selection
                 statement.  The expression given as the argument to SELECT
                 CASE will be evaluated by CASE statements following.  The
                 SELECT CASE statement concludes with an END SELECT
                 As currently implemented, CASE statements may be followed
                 by string values, but in this case only simple comparisons
                 (equals, not equals) can be performed. 
   Dependencies: STRUCT_CMDS
   Function:     SGN( number )
   Description:  SGN returns the sign of the argument 'number', +1
                 for positive numbers, 0 for 0, and -1 for negative numbers.
   Dependencies: (core)
   Function:     SIN( number )
   Description:  SIN returns the sine of the argument 'number'
                 in radians.
   Dependencies: (core)
   Function:     SPACE$( number )
   Description:  SPACE$ returns a string of blank spaces 'number'
                 bytes long.
   Dependencies: MS_FUNCS
   Function:     SPC( number )
   Description:  SPC returns a string of blank spaces 'number'
                 bytes long.
   Dependencies: MS_FUNCS
   Function:     SQR( number )
   Description:  SQR returns the square root of the argument 'number'.
   Dependencies: (core)
   Command:      STOP
   Description:  STOP interrupts program execution. As implemented under
                 bwBASIC, STOP issues a SIGINT signal.
   Dependencies: (core)
   Function:     STR$( number )
   Description:  STR$ returns a string giving the decimal (base 10)
                 representation of the argument 'number'.
   Dependencies: COMMON_FUNCS
   Function:     STRING$( number, ascii-value|string$ )
   Description:  STRING$ returns a string 'number' bytes long consisting
                 of either the first character of string$ or the character
                 answering to the ASCII value ascii-value.
   Dependencies: MS_FUNCS
   Command:      SUB subroutine-name
   Description:  SUB introduces a named, multi-line subroutine. The
                 subroutine is called by a CALL statement, and concludes
                 with an END SUB statement.
   Dependencies: STRUCT_CMDS
   Command:      SWAP variable, variable
   Description:  SWAP swaps the values of two variables. The two variables
                 must be of the same type (either numerical or string).
   Dependencies: COMMON_CMDS
   Command:      SYSTEM
   Description:  SYSTEM exits from bwBASIC to the calling program or
                 (more usually) the operating system.
   Dependencies: INTERACTIVE
   Function:     TAB( number )
   Description:  TAB outputs spaces until the column indicated by
                 'number' has been reached.
   Dependencies: (core)
   Function:     TAN( number )
   Description:  TAN returns the tangent of the argument 'number'
                 in radians.
   Dependencies: (core)
   Function:     TIME$
   Description:  TIME$ returns the current time based on the computer's
                 internal clock as a string in the form "HH-MM-SS".
                 As implemented under bwBASIC, TIME$ cannot be used for
                 assignment (i.e., to set the system time).
   Note:         bwBASIC presently (v2.10) does not allow assignment
                 to a function.
   Dependencies: COMMON_FUNCS
   Function:     TIMER
   Description:  TIMER returns the time in the system clock in seconds
                 elapsed since midnight.
   Dependencies: MS_FUNCS
   Command:      TROFF
   Description:  TROFF turns of the trace facility; see TRON.
   Dependencies: COMMON_CMDS
   Command:      TRON
   Description:  TRON turns on the trace facility. This facility will print
                 each line number in square brackets as the program is
                 executed.  This is useful in debugging programs with
                 line numbers.  To debug an unnumbered program with
                 TRON, call DO NUM first, but remember to call DO UNNUM
                 before you save the program later.
   Dependencies: COMMON_CMDS
   Function:     VAL( string$ )
   Description:  VAL returns the numerical value of the string$.
   Dependencies: COMMON_FUNCS
   Command:      VARS
   Description:  VARS is a debugging command which prints a list of
                 all variables defined which have global scope.
   Dependencies: DEBUG
   Command:      WEND
   Description:  WEND concludes a WHILE-WEND loop; see WHILE.
   Dependencies: COMMON_CMDS
   Command:      WHILE expression
   Description:  WHILE initiates a WHILE-WEND loop.  The loop ends with
                 WEND, and execution reiterates through the loop as
                 long as the 'expression' is TRUE (-1).
   Dependencies: COMMON_CMDS
   Command:      WIDTH [# device-number,] number
   Description:  WIDTH sets screen or device output to 'number'
                 columns.  device-number specifies the device
                 or file for output.
   Dependencies: COMMON_CMDS
   Command:      WRITE [# device-number,] element [, element ]....
   Description:  WRITE outputs variables to the screen or to a file
                 or device specified by device-number.  Commas
                 are inserted between expressions output, and strings
                 are enclosed in quotation marks.
   Dependencies: COMMON_CMDS
   The commands EDIT and FILES are pseudo-commands that launch
   shell programs named in the variables BWB.EDITOR$ and BWB.FILES$,
   respectively.  The default values for these variables can
   be changed in bwbasic.h (DEF_EDITOR and DEF_FILES), or they
   can be changed on the fly by the user.  An idea might be to
   initialize these variables in "profile.bas" for specific
   implementations; for instance, BWB.FILES$ might be defined as
   "ls -l" on Unix systems or "dir" on DOS systems.
   The preset variable BWB.PROMPT$ can be used to set the prompt
   string for bwBASIC.  Again, it is suggested that a user-
   selected prompt can be set up in a "profile.bas" to be
   initialized each time bwBASIC starts.  Note that special
   characters can be added to the prompt string, e.g.,
      BWB.PROMPT$ = "Ok"+CHR$(10)
   will give an "Ok" prompt followed by a linefeed.
   The preset variable BWB.IMPLEMENTATION$ will return "TTY" for
   the bwx_tty implementation and will return "IQC" for the
   IBM PC or Compatibles with QuickC (bwx_iqc) implementation.
   This may be useful in determining which commands and functions
   (specifically CLS, LOCATE, and INKEY$) may be available. 
   There are some items not implemented that have been so long
   a part of standard BASICs that their absence will seem surprising.
   In each case, though, their implementation would require opera-
   ting-system-specific functions or terminal-specific functions
   that cannot be universally provided. Some specific examples:
   CLOAD        Relies on CP/M or MSDOS conventions for binary
                executable files. 
   CONT         See RESUME below (programmer ignorance?).
   DEF USR      Relies on CP/M or MSDOS conventions for binary
                executable files. 
   FRE()        The ability to report the amount of free memory
                remaining is system-specific due to varying patterns
                of memory allocation and access; consequently this
                ability is not present in ANSI or earlier versions 
                of C and this function is not available in bwBASIC.
   INPUT$()     C by itself is not able to read unechoed keyboard 
                input, and can read keyboard input only after a 
                Carriage-Return has been entered.
   INP          Calls to hardware ports, like machine-language
                routines, are highly system-specific and cannot
                be implemented in C alone.
   LLIST        See LPRINT below.
   LPOS         See LPRINT below.
   LPRINT       and LLIST, etc., require access to a printer device,
                and this varies from one system to another. Users
                might try OPENing the printer device on their own
                operating system (e.g., "/dev/lp" on Unix systems,
                or "PRN" under DOS) and see if printing can be done
                from bwBASIC in this way.
   NULL         In this case, I am convinced that NULL is no longer
                necessary, since very few printers now require NULLs
                at the end of lines.
   OUT          See INP above (calls to hardware ports).
   PEEK()       PEEK and POKE enabled earlier BASICs to address
                particular memory locations. Although bwBASIC
                could possibly implement this command (POKE) and
                this function (PEEK()), the limitation would be
                highly limited by the different systems for
                memory access in different systems.
   POKE         see PEEK() above.
   RENUM        Since unnumbered lines can be entered and
                executed under bwBASIC, it would not be
                possible to implement a RENUM routine.
                Instead, bwBASIC uses DO NUM and DO UNNUM.
   RESUME       Is this possible under C? If so, I
                simply have failed to figure it out yet.
                Mea culpa (but not maxima).
   USR          See CALL and DEF USR above (machine language
   VARPTR       See PEEK and POKE above.
   WAIT         See INP and OUT above.
   There are other commands, functions, and implementation details
   that I am working on, and which are on the agenda list for future
   versions of bwBASIC.  These agenda include:
   PARACT       i.e., the ability to execute PARallel ACTions. This
                is described in ANSI BASIC, although I have not seen it
                implemented before.  It will offer a rough, non-
                preemptive form of multitasking within the scope
                of a BASIC program. Programmers will note points at which
                there are already hooks for PARACT in bwBASIC.
   XMEM         PC-type computers need to be able to use extended
                memory.  If we could use extended memory for program
                lines, variables, and function definitions, we could
                write much longer programs.  This would entail,
                however, a fairly serious rewriting of the program
                to utilize memory handles for these storage features
                instead of direct memory pointers.
   Windows      The addition of memory handles in addition to the
                non-preemptive execution of program lines (in a
                crude form, already present) will make it possible
                to develop implementations for Windows and perhaps
                for other graphical user interfaces.  But what form
                should this take?  I have in mind presently a BASIC
                that would run in the background, appearing only
                as an icon in the GUI space, with pop-up editors
                and output windows. Thus, the interpreted language
                would serve a purpose something like 'cron' (a task
                scheduler) under Unix systems. You may have some
                reflections that would help me in this.
   Graphics     Here we face fairly critical differences in different
                styles and implementations of graphics, e.g., between
                GWBASIC, ANSI BASIC, VisualBASIC, etc. But it's
                possible that Graphics commands and functions could
                be added. These would all be implementation-specific.
   The ANSI Standard for full BASIC does not specify which particular
   commands or functions must be implemented, and in fact the standard
   is very robust.  Perhaps no implementation of BASIC would ever
   include all of the items, but some ANSI commands and functions which
   remain unimplemented are:
   This program was originally begun in 1982 by my grandmother, Mrs.
   Verda Spell of Beaumont, TX.  She was writing the program using
   an ANSI C compiler on an Osborne I CP/M computer and although my
   grandfather (Lockwood Spell) had bought an IBM PC with 256k of
   RAM my grandmother would not use it, paraphrasing George Herbert
   to the effect that "He who cannot in 64k program, cannot in 512k."
   She had used Microsoft BASIC and although she had nothing against
   it she said repeatedly that she didn't understand why Digital
   Research didn't "sue the socks off of Microsoft" for version 1.0
   of MSDOS and so I reckon that she hoped to undercut Microsoft's
   entire market and eventually build a new software empire on
   the North End of Beaumont. Her programming efforts were cut
   tragically short when she was thrown from a Beaumont to Port
   Arthur commuter train in the summer of 1986. I found the source
   code to bwBASIC on a single-density Osborne diskette in her knitting
   bag and eventually managed to have it all copied over to a PC
   diskette. I have revised it slightly prior to this release. You
   should know, though, that I myself am an historian, not a programmer.
October 11, 1993