Add files via upload

Available Bwbasic documents in one place

Bwbasic-1.1-Manual.txt

@@ -0,0 +1,441 @@
+
+
+               Bywater BASIC Interpreter/Shell, version 1.10
+               ---------------------------------------------
+
+                    Copyright (c) 1992, Ted A. Campbell
+                 for bwBASIC version 1.10, 1 November 1992
+
+
+CONTENTS:
+
+   1. DESCRIPTION
+   2. TERMS OF USE
+   3. COMMANDS AND FUNCTIONS IMPLEMENTED
+   4. SOME NOTES ON USAGE
+   5. UNIMPLEMENTED COMMANDS AND FUNCTIONS
+   6. SOME NOTES ON COMPILATION
+   7. THE STORY OF BYWATER BASIC
+   8. COMMUNICATIONS
+
+
+1. DESCRIPTION
+
+   The Bywater BASIC Interpreter (bwBASIC) implements a large
+   superset of the ANSI Standard for Minimal BASIC (X3.60-1978)
+   in ANSI C and offers shell program facilities as an extension
+   of BASIC.
+
+   The set of BASIC commands and functions implemented is fairly
+   limited (see section three below), although more commands and
+   functions are implemented than appear in the specification
+   for Minimal BASIC. There are no commands that are terminal- or
+   hardware specific. (Seriously -- CLS may work under bwBASIC
+   on your DOS-based pc, but that is because bwBASIC shells
+   out to DOS when it does not recognize CLS and executes CLS there.)
+
+   The interpreter is 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:
+
+   The bwBASIC source code and executables produced from it can be
+   used subject to the following statement which is included in
+   the header to all the source code files:
+
+        All U.S. and international copyrights are claimed by the
+        author. The author grants permission to use this code
+        and software based on it under the following conditions:
+        (a) in general, the code and software based upon it may be
+        used by individuals and by non-profit organizations; (b) it
+        may also be utilized by governmental agencies in any country,
+        with the exception of military agencies; (c) the code and/or
+        software based upon it may not be sold for a profit without
+        an explicit and specific permission from the author, except
+        that a minimal fee may be charged for media on which it is
+        copied, and for copying and handling; (d) the code must be
+        distributed in the form in which it has been released by the
+        author; and (e) the code and software based upon it may not
+        be used for illegal activities.
+
+
+3. BASIC COMMANDS AND FUNCTIONS IMPLEMENTED:
+
+   ABS( number )
+   ASC( string$ )
+   ATN( number )
+   CHAIN [MERGE] file-name [, line-number] [, ALL]
+   CHR$( number )
+   CINT( number )
+   CLEAR
+   CLOSE [[#]file-number]...
+   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...)]...
+   END
+   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...]
+   FOR counter = start TO finish [STEP increment]
+   GET [#] device-number [, record-number]
+   GOSUB line
+   GOTO line
+   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 )
+   LOF( device-number )
+   LOG( number )
+   LSET string-variable$ = expression
+   MERGE file-name
+   MID$( string$, start-position-in-string[, number-of-spaces ] )
+   MKD$( double-value# )
+   MKI$( integer-value% )
+   MKS$( single-value! )
+   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]
+   RANDOMIZE number
+   READ variable[, variable]...
+   REM string
+   RESTORE line
+   RETURN
+   RIGHT$( string$, number-of-spaces )
+   RND( number )
+   RSET string-variable$ = expression
+   RUN [line][file-name]
+   SAVE file-name
+   SGN( number )
+   SIN( number )
+   SPACE$( number )
+   SPC( number )
+   SQR( number )
+   STOP
+   STR$( number )
+   STRING$( number, ascii-value|string$ )
+   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 ].... 
+
+   If DIRECTORY_CMDS is set to TRUE when the program is compiled,
+   then the following commands will be available:
+
+   CHDIR pathname
+   MKDIR pathname
+   RMDIR pathname
+
+   If DEBUG is set to TRUE when the program is compiled then
+   the following debugging commands (unique to bwBASIC) will
+   be available:
+
+   VARS			(prints a list of all variables)
+   CMDS			(prints a list of all commands)
+   FNCS			(prints a list of all functions)
+
+   If COMMAND_SHELL is set to TRUE when the program is compiled,
+   then the user may enter a shell command at the bwBASIC prompt.
+
+
+4. SOME NOTES ON USAGE:
+
+   An interactive environment is provided, 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. In this case,
+   however, one will not be able to alter the numberless lines
+   within the interactive environment.
+
+   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.
+
+   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".
+
+   All programs are stored as ASCII text files.
+
+   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).
+
+   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.
+
+   Notes on the implementation of specific commands:
+
+   CVI(), CVD(), 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.
+
+   ENVIRON:  The ENVIRON command requires BASIC strings on either
+   side of the equals sign.  Thus: 
+
+      environ "PATH" = "/usr/bin"
+
+   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.
+
+   ERR: 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.
+
+   FOR and NEXT:  In this implementation of bwBASIC, a NEXT
+   statement must appear in the first position in a program
+   line; it cannot appear in a line segment beyond a colon.
+
+   INPUT: bwBASIC cannot support the optional feature of INPUT
+   that suppresses the carriage-return and line-feed at the end
+   of the input.  This is because ANSI C does not provide for any
+   means of input other than CR-LF-terminated strings.
+
+
+5. UNIMPLEMENTED COMMANDS AND FUNCTIONS
+
+   There are a few 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 ANSI C cannot provide. Some specific examples:
+
+   CALL		In some versions of BASIC, CALL is used to call a
+		machine language subroutine, but machine language
+		routines are highly system-specific.  In other
+		BASICs (conforming to the more complete ANSI
+		definition of BASIC), CALL is used to call a
+		named subroutine.  Although it's possible that
+		bwBASIC could develop as a numberless BASIC
+		with named subroutine calls, these features
+		are not implemented in this earliest released
+		version.
+
+   CLOAD	See CALL above (machine language subroutines).
+
+   CONT		See RESUME below (programmer ignorance?).
+
+   DEF USR	See CALL above (machine language subroutines).
+
+   EDIT		EDIT would be especially nice, but requires some
+   		specific knowledge of how particular computers
+   		handle interaction between the screen and the
+   		keyboard.  This knowledge isn't available within
+   		the bounds of ANSI C alone ("innerhalb die Grenzen
+		der reinen Vernunft," with apologies to Immanuel
+		Kant).
+
+   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 C and this function
+		is not available in bwBASIC.
+
+   FILES	The FILES command requires a list of files conforming
+   		to a specifier; ANSI C does not provide this. When
+   		COMMAND_SHELL is defined as TRUE, users might want
+   		to issue operating-system commands such as "DIR"
+   		(DOS) or "ls -l" (Unix) to get a list of files.
+
+   INKEY$	This function requires a keyboard scan to indicate
+		whether a key is pending. Although this facility
+		is easily available on microcomputers (it is part
+		of the minimal CP/M Operating System), it is not
+		easily available on some more complex systems. 
+		Consequently, it's not part of the C standard and
+		bwBASIC has not implemented INKEY$.
+
+   INPUT$()	Similar to INKEY$ above, ANSI 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 ANSI 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.
+
+   RESUME	Is this possible under ANSI 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
+   		subroutines).
+
+   VARPTR	See PEEK and POKE above.
+
+   WAIT		See INP and OUT above.
+
+   		
+6. SOME NOTES ON COMPILATION
+
+   bwBASIC is written in ANSI C and takes advantage of some of the
+   enhancements of ANSI C over the older K&R standard.  The program
+   expects to find standard ANSI C include files (such as ).
+   Because there is nothing terminal- or hardware-specific about it,
+   I should hope that it would compile correctly under any ANSI C
+   compiler, but you may have to construct your own makefile.
+
+   Two makefiles are currently provided: "makefile.qcl" will compile
+   the program utilizing the Microsoft QuickC (tm) line-oriented 
+   compiler on DOS-based p.c.'s, and "makefile.gcc" will compile 
+   the program utilizing the ANSI option of Gnu C++. I have also 
+   compiled the program utilizing Borland's Turbo C++ (tm) on DOS-
+   based machines.
+
+   No alterations to flags are necessary for varied environments,
+   but the beginning of file  allows the user to set
+   some debugging flags and to control some program defaults.
+   The file  has a number of language-specific message
+   sets that can be controlled by setting the appropriate language
+   flag.
+
+
+7. THE STORY OF BYWATER BASIC
+
+   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.
+
+   
+8. COMMUNICATIONS:
+
+   Ted A. Campbell
+   Bywater Software
+   P.O. Box 4023
+   Duke Station
+   Durham, NC  27706
+   USA
+
+   email:  tcamp@acpub.duke.edu
+
+