tinybc(1)                    Tiny BASIC for Curses                   tinybc(1)



NAME
       tinybc - Tiny BASIC for Curses

       tinybc [OPTIONS][FILE]


DESCRIPTION
       tinybc  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 inter-
       preter, but it makes sense because the code is easily extendable.

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


Curses
       Curses is a library for using computer  interactively  in  a  character
       mode. It corresponds to the POSIX standard, and is the most cross-plat-
       form 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.


Tiny BASIC
       Tiny  BASIC  is  the  specification of the most minimal BASIC. Actually
       there is not much to choose from, because the next smallest  specifica-
       tion  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  microcomput-
       ers.

       This  interpreter  is  minimal not because it was difficult to add more
       functionality, adding functionality is surprisingly simple. This inter-
       preter  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  rela-
       tion  operators in expressions. This enables to run programs written in
       Palo Alto Tiny BASIC with some modifications.


OPTIONS
       -i     Starts the interpreter interactively and loads the file.

       -number
              Renumbers the program starting from number.


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 com-
       piled.  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.


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 pro-
       viding 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 past-
       ing to the terminal and the SYSTEM statement provide  that  functional-
       ity.

       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.


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.


       CLS    Clears the screen

       COLOR expr1, expr2
              Changes  the  foreground  color to expr1 and background color to
              expr2

       END    Ends the execution of the program, can be anywhere in  the  pro-
              gram

       GOSUB expr
              Executes  a subroutine which starts with the number which is the
              value of the expression, subroutine ends with RETURN

       GOTO expr
              Executes the line with the number which  is  the  value  of  the
              expression

       IF expr THEN statement
              Executes statement if the value of the expression is not zero

       INCHAR var1, var2, var3
              Writes  the  code  of the character at the current location into
              var1, var2 and var3 are for color codes and can be omitted

       INPUT var, ... var
              Inputs variables

       INKEY var
              Inputs a key code, -1 if no keys pressed

       LET var = expr
              Assigns an expression to variable

       LET @(expr) = string|expr, ... string|expr
              Assigns the expressions and characters from strings to  consecu-
              tive array elements

       LOCATE expr1, expr2
              Moves  cursor  to  line  expr1  and column expr2, the next PRINT
              prints to that location

       NAP expr
              Sleeps the expr of milliseconds, a NAP statement  should  be  in
              the main loop to give time for the operating system

       OUT expr
              Prints a character, the code of which is the expression

       PRINT string|expr, .... string|expr
              Prints the strings and expressions, ; allowed

       REM comment
              Any text can be written after REM as a comment

       RETURN Ends  the subroutine block and executes the line after the call-
              ing GOSUB statement

       SYSTEM expr1, expr2
              Filters the text in array starting at expr2 through the external
              command starting at expr1, both end with 0


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  imple-
       mented  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 appro-
       priate 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.


       CLEAR  Deletes the program

       LIST   Lists the whole program

       LIST line
              Lists the line

       LIST line1-line2
              Lists program from line1 to line2

       LOAD filename
              Loads program from file

       QUIT   Exits

       RUN    Runs the program

       SAVE [filename]
              Saves the program

       HELP   Prints help


Variables
       There is no separate memory allocated for variables in tinybc, all mem-
       ory 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  inte-
       gers the same as variables.


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 gen-
       erates a random number. Example: assign to the variable N a random num-
       ber in the range 1 to 10:

       10 N = RND(10) + 1

       Expressions can contain variables, numbers, and  the  following  opera-
       tors:


       +      Addition

       -      Subtraction

       *      Multiplication

       /      Division

       ()     Parentheses, the expression in parentheses is calculated first


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:


       <      Less

       <=     Less or equal

       >      Greater

       >=     Greater or equal

       =      Equal

       <>     Not equal


Colors
       Most terminals support 8 colors, so  currently  8  colors  are  allowed
       (colors  0--7). The combination of foreground and background color pro-
       vided in the color statement is called a  color  pair.  The  number  of
       color pairs is restricted and the maximum number depends on your termi-
       nal. 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 cur-
       rently the colors are the original curses colors.


Strings
       Strings are sequences of characters between quotation marks in the pro-
       gram  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 expla-
       nation 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 max-
       imum output speed the screen  is  refreshed  only  when  line  feed  is
       printed,  the  input  statements  and  NAP  statement  also refresh the
       screen.


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.  There-
       fore 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 DOS-
       Box 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 termi-
       nal.


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 Make-
       file 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.


LICENSE
       LGPL


AUTHOR
       Tarvo Korrovits


BUGS
       Send to tkorrovi@mail.com




                               January 30, 2013                      tinybc(1)