MBasic v1.0
-----------


USER'S GUIDE
------------


1. Forewords
2. The language
	2.1. Summary of available keywords
	2.2. Numbers
	2.3. Variables
	2.4. Arithmetic and comparison operators
	2.5. Expressions
	2.6. Statements
	2.7. Program
	2.8. Blanks
	2.9. Error messages
3. The editor
4. The functions
5. Programs commands
	5.1. Variables assignations
	5.2. BEEP
	5.3. CLS
	5.4. COLOR
	5.5. EDIT
	5.6. ELSE
	5.7. END
	5.8. ENDIF
	5.9. FOR
	5.10. GET
	5.11. GOSUB
	5.12. GOTO
	5.13. IF
	5.14. IF THEN
	5.15. INPUT
	5.16. LET
	5.17. LOCATE
	5.18. NEXT
	5.19. POKE
	5.20. PRINT
	5.21. REM
	5.22. RETURN
	5.23. STOP
	5.24. TROFF
	5.25. TRON
	5.26. WAIT
	5.27. WINDOW
6. Direct commands
	6.1. CONT
	6.2. HELP
	6.3. LIST
	6.4. LOAD
	6.5. NEW
	6.6. RUN
	6.7. SAVE
7. Sample programs
	7.1. PITMAN
	7.2. BENCHMARK


1. Forewords
------------

  MBasic is adapted from the original Li-Chen Wang's Palo Alto 8080 TINY BASIC

  The TINY BASIC language was published in the pages of Dr. DOBB'S JOURNAL
  and PEOPLE'S COMPUTER COMPANY in late 1975 and early 1976.

  The TINY BASIC language supported a very limited subset of the
  Dartmouth BASIC language and didn't supported strings.

  This manual uses some parts of original TINY BASIC documentation.

  MBasic ? 

  It's been optimized for 32 bits microprocessors and Windows console environment.
  Other enhancements include the use of an internal line editor, 
  advanced maths functions, extended commands set, shell replacment and more...

  It is small (about 28 Kb. Unpacked PE file).

  It is fast (100% assembly language).

  It is sexy (elected Miss Basic 1923).

  For BASIC programmers, it is efficient and easy to learn.

  For average users, it can acts as an acceptable shell replacment,
  or a powerful scripting language.

  Consider sending bugs, enhancements requests, beer or whatever to:

  Sylvain Bizoirre (original creator of Mini Basic):

    sb@retromatique.com

  Or

  Franck Charlet:

    hitchhikr@australia.edu


