VERSION
-------
$Id: README.BASIC 5482 2004-02-29 13:19:06Z leo $

DESCRIPTION
-----------
This is an initial release of a BASIC interpreter hand written 
entirely in Parrot bytecode.  The NOTES below are intended for Parrot 
developers.

This README will always reflect the *current* state of things.  You can 
find the most recent version of BASIC in the Parrot CVS repository.

This BASIC is of the fairly old school.  Line numbers are required, and
the following keywords are recognized:

	LIST
	LIST expr-expr
	RUN
	LOAD progname [loads in progname.bas]
	PRINT
	PRINT expr
	PRINT expr;   [suppress newline]
	DIM           [a no-op]
	LET var=expr
	INPUT var    
	FOR var=expr TO expr
	FOR var=expr TO expr STEP expr
	GOSUB expr
	RETURN
	GOTO expr
	GO TO expr    [syn with GOTO]
	ON expr GOSUB line, line, line
	ON expr GOTO line, line, line
	IF expr THEN STATEMENT
	READ var
	DATA val, val, val, val
	RESTORE 
	RESTORE expr
	TRACE expr    [sets execution trace =1 on =0 off]
	END
	REM
	NEW
	QUIT          [exits interpreter]

The following functions are supported in the full expression parser:

	TIME()  Time since the epoch in seconds
	RND(X)	Random number between 0 and X
	ABS(X)  Absolute value of X
	LEN(X)  Length of string in X
	MID(X,Y,Z)
		Return the string of X, starting at position Y (1-based),
	        for length Z.
	RIGHT(X,Y) Return rightmost Y characters of X
	LEFT(X,Y) Return leftmost Y characters of X
	INSTR(X,Y) Return the position (1-based) where substring Y 
	        begins in X
	ASC(X)  Return the ASCII code for the character X
	CHR(X)  Return the ASCII character for the code X
	SQR(X)  Square root of X
	SIN(X)  Sine of X (radians)
	COS(X)  Cosine of X (radians)
	LOG(X)	Base-e log of X

Additionally, the expression parser understands:
	*+/-    Operators, will perform them
	+	Between two things that don't both look like numbers will
		cause concatenation instead.
	-       Unary minus
	,       Construction of tuples.  5,I+34*2,"FOO",A$ will be
		reduced to a 4-element list (comma-separated) with all
		possible evaluations done.
	AND,OR  Logical
	><<>=   Comparison (returns 1 or 0)


BASIC NOTES
-----------
   Variable name width: None (I think)
   Multidimensional variables: Alpha and Numeric
   String delimiters: ' and ", interchangeable
   Conditionals: < > = and <> (not equal)
   Math: 32-bit floating-point arithmetic.  (*new)
   Case sensitive: All statements and keywords
   Line numbers: Required
   
* GOSUB/FOR-NEXT may be nested to arbitrary depths.  Cross-nesting loops, returning
  from within a loop, or NEXT within a subroutine will cause the stack to be cleared
  back to the appropriate point.
* The values in DATA statements are evaluated at RUNTIME.  Thus, it's
  entirely possible to put variables in DATA statements
* Anywhere var is indicated, a multidimensional variable (string or array) is allowed.
* For IF statements, 0 or empty string is false everything else is true.

This was intended as a true interactive BASIC (see NOTES below) so that
any of the variables and statements work from the prompt as well as in the
body of the stored program.  Entering in a new line number overwrites the line
in the existing program

DISTRIBUTION
------------
Included in this distribution are the following files, some of which may be
of general interest, some only apply to BASIC:

	alpha.pasm		Alpha/Numeric library
	dumpstack.pasm		Diagnostic stack dumping
	expr.pasm		Expression evaluator
	stackops.pasm		Stack operations
	tokenize.pasm	  	A simple string tokenizer

	basic.pasm		The instruction dispatcher
	basicvar.pasm		Storage/Retrieval of BASIC strings, numbers, 
				code
	instructions.pasm	BASIC instructions
	sampleb.bas		Small BASIC example (my test program).

	basic.pl		Perl Harness for compiling, starting BASIC 
				in interactive mode.  Run this.  It creates 
				merged_interpreter.pasm and then basic.pbc

	wumpus.bas		Hunt the Wumpus
	eliza.bas  		Eliza

NOTES
-----
The expr.pasm module contains a full expression evaluator.  It's tied to BASIC through a 
few subroutines (to do variable and function resolution) but otherwise it's a general-purpose
evaluator.  Of special note is the Infix to Postfix notation conversion function.

After running basic.pl, it's not necessary to do it again.  Skip the long compilation 
step and just run:

	..\..\parrot basic.pbc

If a file named "autorun.bas" is found when the interpreter is loaded, it will be run
automagically.  If you wish to exit the interpreter after the program has run, use 
the QUIT statement in the program.  If you simply want to clear memory, use NEW.

BUGS
----
Negative numeric literals in DATA statements must be quoted.  i.e.  100 DATA 6,12,"-1",12

TODO
-----
* Implement SAVE and other I/O goodies
* Compilation might be fun.  

CONTACT
-------
Clinton Pierce <clintp@geeksalad.org>
"clintp" irc.rhizomatic.net #perl or #parrot

LICENSE
-------
Redistributable under the terms of any current version of Perl


