tinybc.1

.TH tinybc 1 "January 30, 2013" "" "Tiny BASIC for Curses"

.SH NAME
tinybc \- Tiny BASIC for Curses

..SH SYNOPSIS
.B tinybc
.RI [OPTIONS]  [FILE]
.br

.SH DESCRIPTION
\fBtinybc\fP is a BASIC interpreter for the curses character screen handling library, which fully corresponds to the Tiny BASIC specification.

The tinybc engine is thread-safe and can be embedded into other code. Embedding may not make sense because of the capabilities of the interpreter, but it makes sense because the code is easily extendable.

It's just an idea i got and quickly implemented, BASIC is not a programming language which i use. I made it for fun and i hope that it would be used for fun, such as a minimalist challenge.

.SH Curses
Curses is a library for using computer interactively in a character mode. It corresponds to the POSIX standard, and is the most cross-platform solution for that purpose. Character mode is the easiest to code, so it is the easiest to feel the computer that way. Terminals of the modern computers provide almost the same "graphics" as some earliest microcomputers, and there are many games with such graphics.

.SH Tiny BASIC
Tiny BASIC is the specification of the most minimal BASIC. Actually there is not much to choose from, because the next smallest specification is the Small BASIC standard, and this does not provide a small language at all. The Tiny BASIC specification was written by Dennis Allison and was published in the People's Computer Company newsletter in December 1975. The specification was necessary because of the need to have a small interpreter which can fit into 2 KB of memory. Tiny BASIC was one of the first programming languages for the microcomputers.

This interpreter is minimal not because it was difficult to add more functionality, adding functionality is surprisingly simple. This interpreter is minimal because it is meant to implement Tiny BASIC. But i think that minimalism enables creatity.

This interpreter is mostly based on the Tom Pittman's Tiny BASIC, except the USR function and using full expressions for input. The Tom Pittman's Tiny BASIC is implemented so completely that the programs written in it run without modifications. The computed GOTO and GOSUB are implemented too, but their expressions would be renumbered when they only consist of a single number. Two additional features are taken from the Palo Alto Tiny BASIC, one big array named @, and using relation operators in expressions. This enables to run programs written in Palo Alto Tiny BASIC with some modifications.

.SH OPTIONS
.IP \fB\-i\fP
Starts the interpreter interactively and loads the file.
.IP \fB\-number\fP
Renumbers the program starting from number.

.SH INSTALL
To compile tinybc in Linux, type make in the terminal. To install tinybc, as root type make install, and to remove the installation, type make remove. The installation also copies the examples to the directory /usr/share/doc/tinybc . To compile tinybc in Windows and DOS, type one of the following depending on your system:

mingw32-make tinybc.exe

make tinybc.exe

make dos

The binaries for Linux and Windows are provided, but because of viruses, etc, it is safer to compile. The program depends only on some version of the curses library. For compiling in Linux, the ncurses development package has to be installed. In Windows, the compiler such as MinGW, and in DOS DJGPP has to be installed. When you install the compiler, add its bin directory to the path. The PDCurses library for Windows is included, in DOS the library in \\pdcurses\\dos has to be compiled. In DOS, tinybc has only been tested in DOSBox, there the files were copied to the directory \\tinybc08 .

The path of the temporary directory should be set to the environment variable TINYBC_TMP , otherwise temporary files shall be stored in the current directory. The path must end with slash or backslash.

.SH LANGUAGE DESCRIPTION
The features such as an array were added in order to make tinybc as advanced as Tiny BASIC, not more advanced. Because in spite that the Tiny BASIC specification provides no arrays, most of the Tiny BASIC interpreters at the time (1976) enabled some memory access, thus providing a data storage similar to array. Such memory access also enabled to read program statements, which could been used to read pre-defined data. In tinybc, assigning strings and lists of expressions to array is provided to compensate the lack of DATA statement in Tiny BASIC.

These interpreters also had an access to input/output port, and they could also send escape sequences to the display. The statements OUT, INKEY, and the other curses statements provide that in tinybc. It was possible to run system functions, any output to paper tape and read any input from paper tape. The input/output redirection, copying and pasting to the terminal and the SYSTEM statement provide that functionality.