2. The language
---------------

  2.1 Summary of available Keywords
  ---------------------------------

    Operators:

	+	-	/	\	*
	=	<	>	<=	>=
	<>

    Direct mode commands:

	CONT	EDIT	HELP	LIST	LOAD
	NEW	RUN	SAVE

    Commands:

	BEEP	CLS	COLOR	ELSE	END
	ENDIF	FOR	GET	GOSUB	GOTO
	IF	IF THEN	INPUT	LET	LOCATE
	NEXT	POKE	PRINT	REM	RETURN
	STOP	TROFF	TRON	WAIT	WINDOW

    Functions:

	{E}	{FALSE}	{PI}	{TRUE}	ABS
	ACOS	ACOSEC	ACOTAN	ASEC	ASIN
	ATN	CHR	COS	COSEC	COTAN
	EXP	FIX	HACOS	HACOSEC	HASEC
	HASIN	HATN	HCOATN	HCOS	HCOSEC
	HCOTAN	HSEC	HSIN	HTAN	IIF
	INKEY	INT	LINE	LOG	LOGN
	PEEK	PEEKL	PEEKW	RND	SEC
	SGN	SIN	SIZE	SQRT	TAN
	TICK

  2.2 Numbers
  -----------

    In MBasic, numbers can be 32 bits unsigned integers
    (range of 0 to 4 294 967 295)
    or standard floating points numbers (double precision).
    Hexadecimal numbers can be used with 0x prefix chars (like in C language).

  2.3 Variables
  -------------

    There are 26 scalar variables donoted by the letters A through Z.
    The one array variable is denoted by '@(I)'.
    Its dimension is originally limited to 2000 cells in source code,
    but it can be extended to hundreds thousands of cells if you really need it.

    Note: Variables and array cells addresses can be obtained with & char
          prefix (like in C language again) adding the ability to use pointers
          and so on.

  2.4 Comparison Operators
  ------------------------

    The following operators are supported:

      /  - floating point divide

      \  - integer divide (fractional results not returned)

      *  - integer multiply

      -  - subtract

      +  - add

      >  - compare if greater than

      <  - compare if less than

      =  - compare if equal to

           Note: Multiple assignment are not supported,
                 i.e., "A=B=O" is interpreted by MBasic as meaning 
                 "compare B against 0 and store result into A"

      <> - compare if not equal to

      >= - compare if greater than or equal to

      <= - compare if less than or equal to

    All compares operations returns 1 if the comparison is true and 0 if false.

  2.5 Expressions
  ---------------

    Expressions are formed with numbers, variables, and functions with arithmetic and
    compare operators between them. + and - signs can also be used at the beginning
    of any element (with the exception of strings).
    The value of an expression is evaluated from left to right,
    except that the * / and \ operators are always given precedence, 
    with + and -, and then the compare operators following, in that order.
    Parentheses can be used to alter the order of evaluation
    in the standard algebraic sense.

  2.6 Statements
  --------------

    A MBasic statement consists of a statement number between 1 and 99999 followed
    by one or more commands (see Commands below). Commands in the same statement are
    seperated by a colon ":".
    If the "GOTO", "STOP", "END", and "RETURN" commands are used then they must be
    the last command in that statement for obvious reasons.

  2.7 Program
  -----------

    A MBasic program consists of one or more statements.
    When the direct command (see Direct Commands below) "RUN" is issued,
    the statement with the  lowest statement number is executed first,
    then the one with the next lowest statement number, etc.
    The "GOTO", "GOSUB", "STOP", "END" and "RETURN" commands
    can alter the instructions sequence.
    Within any statement the execution takes place from left to right.
    The "IF", "IF THEN" and "ELSE" commands can cause remaining commands
    within the same statement to be skipped.

  2.8 Blanks
  ----------

    MBasic statements and commands may use blanks freely, except that numbers,
    command key words, and function names may not have embedded blanks.

  2.9 Error messages
  ------------------

   There are 44 error messages in MBasic.
   When an error is encountered the cause message is printed,
   also mentioning the line number where it occured (not in direct mode).
   Control is then passed to the MBasic editor.

   List of possible errors:

	Syntax error
	Invalid Line number
	Numeric value overflow
	Subscript out of array range
	Out of memory
	TO expected after FOR statement
	Division by zero
	':' or end of line statement expected
	Keyword or variable expected
	'=' statement expected
	Line number not found
	More than 16 GOSUB levels
	RETURN without GOSUB
	Duplicate FOR..NEXT variable
	More than 16 FOR..NEXT levels
	NEXT without FOR
	NEXT variable doesn't match corresponding FOR
	',' statement expected
	Invalid argument
	Variable expected
	File not found
	File too large
	Not a MBasic file
	End of line expected
	Invalid floating point number
	Expressions stack space exhausted
	Error in expression
	Integer value expected
	Illegal char found
	'(' statement expected
	')' statement expected
	Ifs stack space exhausted
	Unexpected statement
	Unexpected end of file
	Command not available in this context
	'"' statement expected
	Argument expected
	Variable or array address expected
	Invalid use of address reference
	Invalid cell reference
	Datas memory overflow
	No argument allowed
	Strings space exhausted
	Numeric value expected


3. The editor
-------------

  MBasic contains a useful line editor for entering and correcting Mini Basic
  programs. Maximum line length allowed is 255 char.
  All editing features of a standard line editor are used:

	- Right and left arrows to go right and left inside the edited line
	- Home and End keys move cursor to top or end of line
	- Del and BackSpace keys cancel a character preceding
	  or following cursor position
        - Insert key switches between normal and insert mode.
          (Insert is the mode by default).
          cursor appearence is modified, depending of the mode used.
        - Alt+num. keys sequence to enter an ASCII code character.

  Statements may be deleted by simply typing their statement number, 
  followed by a CR. Corrections may be verified by typing LIST nn and striking 
  the Escape key to terminate the LIST process (can be paused with space key).


