DOCUMENTATION.md

Welcome to MiniBASIC

MiniBASIC is a classic BASIC interpreter with these design goals:

1. Compatible with 1980s-era code listings, books, and magazines, including such beautiful and fun gems as the classic Usborne BASIC Programming Books.

2. Friendly and easy to use, with features like input history (just press up-arrow!) and modern line-editing.

3. A powerful virtual retro computer, with full-color 960x640 resolution graphics and sound, that runs on any modern desktop machine.

That last design goal is achieved by running MiniBASIC on Mini Micro, a powerful neo-retro virtual computer. (If you like what you can do in MiniBASIC, you will love what you can do in Mini Micro's native language of MiniScript!)

Overview

• There is always exactly one (possibly empty) program in memory at a time.
• Every line of a program must begin with a line number.
• Programs are created or edited by typing lines (starting with the line number) at the prompt. Typing a line number alone deletes that line.
• The current program is listed with LIST, or to see only REM (remark) lines, use LISTREM.
• The current program may be saved with SAVE, loaded with LOAD, and cleared with NEW.
• Commands and identifiers are case-insensitive. (E.g., xvelocity, XVelocity, and xVeLoCiTy are all the same variable.)
• Variable names ending in $ are strings; any others are numeric.
• Scalar variables do not have to be declared; they are created upon assignment. Array variables are declared with DIM or REDIM.
• Variable names of one or two letters exist automatically, even if not assigned to; numeric variables have a default value of 0, and string variables have a default value of empty string. This includes arrays: one- or two-letter arrays, if not DIM or REDIM'd, exist as one-dimensional arrays with a dimension of 10.
• Variables more than two letters long do not exist unless assigned to (for scalars) or declared with DIM/REDIM (for arrays).
• All variables are global.
• Arrays may be of any dimension, and are indexed with parentheses, e.g. N(4) or A$(42). Valid array indexes are from 0 up to (and including) the size given in the DIM or REDIM statement.

BASIC Functions

The following built-in functions are available in MiniBASIC. These must be used as an argument to a command, or as part of some larger expression.

Function	Result
ABS(n)	absolute value of n
ASC(a$)	Unicode code point of the first character in a$; inverse of CHR$
ATN(n)	arctangent of n radians; inverse of TAN
CHR$(n)	character with the Unicode code point n; inverse of ASC
COS(n)	cosine of n radians
EOF(n)	return whether file handle n is at end-of-file
EXP(n)	e^n
FIX(n)	integer portion of n, i.e., whole number neighboring n closest to 0
INKEY$(z)	pulls and returns the first character waiting in the keyboard buffer, if any, else returns ""
INT(n)	next integer equal to or less than n (generally called floor in other languages)
INSTR([start,] a$, b$)	1-based index of substring b$ within a$, optionally starting at start; 0 if not found
LEFT$(a$, n)	leftmost n characters of string a$; see also MID$, RIGHT$
LEN(a$)	length of (i.e. number of characters in) a$
LOWER$(s)	string s converted to lowercase; see also UPPER$
MID$(a$, n [, m])	substring of a$ starting at n and containing up to m characters; if m is not specified, returns the rest of a$
PIXEL(x,y)	returns the color of the graphics layer at pixel x, y, as a number 0-15 corresponding to the COLOR palette; returns -1 if pixel color is not in the palette
PIXEL$(x,y)	returns the color of the graphics layer at pixel x, y, as an HTML color string, e.g. "#00CC55"
POS(n)	when n is even, returns the current text cursor column; when odd, returns text cursor row
RIGHT$(a$, n)	rightmost n characters of string a$; see also LEFT$, MID$
RND(n)	when n is >= 0, returns a random number from 0 to 1; when n < 0, seeds the random number generator
SGN(n)	sign of n, i.e. 1 if n > 0, -1 if n < 0, and 0 if n = 0
SIN(n)	sine of n radians
SPACE$(n)	a string composed of n space characters
SPC(n)	immediately prints n space characters, then returns ""
SQR(n)	square root of n
STR$(n)	converts number n into a string using standard formatting
TAB(n [, m])	given both n and m, moves text cursor to row m, column n; given only n, advances the text cursor to column n only if it is currently less than that; returns ""
TAN(n)	tangent of n radians
TIME(n)	for n=0, time in seconds since system start; n=1, time since current run
UPPER$(a$)	string a$ converted to uppercase; see also LOWER$
VAL(a$)	converts a$ to a number, if possible; else 0

BASIC Commands

The following table lists all MiniBASIC commands. A command is used as a statement on its own, either in immediate mode or as part of a program line; it may not be used as part of a larger expression.

Command	Effect
BREAK	halts the program and reports the line number (for debugging purposes)
CLEAR	clears all variables from memory (but leaves program intact)
CLOSE fileNum	closes a file previously opened with OPEN
CLS	clears the screen (both text and graphics); resets the text cursor to row 1, column 1; and resets the plot point to 0,0; HOME is a synonym
COLOR x	if x is a number, sets text and graphic color to palette color x (0-15); if a x is a string, sets text and graphic color to that HTML color (e.g. "#FF000088" for transparent red)
DATA list	defines a comma-separated list of data for use with READ and RESTORE. Data elements may be strings or numbers; strings must be enclosed in quotes if they contain spaces or punctuation
DEF FN name(n) = expr	define a user-defined function; subsequent use of FN name(n) will be evaluated as expression expr, with the actual value substituted for n
DIM name(n [,m ...])	declares an array with valid indexes from 0 to n inclusive, or a multidimensional array with additional dimensions m, etc. Array will be numeric unless name ends in $, in which case it is a string array. Throws an error if name is already in use as an array.
ELLIPSE [x1, y1 TO] x2, y2	draws or fills an ellipse from x1, y1 (or the current plot position) to position x2, y2 in the current COLOR, and updates the plot position to x2, y2
END	halts the current program and returns to the MiniBASIC prompt; STOP is a synonym
FILL [ON|OFF]	turns fill mode ON or OFF, controlling behavior of subsequent RECT, ELLIPSE, or POLY command
FOR var = n TO m [STEP s]	begins a FOR loop running from n to m, steps of s (default 1)
GET var	waits for a keypress to appear in the keyboard buffer, then returns it. If var is a string variable, returns the character pressed; if it is a numeric variable, returns the ASC value of the character pressed
GOSUB lineNum	pushes the next statement onto the RETURN stack, then jumps to line lineNum
GOTO lineNum	jumps to line lineNum
HOME	clears the screen (both text and graphics); resets the text cursor to row 1, column 1; and resets the plot point to 0,0; synonym for CLS
HTAB n	moves the text cursor to column n (1-68); see also VTAB
IF expr THEN result1 [ELSE result2]	if expr is true (nonzero), then do result1, which may be either a line number to jump to, or one or more statements joined by :; otherwise jump to result2 if specified, or the next line. If statements may be nested.
IMAGE path$, [x1, y1 TO] x2, y2	draws an image found on disk at path. If given only x2, y2, draws the image at its native size and centered on that point; if given four coordinates and/or TO, then stretches the image as needed to fit the rectangular area given; updates the plot position to x2, y2 in either case
INPUT [prompt, ] var [, var2 ...]	prints "?" if no prompt specified, or if prompt is followed by ;; then waits for the user to enter a value to be stored in var (or several values, separated by whitespace or commas, to be stored in var, var2, etc.). Note that when reading into a string variable, input stops at a comma unless it is the last variable in the input list, in which case it reads all the way to the line break
[LET] var = expr	assigns the value of expr to the variable var, which must be of the same type. Note that LET is optional
LINE [x1, y1 TO] x2, y2	draws a line from x1, y1 (or the current plot position) to position x2, y2 in the current COLOR, and updates the plot position to x2, y2
NEXT [var [, var2 ...]]	increments the nearest or specified FOR loop variable and jumps to the top of the loop, unless that loop is complete, in which case it advances to the next specified variable or the next statement
ON expr GOTO lineNum1, lineNum2, ...	jumps to the line number corresponding to the (floored) value of expr, starting at 1 for lineNum1, etc. If expr evaluates to less than 1 or more than the number of line numbers given, control proceeds to the next statement
OPEN fileNum, [mode,] path	opens a disk file for reading/writing. mode may be a number: 0 to read, or 1 to write; or it may be a standard mode string. fileNum must be a nonzero number that's not already in use. See the File I/O section at bottom for more detail
PEN size	changes the pen sized used with PLOT and LINE, as well as RECT, ELLIPSE, and POLY when FILL is OFF; value must be >= 0
PLOT x, y	plots pixel x (0-959, measured from left side of screen) by y (0-639, measured from bottom of screen) in the current COLOR, and sets the plot position used with subsequent drawing; may also take arrays to plot multiple points
POLY x(), y()	draws or fills a polygon defined by arrays x() and y(), updating the plot position to the last point in the arrays
PRINT [expr, expr, ...]	prints zero or more expressions to the text display. Expressions may be separated by ,, ;, or whitespace; a , will print a comma, while ; or whitespace results in no additional space printed. If the list of expressions does not end with ,, ;, or TAB(), then a line break is printed after the last expression. PRINT may be abbreviated ?
READ var [, var2, ...]	reads the next DATA term into the given variable. Any number of variables may be specified, separated by ,, to be read in order. Generates an error if there is insufficient DATA left to be read. See also RESTORE
RECT [x1, y1 TO] x2, y2	draws or fills a rectangle from x1, y1 (or the current plot position) to position x2, y2 in the current COLOR, and updates the plot position to x2, y2
REDIM name(n [,m ...])	declares an array with valid indexes from 0 to n inclusive, or a multidimensional array with additional dimensions m, etc. Acts just like DIM except that it does not throw an error if the array already exists; in such a case, the previous data is lost as the new array is always cleared
REM text	creates a "remark" or comment in the program; any text between REM and the line break is ignored by MiniBASIC. Note that if REM is the first statement on a line, then it will be included in the output of the LISTREM command
RESTORE [lineNum]	resets the DATA pointer (i.e., the next datum read by the READ command) to the first DATA at or after the given lineNum, or if no line number is given, then the first DATA in the program
RETURN	pops the most recent program location off the RETURN stack (as set by GOSUB), and jumps to that location
SOUND [freq, dur, vol, wave]	synthesizes a sound with the given parameters: frequency, in Hz if > 0 or in negative MIDI note numbers if <= 0 (default 440 Hz); duration in seconds (default 0.5); volume 0-1 (default 1), and waveform (0=sine, 1=triangle, 2=sawtooth, 3=square, 4=noise, default 1). Sound is played asynchronously. Frequency and volume may be given an array (with no index, e.g. F()) instead of a scalar value; in this case, the sound interpolates over the values in the array linearly over the duration of the sound
STOP	halts the current program and returns to the MiniBASIC prompt; synonym for END
VTAB n	moves the text cursor to row n (1-25, with 1 at the top); see also HTAB
WAIT [n]	pauses the program for n seconds (default 1) before proceeding with the next statement

Shell Commands

At the > interactive prompt, you may type and execute BASIC code immediately; or enter lines of code; or use one of the following shell commands, which are only usable at the prompt (i.e. not in a program).

Command	Effect
CAT[ALOG]	list contents of the current directory; synonym for DIR
CD path	change the current directory to the given path. Path separators are /; use .. to go up a level
DIR	list contents of the current directory; CAT and CATALOG are synonyms
EDIT lineNum	put cursor at end of line lineNum so you can edit it
LIST [from - to]	list the current program, or some range of line numbers; from or to may be omitted to list from the beginning or to the end of the program, respectively
LISTREM [from - to]	similar to LIST, but shows only lines that begin with REM
LOAD path	load the BASIC program at path relative to the current directory (.bas extension may be omitted)
NEW	clear the current program and all variables
PWD	print working directory (i.e., path to the current directory)
RENUMBER from - to TO newStart [STEP step]	renumber lines in the range from to to, so that they now start at newStart and increment by step
RUN	reset DATA pointers and all variables, then run the current program from the beginning
SAVE [path]	save the current program to path relative to the current directory (.bas extension may be omitted); if path is omitted, saves to the previous program path, if any

Note that parsing of the file path argument for the shell commands is different from parsing for other BASIC statements; everything after the command, up to : or the end of the line, is taken as a single string argument. This lets you use commands like cd ../CC or load ../../demo/fern without having to enclose the file name/path in quotes. (However, if a file name actually includes a colon, then you will need to enclose the whole name or path in quotes.)

Special Topics

Line Editing

At the shell prompt or at any input prompt, the following editing keys are available:

• use Control-A/Control-E or Home/End to jump to the beginning/end of the line
• press Backspace to delete, or Delete to forward-delete
• hold Alt (or Option on Mac) to move or delete by whole words.

Graphics

MiniBASIC features a high-resolution, 960x640 pixel full-color graphics display layer under the text layer.

Please see the program demo/drawing for examples of how to use the drawing commands (PLOT, LINE, RECT, ELLIPSE, POLY, and IMAGE).

Sound

MiniBASIC supports a sophisticated synthesized sound system, including four different waveforms, and the ability to interpolate pitch and/or volume over the course of a sound. All sounds are played asynchronously.

Please see the program demo/sounds for examples showing use of the SOUND command.

File I/O

To write data to disk, follow these steps:

1. Open the file with a command like OPEN n, 1, "path/to/file.txt". n here is any nonzero number that is not already in use for some other open file. The second parameter, 1, is equivalent to "w" and means to clear the file (if it exists) and prepare it for writing. You may also specify "a" to append to the end of a file, or some other mode listed here.
2. Write to the file with PRINT# n, "some data". This version of the PRINT command uses all the same syntax and rules as normal PRINT, but its output is directed to file n instead of to the screen.
3. Close the file with CLOSE n.

To read data from disk, follow these steps:

1. Open the file with a command like OPEN n, 0, "path/to/file.txt". Again, n is any nonzero number that is not already in use for some other open file. The second parameter, 0, means to open the file in "r" (read) mode; you may also use other modes listed here.
2. Read from the file with a command like INPUT# n, A$. This INPUT# command is just like the standard INPUT command, except that any prompt string is ignored, and input is read from the file rather than from the console. Note that both end-of-file and a blank line will store "" in the given string variable (you can tell the difference with EOF(n)). OR,
3. Read a single character from the file with a command like GET# n, A$. If we are at end-of-file, then GET# stores empty string into the given string variable. If given a numeric variable, then at the end of file the value stored is -1.
4. Close the file with CLOSE n.