bwbasic.doc

这是一个简易的basic语言解释器, 可供我们学习和改进.

               Bywater BASIC Interpreter/Shell, version 2.10
               ---------------------------------------------

                    Copyright (c) 1993, Ted A. Campbell
                  for bwBASIC version 2.10, 11 October 1993


CONTENTS:

   1. DESCRIPTION
   2. TERMS OF USE
   3. QUICK REFERENCE LIST OF COMMANDS AND FUNCTIONS
   4. GENERAL NOTES ON USAGE
   5. EXPANDED REFERENCE FOR COMMANDS AND FUNCTIONS
   6. PREDEFINED VARIABLES
   7. UNIMPLEMENTED COMMANDS AND FUNCTIONS
      and AGENDA FOR DEVELOPMENT
   8. THE STORY OF BYWATER BASIC
   9. COMMUNICATIONS

   The author wishes to express his thanks to Mr. David MacKenzie, 
   who assisted in the development Unix installation and configuration
   for this version.


1. DESCRIPTION

   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.


2. TERMS OF USE:

   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.


3. QUICK REFERENCE LIST OF COMMANDS AND FUNCTIONS

   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 )
   CLEAR
   CLOSE [[#]file-number]...
   CLS
   COMMON variable [, variable...]
   COS( number )
   CSNG( number )
   CVD( string$ )
   CVI( string$ )
   CVS( string$ )
   DATA constant[,constant]...
   DATE$
   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 NUM|UNNUM
   DO [WHILE expression]
   EDIT
   ELSE
   ELSEIF
   END IF | FUNCTION | SELECT | SUB
   ENVIRON variable-string = string
   ENVIRON$( variable-string )
   EOF( device-number )
   ERASE variable[, variable]...
   ERL
   ERR
   ERROR number
   EXP( number )
   FIELD [#] device-number, number AS string-variable [, number AS string-variable...]
   FILES filespec$
   FUNCTION
   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]]
   INKEY$
   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
   NEW
   NEXT [counter]
   OCT$( number )
   ON variable GOTO|GOSUB line[,line,line,...]
   ON ERROR GOSUB 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
   POS
   PRINT [# device-number,][USING format-string$;] expressions...
   PUT [#] device-number [, record-number]
   QUIT
   RANDOMIZE number
   READ variable[, variable]...
   REM string
   RESTORE line
   RETURN
   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 )
   STOP
   STR$( number )
   STRING$( number, ascii-value|string$ )
   SUB subroutine-name
   SWAP variable, variable
   SYSTEM
   TAB( number )
   TAN( number )
   TIME$
   TIMER
   TROFF
   TRON
   VAL( string$ )
   WEND
   WHILE expression
   WIDTH [# device-number,] number
   WRITE [# device-number,] element [, element ]....
   

4. GENERAL NOTES ON USAGE:

   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 enviroment 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.


5. EXPANDED REFERENCE FOR COMMANDS AND FUNCTIONS

   The "Dependencies" listed in the folowing 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
   			environment

   COMMON_CMDS		Commands beyond ANSI Minimal BASIC which are common
   			to Full ANSI BASIC and Microsoft BASICs

   COMMON_FUNCS		Functions beyond the ANSI Mimimal 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
                 'number'.

   Dependencies: COMMON_FUNCS

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

   Function:     CINT( number )

   Description:  CINT returns the truncated integer for the argument
                 'number'.

   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 )