Phil Cockcroft's BASIC Manual Page

basic - `Basic' language interpreter

SYNOPSIS

basic [ -e -x -n file ]

DESCRIPTION

Basic is an interpreter for the Basic language. See below for current commands recognised. If a file is given then that file is loaded up into core and run without any interaction. This can be used for games etc. which use a small calling program which is set user-id. All commands are only recognised in lower case. A line editor is invoked for all input from the terminal. To get characters less than space into a line use the construct \n \a etc. which will get cntrl-n and cntrl-a into the line.

FLAGS

-e: use the in built editor for line input. Even when default mode is for no editor.
-x: don't use the editor ever. Use the terminal driver for all editing and input.
-n: where n is any number between 0 and 9 defines the number of file buffers allocated at start up.

COMMANDS

Standard Dartmouth Basic Commands

end: This terminates the execution of a program and returns to command level.
run { lineno }: This will execute a program, if an optional line number is given then the program is run from that line. All variables are cleared and all files are closed.
goto lineno: This command will transfer control to the specified line number
let x = EXP: This command is used to introduce an assignment. If a command is not found on a line then a implied let is assumed.
list: the whole file
list 1-2: lines 1 to 2
list -1: lines up to 1
list 1: line 1 list 1-
line 1 onwards: This command will list any number of lines of text onto the terminal. The start and last line can be specified as can to a specified line and from a specified line.
print or '?'
print #f: This command will print out all of it's parameters, they have to be separated by commas or semi-colons, if a comma is used then the print head is moved to the next tab position (16 places ). If a file descriptor is given then output is to the given file.
rem or `': A comment statement, is ignored totally by the program during execution.
stop: Stops the execution of the program and returns to command level. Similar to 'end' but prints a message. A program can also be 'cont'inued after a stop.
for x = EXP to EXP { step EXP }: Will start execution of a for loop. It will take the two limits and an optional step argument. The loop is always executed once.
next { x { , y } }: End of the for loop, if the terminal conditions are met then execution continues from the next statement otherwise return to end of the corresponding for statement. The next does not need a parameter if this is the case the most recently activated loop is used. If there are more than one parameter then each one is only checked after the completion of the inner loop.
gosub lineno: Transfer command to a line number. Save return address so that the program can resume execution after the gosub command.
return: Return from a subroutine ( called by gosub ). It will return from the most recently activated subroutine call.
read VAR { , VAR }: Read data from the data statements contained in the program. An item can be a string or a variable.
data OBJECT { , OBJECT }: Statements that contain the data used in the read statements. Items are separated by commas. The data statement must be the only one on the line.
restore { lineno }: Restore the data pointer to the start of the file. So that the data can be read again. If an optional line number is given then the restore occurs from the start of that line. If no data statements are found then the restore is from the start of the program.
if EXP then STATEMENT { else STATEMENT }: The if statement if the condition is true then the commands after the 'then' are executed. If this is a line number then a goto is performed. If the condition is false then the statement after the else is dealt with in a similar manner, the else statement is an optinal facility.
dim VAR ( d,d,d ) { , VAR( d ) }: Dimension a list of arrays ( string or arithmetic ) a maximum of three subscripts can be used. All arrays must be dimensioned before use.
exit , bye , quit: Terminate the execution of the interpreter, closing all files.

Extended Basic Commands