4. The functions
----------------

  {E}
  Returns an approximation of e (2.7182818284590452).

  {FALSE}
  Returns the value 0.

  {PI}
  Returns an approximation of pi (3.1415926535897932).

  {TRUE}
  Returns the value 1.

  ABS(X) 
  Returns the absolute value of expression X.

  ACOS(X)
  Returns the arc cosine of expression X.

  ACOSEC(X)
  Return the arc cosecant of expression X.

  ACOTAN(X)
  Return the arc cotangent of expression X.

  ASEC(X)
  Returns the arc secant of expression X.

  ASIN(X)
  Returns the arc sine of expression X.

  ATN(X)
  Returns the arc tangent of expression X.

  CHR(X)
  Returns the ASCII value of expression X (integer).

  COS(X)
  Returns the cosine of expression X.

  COSEC(X)
  Returns the cosecant of expression X.

  COTAN(X)
  Returns the cotangent of expression X.

  EXP(X)
  Returns e^X.

  FIX(X)
  Returns the integer part of expression X.

  HACOS(X)
  Returns the inverted hyperbolic cosine of expression X.

  HACOSEC(X)
  Returns the inverted hyperbolic cosecant of expression X.

  HASEC(X)
  Returns the inverted hyperbolic secant of expression X.

  HASIN(X)
  Returns the inverted hyperbolic sine of expression X.

  HATN(X)
  Returns the inverted hyperbolic tangent of expression X.

  HCOATN(X)
  Returns the inverted hyperbolic cotangent of expression X.

  HCOS(X)
  Returns the hyperbolic cosine of expression X.

  HCOSEC(X)
  Returns the hyperbolic cosecant of expression X.

  HCOTAN(X)
  Returns the hyperbolic cotangent of expression X.

  HSEC(X)
  Returns the hyperbolic secant of expression X.

  HSIN(X)
  Returns the hyperbolic sine of expression X.

  HTAN(X)
  Returns the hyperbolic tangent of expression X.

  IIF(X,Y,Z)
  Returns Y if X is true or Z otherwise.

  INKEY
  Returns a key press 
  Contrary to GET command, INKEY doesn't wait for the any key to be pressed.

  INT(X)
  Returns the integer part of expression X
  (round negative numbers to lower integer).

  LINE
  Returns last used line number.

  LOG(X)
  Returns natural logarithm of expression X.

  LOGN(X,Y)
  Returns natural logarithm of expression X in base Y.

  PEEK(X)
  Returns the content of 8 bits memory location X in Basic text area.
  (see POKE command for argument details)

  PEEKL(X)
  Returns the content of 32 bits memory location X in Basic text area.
  (see POKE command for argument details)

  PEEKW(X)
  Returns the content of 16 bits memory location X in Basic text area.
  (see POKE command for argument details)

  RND(X)
  Returns a random number between 1 and X (inclusive).

  SEC(X)
  Returns the secant of expression X.

  SGN(X)
  Returns the sign of expression X:

	 1 if positive
	 0 if null
	-1 if negative

  SIN(X)
  Returns the sine of expression X.

  SIZE
  Returns the number of bytes left unused by the program.

  SQRT(X)
  Returns the square root of expression X.

  TAN(X)
  Returns the tangent of expression X.

  TICK
  Returns the number of milliseconds since Windows started.