Because of the lack of the if and while blocks, Tiny BASIC does not correspond to the modern programming paradigm. Structured programming is nevertheless possible by marking all destinations of jumps with REM statements, such as REM SUBROUTINE DrawPixel (X, Y), REM DO, REM ELSE and REM END IF, and by using empty REM statements for making the code clearer. The original Tiny BASIC had no FOR...NEXT loop, which enables to write code faster, but does not significantly increase the speed of programming.

It is difficult to make the simplest language which is usable for some purposes and which still corresponds to some standard. Adding even a single seemingly simple feature can be enough to make the language not simple or not standard. Making a simple language is a matter of such delicate balance.

.SH Program statements
In statements, all lines must begin with a number. It is not always necessary though that the numbers are different or in a growing order. The line numbers are required because Tiny BASIC is a traditional BASIC. The lines can also be renumbered. See the examples (the files with the bas extension). The LET and THEN keywords can be omitted, the PRINT keyword can be abbreviated as PR.

.IP "\fBCLS\fP"
Clears the screen
.IP "\fBCOLOR expr1, expr2\fP"
Changes the foreground color to expr1 and background color to expr2
.IP "\fBEND\fP"
Ends the execution of the program, can be anywhere in the program
.IP "\fBGOSUB expr\fP"
Executes a subroutine which starts with the number which is the value of the expression, subroutine ends with RETURN
.IP "\fBGOTO expr\fP"
Executes the line with the number which is the value of the expression
.IP "\fBIF expr THEN statement\fP"
Executes statement if the value of the expression is not zero
.IP "\fBINCHAR var1, var2, var3\fP"
Writes the code of the character at the current location into var1, var2 and var3 are for color codes and can be omitted
.IP "\fBINPUT var, ... var\fP"
Inputs variables
.IP "\fBINKEY var\fP"
Inputs a key code, -1 if no keys pressed
.IP "\fBLET var = expr\fP"
Assigns an expression to variable
.IP "\fBLET @(expr) = string|expr, ... string|expr\fP"
Assigns the expressions and characters from strings to consecutive array elements
.IP "\fBLOCATE expr1, expr2\fP"
Moves cursor to line expr1 and column expr2, the next PRINT prints to that location
.IP "\fBNAP expr\fP"
Sleeps the expr of milliseconds, a NAP statement should be in the main loop to give time for the operating system
.IP "\fBOUT expr\fP"
Prints a character, the code of which is the expression
.IP "\fBPRINT string|expr, .... string|expr\fP"
Prints the strings and expressions, ; allowed
.IP "\fBREM comment\fP"
Any text can be written after REM as a comment
.IP "\fBRETURN\fP"
Ends the subroutine block and executes the line after the calling GOSUB statement
.IP "\fBSYSTEM expr1, expr2\fP"
Filters the text in array starting at expr2 through the external command starting at expr1, both end with 0

.SH Interactive mode
Interactive mode enables to both edit and run the program. Interactive mode is a part of the Tiny BASIC specification, so it has to be implemented in every language which is claimed to be Tiny BASIC. The HELP statement is added. LOAD and SAVE are also additional statements which are not in the Tiny BASIC specification. In the early computers they used teletypes as terminals, so there was no difference whether the input or ouput was done with a typewriter, or with a punched tape.

As it is the tradition in BASIC, the first character can be written instead of the full keyword.

If you write a line which starts with a number, then this is considered to be a program line and it will be added to to program to the appropriate place. If the number is the number of an existing statement, then this statement will be replaced with the statement which you entered. If the line consists only of a number with no additional text, then the statement with that number shall be deleted.

.IP "\fBCLEAR\fP"
Deletes the program
.IP "\fBLIST\fP"
Lists the whole program
.IP "\fBLIST line\fP"
Lists the line
.IP "\fBLIST line1-line2\fP"
Lists program from line1 to line2
.IP "\fBLOAD filename\fP"
Loads program from file
.IP "\fBQUIT\fP"
Exits
.IP "\fBRUN\fP"
Runs the program
.IP "\fBSAVE [filename]\fP"
Saves the program
.IP "\fBHELP\fP"
Prints help

.SH Variables
There is no separate memory allocated for variables in tinybc, all memory remaining in the program buffer after the program can be used as data. The first 26 * 4 bytes of it is used for variables, and the rest is used for array. All the data space is filled with zeroes in the beginning of running the program, so one can consider that the initial values of all variables and array elements are 0.