delete l - l: Delete a specified range of lines. If they are not found then no lines will be deleted.
edit l: Edit a given line. If the exit from the edit is via a cntrl-c then do not change the line.
input { #f , }: input "prompt"; Input from a terminal or from a file. If the input is from the terminal then a prompt message can also be added.
clear EXP: Clear all variables then allocate the amount of string space specified by the second parameter.
save STRINGEXP: Save the current program to a named file.
old STRINGEXP: Load a program from the named file. All variables are cleared.
new { EXP }: Wipe the program from core. All files are closed and the interpreter is reset to its inital state. If a parameter is given then that is the number of file buffers that are allocated.
shell: Shell out to Unix. This is the Bourne shell. If the interpreter is made set userid then this is turned off in the shell.
resume { l }: Return from an error trap. If a parameter is given then the return is made to that line. An error trap is set up by the "on error goto" statement.
random: Randomise the random number generator. The generator always starts from the same place in its sequence, when a program is started.
on EXP goto l { , l}
on EXP gosub
on error goto lineno: This command will execute either a goto or a gosub to a specified line number. The linenumber is specified by the value of the statement and the linenumber is taken from the list of line numbers that is given. If the error format is used, only one linenumber is required. This is the line where a jump is performed to if an error occurs.
error EXP: Execute the given error sequence. Useful for debugging of error trap routines. anonymousOS Release 0.0 4 BASIC(1) USER COMMANDS BASIC(1)
auto { l { ,l } }: Perform auto line numbering so that a program can be typed in without having to bother about linenumbers. An optional start and increment can also be specified.
cls: Clear the terminals screen.
base 0 | 1: Specify the starting index for arrays. This can have a value of either zero or one.
poke EXP , EXP: Poke a value into a location. Unreasonable addresses are ignored. ( Can cause bus-errors if not using split i and d space. (Not available on Vax systems).
open STRINGEXP { for input | output | append | terminal } as EXP: Open a file for input/ output. This command can be used to specify whether the file is to be read or writen to. A file cannot be opened for writing if the file is already open. If the mode is terminal then it will believe that it is talking to a terminal. (No buffering. Open for reading and writing.) If the option is 'for output' it may be ommitted.
close EXP: Close a file. Releases the file descriptor and flushes out all stored data.
merge STRINGEXP: Merge two files together. If there is a line in the file with the same linenumber as in the program then that line is replaced by the new one. All other lines are inserted into the file.
chain STRINGEXP: Read in a program, then start to execute it. All simple variables are kept but all arrays and strings are cleared. The size of the string space is kept the same.
def fnNAME{ ( VAR {,VAR } ) } = EXP: Define a user defineable function.
linput: Identical to input but ignores seperators.
mid$(STRINGVAL , EXP { ,EXP} ) = STRINGEXP: Assign STRINGEXP to STRINGVAL starting at EXP1 and finishing at EXP2.
cont: Continue execution of a program that has been halted by a stop statement or by control-c.
while EXP: Start of a while loop. The loop is repeated until EXP is false. If EXP is false at the start then do not execute the loop at all. A while loop must be terminated by a wend statement.
wend: Terminating statement of a while loop. Only one wend is allowed for each while.
repeat: Start statement for a repeat - until loop. This type of loop will always be executed at least once.
until EXP: The terminating statement of a repeat - until loop. The loop terminates when EXP is true.

String functions Available

mid$(a$,i,j): Returns the part of a$ between the i'th and j'th positions. If the second parameter is not specified then the string is taken between the start value and the end of the string.
right$(a$,j): Returns the right j characters of a$.
left$(a$,j): Returns the left j characters of a$.
string$(a$,j): Returns a$ repeated j times.
ermsg$(j): Returns the j'th error message.
chr$(j): Returns the ascii character corresponding to the value of j.
str$(j): Returns a string representation corresponding to j. This is similar but not the same as what can printed out.
space$(j): Returns a string of j spaces
get$(f): Returns one character from file f. If f is zero use the terminal. Returns a zero lenght string on cntl-c
date$: returns a string coresponding to the current date. ( Same string as printed out when logging on. ).

Maths functions Available

sgn(x): Returns the sign of a number. It's value is 1 if greater than zero , zero if equal to zero. -1 if negative.
len(a$): Returns the length of string a$.
abs(x): Returns the absolute value of x.
int(x): than x.
val(a$): Returns the value of the number specified by the string.
asc(a$): Returns the ascii code for the first element of a$.
instr(a$,b$,c): Returns the starting position that a$ is in b$, starting from the optional c'th position.
eof(f): Returns true if the file specified by f has reached the end of the file.
posn(f): Returns the current printing position in the file. If f is zero then it is the printing position of the terminal.
sqrt(x): Returns the square root of X.
log(x): Returns the natural logarithm of x.
exp(x): Returns e^x. e=2.7182818..
eval(a$): Evaluates a$. e.g. eval("12") returns the value 12.
rnd: Returns a random number between 1 and 32767.
rnd(x): If x is zero returns a random number between 0 and 1 otherwise returns a random number between 1 and int(x).
peek(x): Returns the value of the byte at address x. If x is unreasonable then returns zero. ( Not available on a VAX )
sin(x)
cos(x)
atan(x): Trignometric functions. (May not yet be implemented).
pi: Returns the value of pi. = 3.141592653589...
erl: Returns the line number of the last error. Zero if error was in immeadiate mode.
err: Returns the error code of the last error.
tim: Returns a numeric value for the number of seconds since 1:1:1970 i.e. the value of the Unix clock.

Mathematical Operators

The following mathematical operators are accepted.

^ exponentiation
* multiplication
/ division
mod remainder
+ addition
- subtraction

bitwise operators

for real values non-zero is true,

and bitwise and
or bitwise or
xor bitwise exclusive or
not bitwise not

comparison operators

<= less than or equal
<> not equal to
>= greater than or equal
= equal
> greater than
< less than

Assignment statements can also have the form

	a +=  b     a -=  b     a *=  b    a /=  b

Which have similar meanings to C's interpretation

EXPRESSION SYNTAX

stringexp ::= string | string + stringexp
string ::= qstring | stringvar | stringfunc
qstrings ::= "any char" | `any char` N.B. strings with nothing after them on the line do not need the terminating quote
stringvar ::= numbvar$ | numbvar$[ dim1 { ,dim2 {, dim3 } } ]
stringfunc ::= chr$(val) | mid$(stringexp, val {,val} ) | date$ | right$(stringexp, val) | left$(stringexp, val) | ermsg$(val) | str$( val) | space$(val) | string$(stringexp, val) | get$( 0 | fval )
val ::= term | term sep val | not val | - val
term ::= numb | valfunc | numbvr | stringexp csep stringexp
numb ::= digit | digit digit+ | digit* . digit* | digit* e {+ | -} digit+ | digit* . digit* e {+ | -} digit+
digit ::= 0 1 2 3 4 5 6 7 8 9
numbvr ::= numbvar | subsc
numbvar ::= lett | lett alpha+
subsc ::= numbvar( val {, val { ,val } } )
sep ::= + - * / ^ and or xor | csep
csep ::= <> > < >= <= =
valfunc ::= sgn(val) | len(stringexp) | abs(val) | val(stringexp) | asc(stringexp) | eof(fval) | posn( 0 | fval) | sqrt(val) | instr(stringexp, val { ,val} ) | log(val) | exp(val) | eval(stringexp) | int(val) | peek(val) | rnd | rnd(val) | usrfunc | pi | erl | err | tim
usrfunc ::= fn/numbvar { (val { , val { , val } } ) }
fval ::= val with value between 1-9

DIAGNOSTICS

When the interpreter discovers an error it will call an error trapping routine. The errors can be caught by the user program using the on-error feature. If no error trapping routine has been supplied a message is printed with the corresponding line number.

BUGS

None yet!

AUTHOR

Phil Cockcroft

HTMLize by

kabe(at)dais.is..tohoku.ac..jp