|
|
SnailBASIC Manual
This is the manual for the SnailBASIC interpreter for My4TH and My4TH light.
SnailBASIC was written in December 2024 by Dennis Kuschel, dennis_k@freenet.de
DESCRIPTION
SnailBASIC is a basic interpreter for My4TH and My4TH light. It is very similar
to TinyBasic, which was originally developed by Dennis Allison in 1975.
TinyBasic had only a few instructions, which were PRINT, IF, THEN, GOTO, GOSUB,
INPUT, RETURN, LET, CLEAR, LIST, RUN and END. It was an integer-only Basic,
working with 16-bit integers. Strings and arrays were not supported. SnailBASIC
is also a 16-bit integer Basic, but it has a few more instructions then the tiny
original, and it supports strings.
In addition to the basic commands of the original tiny Basic, SnailBASIC has
these commands and functions:
NEW, OLD, FOR, TO, NEXT, STEP, POKE, PEEK, LOAD, SAVE, DIM, REM,
FRE, LEN, ASC, CHR$, MID$, IN, OUT
SnailBASIC also has rudimentary string support, and it supports the colon to
write more Basic commands in one line. And it is not necessary to write "THEN
GOTO 20" - the GOTO can be omitted.
SnailBASIC is a 5K Basic - this is comparable to the 3K Basic's of the early
days. This is because My4TH is a RISC machine, and many simple instructions are
needed to reach the goal. The machine code is somewhat longish compared to code
for the 6502 or similar CPUs of that era. For maximum performance, SnailBASIC is
not written in Forth, but in pure Assembler.
INSTALLATION
SnailBASIC comes as a loadable binary module for My4TH and My4TH light. The
module has a size of 5 KB or 5 Forth blocks. To install it on your My4TH
computer you need the my4th transfer tool for the PC and a serial connection
between the two computers. I recommend to install SnailBASIC in blocks 2 to 7 in
the EEPROM. This is the command you need to enter on the PC:
$ my4th write /dev/ttyS0 binary 2 snailbasic.bin
Of course, you will need to change the name of the serial port according to your
setup, and on a Windows machine you would write com1 instead of /dev/ttyS0.
To start the Basic interpreter, type
2 bload
at the Forth prompt. After a short while you will be greeted with the Basic
interpreter prompt.
AUTOSTART
It is possible to configure My4TH to start SnailBASIC right after power up.
If you want to have Basic as your default programming language, restart your
My4TH computer and type
0 edit
at the Forth prompt. The Forth editor will now show you the contents of the
first block in the EEPROM. If the screen shows only garbage characters, press
[C] and [ENTER] to clear the screen. After the screen is cleared, press [1] and
[ENTER] to edit the uppermost line. Now type [1], so that only the number 1
stands at the beginning of the line. Press [ENTER] and then [W] and [ENTER]
again to save the block back to EEPROM.
This modification enables the autostart mechanism. The next time My4TH is
powered on, the computer will attempt to execute Forth words from EEPROM block
1. Now you have to put the command that starts SnailBASIC into block 1. Back at
the Forth prompt, type
1 edit
to edit block 1. Again, press [C] and [ENTER] to clear the screen. Press [1] and
[ENTER] to edit the uppermost line. Write this into the line:
2 bload
Press [ENTER], and then press [W] and [ENTER] again to save the block back to
EEPROM. If you now reset your My4TH computer, it will boot into Basic.
It is also possible to automatically start a Basic program that you have
previously stored in the EEPROM. To enable autostart of a Basic program, add the
first block number of your Basic program in the EEPROM to the command in block 1
as follows:
8 value as 2 bload
These Forth commands create the new variable "as" that is set to 8, which is the
block where the basic program is stored (of course you have to insert your
appropriate block number here). When the Basic interpreter starts, it looks for
this variable. If the variable is defined, the Basic program is loaded and run.
COMMANDS
PRINT expression list
Prints the specified expression. The expression can consist of text strings,
string variables, integer variables, or expressions that evaluate to integers.
Expressions can be separated by a semicolon or a comma. If a comma is used,
SnailBASIC will move the cursor to the next print window by outputting a TAB
character (ASCII character 0x09). If the PRINT command is not terminated with a
semicolon, the cursor is moved to the beginning of the next line.
GOTO line number
Continues the execution of the programme on another line. GOTO also accepts a
variable instead of a line number, allowing GOTO to jump to pre-calculated
lines. To increase speed, GOTO does not evaluate an expression directly.
GOSUB line number
Calls a subroutine. As with GOTO, the program execution continues on another
line in the program. The position of the GOSUB is remembered on the call stack,
so a RETURN will bring the program back to the statement following the GOSUB.
Like GOTO, GOSUB also accepts a variable as parameter.
RETURN
Return from a subroutine. Program execution returns to the statement following
the GOSUB which called the present subroutine.
IF expression THEN statement
Conditional execution. If the expression evaluates to true, then the statement
is executed. The statement can be a basic command or a line number, so there is
no need to use the GOTO command to continue program execution on another line.
The supported operators for the condition are =, <>, < and >.
INPUT "question"; variable
Asks the user for input from the console. An optional question (enclosed in
quotes and terminated by a semicolon) is printed to the console, prompting the
user to enter a number or string. If no question is given, at least a question
mark is printed to inform the user that some input is expected. The input is
stored in the ineger or string variable.
END
Terminates program execution.
LET variable=expression
Assigns a value, the result of expression, to a variable. Variable must be a
single letter. A..Z are used for integer variables, and A$..Z$ are used for
strings. Expression must evaluate to an integer in the range -32768 to 32767.
The LET word is optional, assignments can be made without it.
REM comment
Basic commands after the REM word are not executed, so this space can be used
for comment text. To avoid tokenizing the comment, the comment text can be
enclosed in quotation marks.
CLEAR
Deletes all string variables and sets all integer variables to zero.
NEW
Clears all Basic memory. A stored Basic program is deleted and all variables are
reset to their uninitialized state (see CLEAR command).
OLD
Restores a Basic program stored in memory. This command reverses the effect of
the NEW command, except that variables remain cleared. This command is useful
after a hard reset of the My4TH computer to restore a Basic program that is
still present in the RAM.
LIST from – to
Lists the Basic program in memory. The parameters are optional; if none are
specified, the entire program is listed. Possible formats for the LIST command
are:
LIST lists the entire program
LIST 50 lists only program line 50
LIST -100 lists all lines up to line 100
LIST 300- lists all lines with line number 300 and above
LIST 100-300 lists all lines with line numbers from 100 to 300
RUN line number
Starts the execution of a Basic program stored in memory. If RUN is called
without parameter, execution starts with the lowest numbered line. Otherwise,
the program execution starts with the line given as parameter.
FOR expression TO limit STEP increment
Begins a FOR-loop. The STEP word is optional and can be omitted. Examples:
FOR i = 100 TO 200 increments i by 1 in every iteration
FOR a = 0 TO 50 STEP 5 increments a by 5 in every iteration
NEXT variable
Marks the end of the part of the program started by the FOR command. For better
code readability, the loop variable used can be written after the NEXT command,
but this is optional. Program execution continues with the command immediately
following the FOR command. This example prints out 10 stars:
FOR i = 1 to 10 : print"*"; : NEXT
POKE address, value
Writes an 8-bit value to the memory location specified by address.
PEEK( address )
Returns the 8-bit value stored at the memory location specified by address.
LEN( string )
Returns the length of the string. The string can be either an immediate string
or a string variable.
DIM string variable ( size )
Defines the size of a string variable. Note that DIM cannot be used to set the
dimension of arrays because arrays are not supported by SnailBASIC.
Important: If string variables are used before they are DIM'd, they are set to
the maximum size of 255 bytes by default. This will exhaust memory very quickly,
especially on the My4TH light computer.
FRE( 0 )
Returns the amount of free Basic program memory in bytes.
ASC( string )
Returns the ASCII value of the first character in the string.
CHR$( value )
Converts the value (range 0 to 255) to a one character long string. The value
is the ASCII code of the character.
MID$( string, start, len )
Derives a new string from an existing string. The new string starts with the
character at the "start" position in the string and has a total length of "len"
characters. For example, if start is 1 and len is 5, MID$ will return a string
containing the first 5 characters of the source string.
OUT value
Outputs a value on the digital output port (8 bits on My4TH, 2 bits on My4TH
light). On My4TH light bit 0 of the output port is connected to the TxD line and
to the LED, so the OUT command can be used to control the light (use OUT 3 to
switch the LED on and OUT 2 to switch it off).
IN( 0 )
Returns the value of the digital input port (8 bits on My4TH, 1 bit on My4TH
light)
SAVE block
Stores a Basic program in the EEPROM memory. The block parameter is the first
block in the EEPROM used to store the basic program. One block is 1 KB in
size. If the Basic program does not fit into one block, more blocks are used
until the entire program is stored. While saving, the SAVE command prints out
the numbers of all the blocks used.
LOAD block
Loads a Basic program from EEPROM memory into RAM. The block parameter specifies
the beginning of the Basic program in the EEPROM.
Attention! You should not load programs on My4TH light that are larger than one
block! Loading larger programs will cause your computer to crash because memory
areas that are important for the operation of the computer will be overwritten.
EXPRESSIONS
SnailBASIC supports the basic arithmetic expressions with the standard operators
[+], [-], [*], and [/] for integer values. An expression is always interpreted
from left to right, regardless of the mathematical priority of the operators.
If you want to prioritize multiplications over additions, you should write the
multiplication first, or you can use parentheses to enforce the correct order.
In addition to the standard operators, the binary operators AND, OR, and XOR are
supported.
For string variables only the [+] operator is supported to concatenate strings.
Note that the expression a$ = a$ + b$ works, but a$ = b$ + a$ does not. This is
because SnailBASIC does not use a temporary buffer to store the target string.
EXAMPLES
This program outputs all Fibonnaci numbers between 0 and 10000:
10 a=0:b=1
20 PRINT a
30 PRINT b
40 b=b+a
50 a=b-a
60 IF B<10000 THEN 30
Here is a program that converts temperature from Fahrenheit to Celsius:
10 INPUT"Temperature in Fahrenheit";f
20 c = (f - 32) * 5 / 9
30 PRINT f;"Fahrenheit are ";c;"degree Celsius"
40 GOTO 10
This program calculates the square root of a number:
10 INPUT a
20 b=a
30 c=a/b+b
40 c=c/2
50 b=b-c
60 IF b<0 THEN b=0-b
70 IF b>1 THEN b=c : GOTO 30
80 PRINT c
Side note:
The Forth implementation of the sqrt function is 4.3 times faster than the
SnailBASIC implementation. This is the square root function in Forth:
: sqrt dup begin 2dup / over + 2/ swap over - abs 2 < until nip ;
|
|