5. Program commands
-------------------

  MBasic statement commands are listed below with short examples and explanations,
  as i consider you read this note, not to learn Basic language, but to play with ASM.

  5.1 Variables assignations
  -----------------------

    Assign a variable or array cell to a value or expression

	A=234-5*6:A=A/2:X=A-100:@(X+9)=A-1

    Complex and recursive expressions are allowed:

	@((@(A+X)+@((@(12)-B)*X)+5)=((A*5)/@((X/2)+A))

  5.2 BEEP
  --------

	BEEP

    Emits a Beep on internal speaker or a standard Windows alert sound 
    if a sound card is connected.

  5.3 CLS
  -------

	CLS

    CLS clear console screen and sets background and foreground colors with current
    colors values (see COLOR command)

  5.4 COLOR
  ---------

	COLOR X, [Y]

    COLOR command sets the foreground (X) and background (Y) colors for following
    PRINT commands. Arguments range from 0 to 15 and are idendical to standard 
    DOS colors.

    Note: Background color won't be modified if Y parameter is not specified.

  5.5 EDIT
  --------

    EDIT nn command allows to correct an existing MBasic statement. 

  5.6 ELSE
  --------
  
	IF A<B THEN
	PRINT "PRINT THIS STRING IF A<B"
	ELSE
	PRINT "OR PRINT THIS ONE IF A>=B"
	ENDIF
  
    Revert last condition inside a conditional block of command.

    Note: Several ELSE statements can be used within a conditional block
          allowing to add several block epilogues depending of conditions
          verifications states (i know this is not standard but it can be useful).

  5.7 END
  -------

	END
    
    See STOP command.

  5.8 ENDIF
  ---------
  
  	ENDIF
  
    Terminates a conditional block of commands.

  5.9 FOR
  -------

	FOR X=1 TO 10	 	or	FOR X=1 TO 10 STEP 2
	PRINT "Number ";X           	PRINT "Number ";X
	NEXT X                      	NEXT


    The FOR command can include the optional argument 'STEP'.
    Increment must be a positive value. Following exemple is thus not allowed:

	FOR X=10 TO 1 STEP -1

    FOR commands can be nested up to 16 depth levels. 
    That is, one FOR loop can contain other FOR loops with different loop variables.

  5.10 GET
  --------

	GET A

    Get command waits for a key to be typed.
    When it is done, variable following this command assumes the value of key pressed
    (ASCII code for letters/numbers, special code for control keys). 
  
    Note: Execution is halted until a key is pressed.

  5.11 GOSUB
  ----------

	GOSUB 120

    The GOSUB command is used to invoke a subroutine ended with a RETURN command.
    The GOSUB command must be the last command within any given statement. GOSUB
    commands can be nested, up to 16 depth levels.

	GOSUB A*10+B

    Like 'GOTO' command, this form of "computed GOSUB" is allowed and will cause a
    different subroutine to be executed depending upon the value of the expression
    that follows "GOSUB"..

  5.12 GOTO
  ---------

	GOTO 120

    In this example, control is passed unconditionally to statement number 120.
    The GOTO command must appear as the last command in any given statement.

	GOTO A*10+B

    This form of "computed GOTO" is allowed. In this case, control is passed
    to the statement number represented by the expression that follows "GOTO".

  5.13 IF
  -------

	IF A<B X=3:PRINT "THIS STRING"

    The IF command works with the comparison operators (enumerated above) to check
    the validity of the specified comparison condition. If the comparison A<B is true,
    then rest of the commands in the same statement are executed. However, if the
    comparison tests false, then the balance of the commands in the statement are not
    executed and control passes to the statement with the next highest statement number.

    Note: Any expression <>0 is considered to be true.

  5.14 IF THEN
  ------------

	IF A<B THEN X=3:PRINT "THIS STRING"	or	IF A<B THEN
							X=3
							PRINT "THIS STRING"
							ENDIF

    The IF...THEN command declares a conditional block of commands.
    When used as single line (with following statement(s))
    it works like the normal IF command (see above)
    otherwise it must be terminated with a matching ENDIF command.

  5.15 INPUT
  ----------

	INPUT [X], &Y

    The INPUT statement is used to acquire input datas during program execution.
    MBasic will wait for a string or a number to be typed and echoed at the console,
    then the specified variable will assume the value of the appropiate input.
    The INPUT statement will accept expressions as well as numbers as input.

	LOCATE 5,12:INPUT "Enter a value : ",&A

    In this example MBasic will print the string "Enter a value : "
    and wait for user's input.

  5.16 LET
  --------

	LET X=Y

    Performs same operation as a standard variable assignation.

  5.17 LOCATE
  -----------

	LOCATE X, Y, [Z]

    LOCATE command moves the cursor to the horizontal (X) and vertical (Y) position 
    of console screen. Optional argument (Z) makes cursor visible (=1) or hidden (=0)
    In following example, "Hello" text is printed at column 25,
    line 12 of console screen with a visible cursor

	LOCATE 25,12,1:PRINT "Hello"

  5.18 NEXT
  ---------

	NEXT [X]

    The variable specified by the NEXT command is optional. A NEXT without variable
    doesn't perform any loops overlapping control.

  5.19 POKE
  ---------

	POKE A,B

    The POKE command is used to place data B into memory address A which must be
    inside Basic text area limits. This command may be repeated as follows:

	POKE A,B,C,D

    In the above example, data B is placed in memory location A, then data C is placed
    in memory location A+1, then data D is placed in memory location A+2...
    All variables may be expressions.

  5.20 PRINT
  ----------

	PRINT A*3+1;"ABC"

    This form of the PRINT command will print the value of the expression A*3+1
    on the console, followed by the string ABC on the same line. 
  
    Note: Only double quotes (") may be used to denote character strings.

	PRINT A;B;#3;C;D;E;#10;F;G

    This form of the PRINT command demonstrates format control.
    The format character # is used to indicate the number of leading spaces
    to be printed before a number. The default number is 0.
    Once the # format is invoked it is active for the remainder of the statement
    unless overridden by a subsequent format specifier, as in the example.

    Note: ? char is an alias for PRINT command.

  5.21 REM
  --------

    Anything written after a REM command is ignored by MBasic.

    Note: ' char is considered as a REM command as well.

  5.22 RETURN
  -----------

	RETURN

    The RETURN command causes execution to resume at the statement
    that follows the GOSUB that caused the current subroutine to be executed. 
    It must be the last command of any given statement.

  5.23 STOP
  ---------

	STOP

    This command stops the execution of a MBasic program and passes control
    to the MBasic editor. All initialized variables keep their values and can be
    printed for tests or debug. STOP must be the last command in any given statement.

  5.24 TROFF
  ----------

	TROFF

    TROFF command will stop escape key checking performed at every line.
    This will speed up programs execution speed a LOT.

  5.25 TRON
  ---------

	TRON

    TRON command will switch escape key checking on, 

    Note: Every RUN command switch it ON so the program will have
          to explicitely switch if OFF if more speed is required
          and real time breaking isn't required.

  5.26 WAIT
  ---------

	WAIT I

    The WAIT command is used to pause MBasic execution
    for I milliseconds. WAIT command is based on internal computer timer
    and is thus independant of processor speed.

    Note: Wait 0 will flush windows "multi-tasking" environment
          Wait -1 will performs an infinite loop.

  5.27 WINDOW
  -----------

	WINDOW X, Y, [EDIT]

    WINDOW command is used to resize current console window with new horizontal (X)
    and vertical (Y) dimensions mentioned in characters.
    Following example resizes current console window with 40 characters width
    and 25 lines height:

	WINDOW 40,25

    Optional 'EDIT' argument is used alone.
    It resizes current console window with original MBasic editor sizes and colors.

	WINDOW EDIT

    Note: WINDOW command may cause some random error from inside MBasic program
	  or from Windows environment due to the fact that programmer
          cannot decide of characters font size inside a console window.
          After a WINDOW command, characters may be unreadable.
          In this case, you will have to resize window by yourself 
          or modify characters size from 'Auto' to a fixed size in the menu bar.


6. Direct commands
------------------

  Direct commands are those commands that can be invoked by the user only when
  MBasic is in editor mode (in response to the '>' prompt). 
  All statement commands (those listed above) can be invoked while in command mode. 
  Typing Ctrl+C (or Ctrl+Break) while in direct mode or during program execution 
  will causes MBasic to terminate. Control is then passed to Windows Desktop.
  Recall that a statement consists of a number followed by one or more commands. 
  If the number is missing, or if it is 0, the command will be executed immediatly 
  after typing the terminating CR.
  The following commands can be used as direct commands,
  they CANNOT be used as part of a MBasic statement.

  6.1 CONT
  --------

	CONT

    Continue a program after a break. (Restart at last known line).

  6.2 HELP
  --------

	HELP

    Display a summary of available commands and functions.

  6.3 LIST
  --------

	LIST [nnnn]

    The LIST command is used to display the current MBasic program
    on the operator's console. The statements will be listed in numerical order.
    If LIST is followed by an expression (e.g. LIST 200 or LIST LINE)
    the listing will begin with statements following the specified statement.
    LIST can be paused with SPACEBAR or stopped with ESCAPE keys.

  6.4 LOAD
  --------

	LOAD FILENAME

    The LOAD command loads the specified MBasic program from the current disk 
    directory into the Basic text area.
    Any program residing within MBasic prior to the LOAD operation is lost.
    If there's insufficient room for the program, LOAD will return an error message.
    The filetype is assumed to be ".MBI", previously saved with MBasic.
    Files saved with MBasic can be edited only with the internal editor.
    Programs created with an external editor cannot be read by MBasic.

  6.5 NEW
  -------

	NEW

    The NEW command deletes the current program from MBasic's memory
    and erase all variables.

  6.6 RUN
  -------

	RUN

    The RUN command causes execution of the stored MBasic program.
    Execution will begin at the lowest numbered statement and continue until there
    are either no more statements to execute or a STOP/END command is found.
    A long MBasic program may be terminated by typing ESCAPE at the console
    if trace mode is on and/or the program is waiting for user input.
    ESCAPE key will give the control back to MBasic editor.

    Note: A Ctrl+C (or Ctrl+Break) may be typed at any time,
          MBasic will be terminated and control returned to Windows Desktop.

  6.7 SAVE
  --------

	SAVE FILENAME

    The SAVE command saves the current MBasic program in the specified directory
    with the specified FILENAME. The default file extension is ".MBI".
    FILENAME can be of Windows filenames standard.


7. Sample programs
------------------

  Several programs are delivered with MBasic to show off how sexy it is.

  7.1 PITMAN
  ----------

    Author: Sylvain Bizoirre

    Notes from the author:

    I wrote PITMAN in 1984 for the Sharp MZ 80 computer...
    and sold it in compiled version with a good success!
    I forgot it for a long time and recently found it again in an old audio tape.
    At the time I didn't think about structured programming methods,
    but to fit this program in 8 Kb. memory.
    I kept this program intact and just adapted it to MBasic.
    PITMAN is a good example of MBasic capabilities and a real headache for players. 
    If you like this game and create new headache stages,
    don't hesitate to let me know !

  7.2 BENCHMARK
  -------------

    Author: Franck Charlet

    Notes from the author:

    This program was written to test MBasic performances
    with various datas manipulations and instructions decoding.
    I have converted it to various BASICs to measure (and improve) MBasic speed.
    Here are the results i obtained on my P133 machine (average times):

    Tested with:

      IBasic	     - Executable file (Probably PCode).
      MBasic	     - Interpreted (PCode).
      RapidQ	     - Executable file (PCode).
      Visual Basic 4 - Executable file (PCode).
      YaBasic	     - Interpreted (Probably PCode).
      ...More to come...

    Note: 16 bits basics (QB and others) are not concerned here.

    (All results are reported in seconds).

     ---------------------------------------------------------- 
    |                |  FP ops |  FP fncs | Int ops | Int fncs |
    |----------------|---------|----------|---------|----------|
    | IBasic         | ~74.688 | ~195.572 | ~89.628 |  ~84.090 |
    | MBasic         |  ~4.788 |   ~6.302 |  ~8.189 |   ~4.892 |
    | RapidQ         | ~14.752 |  ~20.349 | ~30.424 |  ~17.585 |
    | Visual Basic 4 |  ~1.102 |   ~2.584 |  ~4.036 |   ~3,676 |
    | YaBasic        |  ~8.xxx |  ~13.xxx | ~14.xxx |  ~10.xxx |
     ---------------------------------------------------------- 

    Visual Basic 4 stays unbeatable for that kind of stuffs,
    i do believe it uses somekind of loops cache/optimizations.
    And that fixed functions arguments are not calculated twice.
    (Not yet implemented in MBasic).

------------------------------------------------

Be seeing you...

Sylvain Bizoirre	sb@retromatique.com
Franck Charlet		hitchhikr@australia.edu
