brassica 1.0.2

Description:

brassica 1.0.2

Interprets a generalised subset of 1975 Altair/Microsoft BASIC, sufficient to
run programs from:

David H. Ahl and Steve North, BASIC Computer Games, Workman (1978)
David H. Ahl and Steve North, More BASIC Computer Games, Workman (1980)

These contain many famous listings of historical interest, including early
examples of machine learning, natural language processing, artificial
intelligence, cellular automata, and Wumpus hunting.
A selection is included with the package (see below).
Requires Python 3.9 or higher (for importlib), and a carriage-return capable
terminal (IDLE isn't).
Usage
To load and run the bundled 'Wumpus' program:
import brassica
brassica.run('wumpus')

To list the loaded program:
brassica.list_program()

To load and run your own program:
brassica.run('myprogram.bas')

To rerun the last program without reloading it:
brassica.run()

To list which lines of the loaded program have not yet had all of their
statements successfully run (development tool):
brassica.not_run()

To load and run the bundled 'Camel' program in teletype mode:
brassica.run('camel', 20, 300, True)

Bundled Programs
The following titles, from the above two books, are included in the package:



Title
Authors, Contributors, and Creators




Animal
Arthur Luehrmann, Nathan Teichholtz, Steve North


Camel
The Heath Users Group


Chase
Mac Oglesby, Bill Cotter, Arnold Loveridge


Eliza
Jeff Shrager, Steve North, Joseph Weizenbaum


Even Wins
Eric Peters


Flip
John S. James


Four in a Row
James L. Murphy, Howard Wexler, Ned Strongin


Guess-It
Gerard Kierman, Rufus Isaacs


Hammurabi
David H. Ahl, Doug Dyment, Mabel Addis, William McKay


Hexapawn
R. A. Kaapke, Jeff Dalton, Steve North, Martin Gardner, Donald Michie


Inkblot
Scott Costello


Life
Clark Baker, Steve North, John Conway, Martin Gardner


Maze
Richard Schaal, Jack Hauber


Not One
Robert Puopolo, John Scarne


Sea Battle
Vincent Erikson, Steve North


Super Star Trek
Robert Leedon, David H. Ahl, Mike Mayfield, Mary Cole, John Gorders


Wumpus
Gregory Yob



Guide to Brassica BASIC
[PDF version]
Lines
Line numbers label branching destinations, but are not strictly necessary
elsewhere.
Blank lines, numbered or not, are allowed.
Lines beginning with # are comments.
Colons separate multiple statements on the same line.
The presence or absence of horizontal whitespace makes no difference anywhere
outside of string literals, DATA values, and line numbers.
Aside from the names of variables and user-defined functions, the interpreter is
case-insensitive.
# infinite loop
100
110 let x = x + 1
go to 100 : REM unnumbered line

Variables
Legitimate names consist of a letter followed by zero or more alphanumeric
characters, possibly followed by a data-type indicator (% or $), possibly
followed by array subscripts.
Names are case-sensitive, not limited to two characters, and may not contain
reserved words (TO, INT, etc.).
Arrays of character strings are supported.
The six variables below are distinct and may coexist.
Subscripts begin from zero.
All BASIC variables are global in scope.
Variables may be referenced without prior definition, in which case numbers are
initialised to 0, and strings to "".
Referencing an undimensioned array DIMs it as 0 - 10 (inclusive) on each
subscript.
X A numerical scalar.
X% An integer-constrained scalar (signed).
X$ A character string.
X(10) A scalar element of a one-dimensional numerical array.
X%(4,6) A scalar element of a two-dimensional integer array.
X$(0,0,0) One string of a three-dimensional array of strings.

Operators
In decreasing order of precedence:
(...) Bracketing (including functions).
^ Exponentiation.
unary + - Identity and negation.
* / Multiplication and division.
\ Integer division.
MOD Modulo.
+ - Addition and subtraction.
= <> < <= > >= Relational operators.
NOT Bitwise logical NOT.
AND Bitwise logical AND.
OR Bitwise logical OR.
XOR Bitwise logical XOR.

Operators of equal precedence, such as the six relationals (equal to, not equal
to, less than, less than or equal to, greater than, greater than or equal to),
are applied in left-to-right order.
The equivalence operator is a single =, which is also used for the assignment
operator immediately after an expressed or implied LET.
Whitespace is ignored; be wary of X OR and T OR (use parentheses).
Consecutive operators need not be separated by parentheses, but see below.
Logically false relations evaluate to 0, true relations to -1.
There is no short-circuiting.
Relational operations are allowed between strings, and are case-insensitive
(hence, "a" = "A", while ASC("a") <> ASC("A")).
Addition of strings performs concatenation.
Operands of bitwise operators are truncated to integers before the operator is
applied.
NOT(X%) = -(X% + 1).
Operands of \ and MOD are truncated to integers before the operator is
applied.
Results from \ are then rounded to the nearest integer towards zero.
Hence, -2\3 = 0 = 2\3, as opposed to INT(-2/3) = -1.
The modulo operator is subsequently defined via
A MOD B = INT(A) - INT(B) * (A\B)

If an alternative definition is required, perhaps a generalisation to
floating-point values, use something like:
DEF FNMO(A,B) = A - B * INT(A/B)

The unary negation (-) and logical NOT (NOT) operators imply a bracketing
extending to (not around) the next operator of lower precedence.
The unary identity (+) operator acts only on the value to its immediate right.
In effect, the unaries act as functions.
Hence;
A^B^C = A^+B^C = (A^B)^C

while
A^--B^C = A^-(-(B^C)) = A^(B^C)

and
A * NOT B + NOT C + NOT D + E AND F
= A * NOT(B + NOT(C + NOT(D + E))) AND F
= A * ((NOT B) - (NOT C) + (NOT D) - E) AND F

(This is the behaviour of Commodore BASIC v2.)
Commands
All BASIC statements begin with a command keyword.
The absence of an overt keyword implies LET.
CLEAR
Deletes all variables, arrays, and user-defined functions.
May be followed by a positive number, which is ignored.
DATA
Lists constant values for READing.
DATA 3, 4.5E-2, REM, A B C, " D,:E "
REM two numbers and three strings

DEF FN
Defines a custom function.
FN forms the beginning of its (case-sensitive) name, which must end with
the appropriate return-type indicator ($, %, or none).
DEF FNA(X) = X + C
def fnc$(a$,n) = mid$(a$,n,1)
PRINT FNA(7) fnc$("ABC",2)

DELAY
Suspends execution for a time.
(Replaces delay loops.)
DELAY 2 :REM waits two seconds

DIM
Specifies the domain of an array variable's subscripts.
Each subscript runs from zero to its specified limit (with both extremes
included).
DIM A$(5), X(2,6)
REM X has 3 * 7 = 21 elements

END
Terminates execution quietly.
FOR ... TO ... STEP
Begins a loop, iterating over some (non-array) variable.
The expression between FOR and TO is an implied LET, defining the
iterator.
The STEP (increment) is optional, and defaults to 1.
The termination threshold, appearing after TO, is locked-in as a constant
when the loop is initiated.
X=3: FOR I=1 TO X: PRINT I: X=10: NEXT
REM prints 1, 2, 3.

Because the loop-termination condition is only tested at the bottom (by the
NEXT), loops always execute at least once.
FOR I = 9 TO 5 STEP +2: PRINT I: NEXT
REM this prints 9.

Beginning a new loop terminates any prior loop over the same iterator within the
same subroutine (see GOSUB).
Termination of a loop also terminates any loops nested within it.
FOR I=1 TO 3: FOR J=1 TO 3: FOR I=1 TO 3
NEXT I: NEXT J
REM next-without-for error at the 'NEXT J'

GOSUB
Branches to a new subroutine.
The destination must be a constant literal line number.
While variables have global scope, loops are only visible within the subroutine
they were initiated in.
100 FOR I=1 TO 3: GOSUB 200
200 NEXT :REM next-without-for error here

10 REM this prints 1 2 5 6 8
20 FOR I=1 TO 8: PRINT I;
30 IF I=2 THEN GOSUB 50
40 NEXT I: PRINT: END
50 FOR I=5 TO 6: PRINT I;: NEXT I
60 RETURN

GOTO
Branches to a line number.
The destination must be a constant literal.
The word GO is reserved by BASIC in its own right.
GOTO 840

IF ... GOTO
Conditional branching.
If the condition is true, execution jumps to the specified line.
Otherwise, execution continues with the next line.
Non-zero numbers and non-empty strings are considered true.
IF X > 5 GOTO 1000

IF ... THEN
Conditional execution.
If the condition is true, execution continues along the same line.
If the condition is false, execution moves to the next line.
Non-zero numbers and non-empty strings are considered true.
IF X > 5 THEN 1000 :REM same as IF - GOTO

10 REM GOTO does the work of ELSE
20 IF A$ THEN X=X+1: GOSUB 500: GOTO 40
30 X=0: B$="Z"
40 REM line 30 is the ELSE block

IF ... THEN ... ELSE
Conditional execution.
If the condition is true, the statement before ELSE is executed.
If the condition is false, the statement after ELSE is executed.
In either case, execution proceeds to any further statements on the line.
When statements are nested, THENs and ELSEs are paired in the same manner
as opening and closing parentheses.
IF X THEN PRINT "T" ELSE PRINT "F": A = 1
REM AS is assigned in either case

IF X THEN IF Y THEN 700 ELSE 800: B = 2
REM the ELSE is paired with the second THEN
REM the B statement is unreachable

INPUT
Accepts input from the terminal.
The user is automatically re-prompted on entering the wrong type or number of
comma-separated values.
(To enter a string with a comma in it, wrap it in double quotes.)
INPUT :REM just waits for enter
INPUT X(4),Y$ :REM expects two values

An optional string-literal prompt can be printed.
It must be followed by either a semicolon (append the usual question mark) or a
comma (no question mark).
INPUT "Coordinates";X,Y
INPUT "[press enter]",

LET
Assigns a value to a variable.
The keyword is optional.
The data types of value and variable must match.
Non-integer numbers are floored when necessary.
LET A$ = "Hi!" :REM assigns "Hi!" to A$
X = "A" = "a" :REM assigns -1 to X
N%(2.3) = 4.9 :REM assigns 4 to N%(2)

NEXT
Bottom of a loop.
Increments the iteration variable by the STEP defined when the loop was
initiated.
If the variable then exceeds the termination threshold, the loop terminates and
execution continues onward.
Otherwise, execution returns to the top of the loop.
If the iteration variable is not stated, NEXT applies to the most recent
loop.
When the STEP is non-negative, 'exceeds' means 'is greater than'.
When the STEP is negative, 'exceeds' means 'is less than'.
Terminating a loop also terminates any nested loop.
See FOR and GOSUB.
FOR I = 8 TO 3 STEP -2: NEXT
FOR J = -5 TO -2: FOR K = 1 TO 3: NEXT K,J
REM at this point, I = 1, J = -1, K = 4

ON ... GOSUB
Branches to the nth of a list of subroutines.
If n should be zero, or exceed the number of subroutines, no branch is made,
and execution continues with the next statement.
N = 2: ON N GOSUB 1000, 2000, 3000
REM branches to the subroutine at line 2000

ON ... GOTO
Branches to the nth of a list of destinations.
If n should be zero, or exceed the number of destinations, no branch is made,
and execution continues with the next statement.
ON INT(3*RND(1)+1) GOTO 500, 600, 700
REM goes to one of these three lines

PRINT
Sends visible output to the terminal.
Numbers are printed with a trailing space.
Positive numbers also have a leading space (in lieu of a negative number's
sign).
(Use STR$ and MID$ to suppress these.)
The width of the terminal is divided into 'print zones' of 14 spaces each.
Consider:
PRINT A;BTAB(16)CHR$(34)SPC(4)":",C D$E $;

The first semicolon separates A from B, so we don't get the value of
AB.
No semicolon is needed after B, since the reserved word TAB cannot
be part of a variable's name.
TAB(16) moves the cursor to terminal-column 16, where CHR$(34) prints
a double-quote.
SPC(4) moves the cursor four more spaces to the right, where a colon is
printed.
The comma then moves the cursor to the beginning of the next print zone, where
the values of CD$ and E$ are printed.
(Whitespace is ignored, including within keywords.)
The final semicolon says not to print a newline at the end.
Also, while
PRINT A-B;"X"+"Y";-C

prints the value of A-B, followed by the concatenated string XY, followed
by the value of -C, the output is no different in the absence of the
semicolons and plus sign.
(Since the minus operator does not apply to strings, "Y"-C is understood as
two separate terms.)
TAB, SPC and comma are rapid operations, in that they take essentially
no time even when teletypewriter-effect options are active.
They do not overprint existing text.
This is in contrast to printing spaces, which does take time, and does
overprint.
Cursor positioning and text-wrapping will be inaccurate when special characters,
such as a bell or tab, have been printed to the line.
READ
Assigns the next DATA value to a variable. See RESTORE.
READ X,Y$ :REM read a number and a string

REM
A remark; the rest of the line is a comment.
RESTORE
Allows DATA to be READ again.
RESTORE :REM re-READ from the beginning
RESTORE 600 :REM re-READ data from line 600

RETURN
Returns from a subroutine (to the point of GOSUB).
STOP
Terminates execution with a break message.
Functions



Function
Return Value




ABS(X)
Absolute value of X.


ASC(X$)
ASCII code of the first character of X$.


ATN(X)
Arctangent of X.


CHR$(X)
The character with ASCII value X.


COS(X)
Cosine of X.


EXP(X)
Natural exponential function of X.


INT(X)
Greatest integer less than or equal to X (floor function).


LEFT$(X$,N)
The leftmost N characters of X$.


LEN(X$)
The length, in characters, of X$.


LOG(X)
Natural logarithm of X.


MID$(X$,I,N)
An N-character substring of X$, starting from the Ith (or all characters from the Ith onward, if N is omitted).


INSTR(N,X$,Y$)
The position of the first occurrence of string Y$ within string X$, not coming before the Nth character (or the first, if N is omitted). Returns 0 when X$ is empty, or when Y$ does not appear.


POS(1)
Current position of the cursor across the console (the leftmost column is numbered zero).


RND(X)
A variate from the standard uniform distribution. Use X > 0 for a new variate (X = 1 is the conventional choice), or X = 0 for the previous one. Use X < 0 to seed the generator with INT(X). Note that RND(-1) on its own is a syntax error; use A = RND(-1), or similar.


RIGHT$(X$,N)
The rightmost N characters of X$.


SGN(X)
Sign (signum) function of X.


SIN(X)
Sine of X.


SPC(X)
Advances the cursor X spaces to the right (or left, if X is negative). Can only be used within PRINT statements.


SQR(X)
Square root of X.


STR$(X)
Converts X to character-string representation. This has a leading space when X >= 0.


STRING$(N,X$)
Concatenates N copies of X$ (or N spaces, should X$ be omitted).


SYST(1)
Current system date-time, in seconds.


TAB(X)
Positions the cursor at column X (or -X spaces in from the right margin, if X is negative). Can only be used within PRINT statements. Does nothing when the cursor is already at or beyond the requested position.


TAN(X)
Tangent of X.


TTW(1)
Width of the terminal, in characters. This is normally one less than that of the parent terminal within which it is running.


VAL(X$)
Converts X$ to the numerical value it represents (the reverse of STR$).



The value of the dummy argument to \ib{POS}, \ib{SYST}, and \ib{TTW} must be
either 1 or 0.
POS and TAB will be inaccurate when special characters (\a, \b, \t, etc.)
have been printed since the last carriage return.
Identities
Functions on the left are not implemented directly.
Substitute expressions from the right.
PI = 3.1416
LOGN(X) = LOG(X)/LOG(N)
SEC(X) = 1/COS(X)
CSC(X) = 1/SIN(X)
COT(X) = 1/TAN(X)
ARCSIN(X) = ATN(X/SQR(1-X*X))
ARCCOS(X) = 1.5708-ATN(X/SQR(1-X*X)
ARCSEC(X) = 1.5708*SGN((X)-1)+ATN(SQR(X*X-1))
ARCCSC(X) = 1.5708*(SGN(X)-1)+ATN(1/SQR(X*X-1))
ARCCOT(X) = 1.5708-ATN(X)
SINH(X) = (EXP(X)-EXP(-X))/2
COSH(X) = (EXP(X)+EXP(-X))/2
TANH(X) = 1-2*EXP(-X)/(EXP(X)+EXP(-X))
SECH(X) = 2/(EXP(X)+EXP(-X))
CSCH(X) = 2/(EXP(X)-EXP(-X))
COTH(X) = 1+2*EXP(-X)/(EXP(X)-EXP(-X))
ARSINH(X) = LOG(X+SQR(X*X+1))
ARCOSH(X) = LOG(X+SQR(X*X-1))
ARTANH(X) = LOG((1+X)/(1-X))/2
ARSECH(X) = LOG((SQR(1-X*X)+1)/X)
ARCSCH(X) = LOG((SQR(1+X*X)*SGN(X)+1)/X)
ARCOTH(X) = LOG((X+1)/(X-1))/2