There are 26 variables in Tiny BASIC, the names of which are the upper case letters A--Z. Variables are integers, but these are quite long integers with up to 10 decimal places. This enables to do real number calculations assuming that the point is somewhere in the middle of the number.

As in Palo Alto Tiny BASIC, there is one big array named @, the size of which is all memory in the program buffer remaining from the program and variables. As in 68000 Tiny BASIC, array elements are 32 bit integers the same as variables.

.SH Expressions
The order of calculations is natural (multiplications, etc. first).

One constant named SIZE can be used in expression. This is taken from the Palo Alto Tiny BASIC. The value of that constant is the memory remaining in the program buffer, the maximum size of the @ array is thus SIZE/4.

One function, RND(expr) , can be used in expression. This function generates a random number. Example: assign to the variable N a random number in the range 1 to 10:

10 N = RND(10) + 1

Expressions can contain variables, numbers, and the following operators:

.IP "\fB+\fP"
Addition
.IP "\fB-\fP"
Subtraction
.IP "\fB*\fP"
Multiplication
.IP "\fB/\fP"
Division
.IP "\fB()\fP"
Parentheses, the expression in parentheses is calculated first

.SH Relations
The elements of a relation are expressions. The relation operators can also be used in expressions, with the lowest priority. This enables the expressions like (A > B) * (A < C) , where * and + are used as and and or, correspondingly. The relation operators are the following:

.IP "\fB<\fP"
Less
.IP "\fB<=\fP"
Less or equal
.IP "\fB>\fP"
Greater
.IP "\fB>=\fP"
Greater or equal
.IP "\fB=\fP"
Equal
.IP "\fB<>\fP"
Not equal

.SH Colors
Most terminals support 8 colors, so currently 8 colors are allowed (colors 0--7). The combination of foreground and background color provided in the color statement is called a color pair. The number of color pairs is restricted and the maximum number depends on your terminal. A typical terminal allows 64 color pairs. When you try to use one color combination more than your terminal allows, the color shall not change. The curses colors are not the best possible and they can be re-defined in the code, but they are the only standard colors, so currently the colors are the original curses colors. 

.SH Strings
Strings are sequences of characters between quotation marks in the program text. For example "Hello World!" in the following statement is a string:

10 PRINT "Hello World!"

You have to set your terminal encoding to IBM850, which is the MS-DOS encoding, to be able to print the pseudographics characters. The explanation why it is implemented like that is rather technical. You  can print ASCII characters in any encoding.

You may have to use a NAP statement before PRINT or OUT statements, in a bigger loop. To make sure that the previous graphics operation is finished, otherwise the output may be weird in some terminals. For maximum output speed the screen is refreshed only when line feed is printed, the input statements and NAP statement also refresh the screen.

.SH Running
Tiny BASIC programs can run both in the interactive mode and from the command line. Because programs which use Curses can write everywhere on the screen, the screen is cleared when the program terminates. Therefore remember to press any key when the program is finished, to go back to command line. This enables to always see the result of the program.

When the program asks for input, both numbers and variable names can be entered. In case of variable names, the corresponding input would be the value of the variable.

If a program provides no means to exit normally, ctrl-c should do that harmlessly to the operating system and to the terminal (but not to your BASIC program). In Windows, the key for interrupting the program is ctrl-break, the break key is a key in the upper right corner of the keyboard, with "Pause" written on it. In DOSBox, ctrl-f9 exits the DOSBox at any time.

In Windows, Wordpad can be used to edit programs written in Linux, don't use Notepad or a word processor for that purpose. When copying Windows text files to Linux, they must be converted with tr -d '\\r' or with a text editor. Input and output redirection works with curses, also it is possible to copy from the terminal and paste to the terminal.

.SH Troubleshooting
If the program exits abnormally, like when you happen to divide by zero, it may happen that your terminal settings would be changed. It depends on your terminal how to restore the default settings. Running a tinybc program that exits normally can restore the settings. But if nothing else helps, closing the terminal and running it again shall always restore the settings, as running tinybc does not change anything permanently.

The debug mode can be switched on by defining the DEBUG symbol in Makefile and compiling. When the debug mode is on, the debug messages shall be written to log file. This information is verbous though, so avoid too much looping when debugging.

.SH LICENSE
LGPL

.SH AUTHOR
Tarvo Korrovits

.SH BUGS
Send to tkorrovi@mail.com