=====================
My BASIC Interpreter
=====================

by Shandong Han

CAT Lab (http://catlab.idogicat.com/)

This is a command line tool to interprete BASIC programs. It can also run as an expression evaluator. It writes the result to stdout and returns 0. When error occurs, it writes error message to stderr, and returns 1.

Usage:

	mybasic -e <expression>

or

	mybasic -f <BASIC_program_file_name>


Expression Evaluatorr
=====================

The expression should be written in BASIC syntax. algebra, string, comparison and logic calculations are supported.

The spec of it is as follows:

Data types
-----------

   * boolean
   * integer
   * double
   * string

Operators
-----------

   * math: ^, +(unary), -(unary), *, /, \, MOD, +, -
   * string: +
   * relational: =, <>, <, <=, >, >=
   * logic: NOT, AND, OR
   * others: (, ) (to change precedences of operators)

Math Functions
---------------

abs, sign, int, sqrt, exp, log, log10, rad (change degrees to radians), deg (change radians to degrees), sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, asinh, acosh, atanh, sec, csc, pi (return value of Pi), random (return random number in [0, 1])

String Functions
-----------------

str(num) (convert number to string), space(n), tab(n), ltrim(str), rtrim(str), trim(str), len(str), ucase(str), lcase(str), val(str) (parse string to number), isNumeric(str), left(str, n), right(str, n), mid(str, from, n), instr(str1, str2) (return index starting from 0; if not found, return -1)

Differences from traditional BASIC language
-------------------------------------------

   * some function names are different, for example, "sqrt" instead of "sqr"
   * indexes in a string starts from 0 instead of 1
   * BASIC type characters (such as "2#" for 2 of double type) not supported


BASIC Interpreter
==================

This interpreter supports a practically simplified BASIC syntax.

Spec of 'practically simplified BASIC syntax' (besides things listed above):

Supported
----------

   * comment: REM, '
   * variable declarison: DIM ... AS ...
   * condition (block IF): IF, THEN, ELSEIF, ELSE, END IF
   * FOR loop: FOR, TO, STEP, NEXT, CONTINUE FOR, EXIT FOR
   * DO loop: DO, WHILE, UNTIL, LOOP, CONTINUE DO, EXIT DO
   * function & sub-routine: FUNCTION, END FUNCTION, SUB, END SUB, RETURN, BYVAL, BYREF
   * output: PRINT
   * others: END

Not supported
--------------

   * LET (most useless command. ignored by the interpreter.)
   * line number (too old)
   * GOTO (evil)
   * GUSUB...RETURN (too old)
   * DEF FN (too old)
   * Single-line IF
   * READ...DATA (too old)
   * SELECT CASE (don't like the syntax. don't want to introduce something too different, such as the 'switch/case' in C/C++/Java.
     can be replaced with IF)
   * ON [ERROR] ... (too old)
   * WHILE ... WEND (old but not good; replaced by the more powerful & flexible DO ... LOOP)
   * EXIT SUB, EXIT FUNCTION (use RETURN instead)
   * CALL (but functions can be called directly as sub-routines)
   * variant data type (decreases code quality)
   * user defined type (class)
   * PRINT USING (if it is really necessary, will consider adding it)
   * file I/O (OPEN, etc... will provide new set of file I/O API in later versions)


Differences from normal BASIC language
---------------------------------------

   * variables must be declared (with DIM) before use (similar to always declaring 'OPTIONAL EXPLICIT' in Visual Basic. to help improve code quality.)
   * "DIM a, b, c AS DOUBLE" is OK, but "DIM a AS INTEGER, b AS DOUBLE" not supported (to help improve code quality)
   * Boolean type not allowed to convert from & to Integer (to help improve code quality)
   * functions: BYVAL or BYREF must be specified (no default) (to help improve code quality)
   * in PRINT statement:
      - "," means inserting a tab, instead of starting to print at a certain place (too old-fashioned and not practical any more)
      - ";" means to start right after the previous place (same as original BASIC spec), but won't insert a space before a number (programmer
        should be responsible for this when necessary!)


Not yet supported (but will be supported in later versions)
------------------------------------------------------------

   * data type:
      - array (multi-dimensional)
         o array index starts from 0, cannot be specified to another number
         o in 'DIM A(N) AS INTEGER', N is not upperbound, but size of array
      - date
      - time
      - datetime

   * built-in functions
	- some statistical functions
	- some algorithms
	- file I/O
	- other interoperabilities (?)

   * commands
	- INPUT (?)


License
========

This software is licensed under "HSL" (http://www.shandonghan.com/hsl-hans-simple-license). You can use it for free and distribute it freely, but you cannot sell it to others. When there are bugs, please let me know, I will try to fix them.

If you find it useful and want to express your thanks, please help those who need your help, or kindly donate to any of following organizations:

   * WWF ("World Wide Fund For Nature" or "World Wildlife Fund")
   * The Red Cross
   * any organization protecting people, dogs/cats & other wild animals, environment, etc.