Code It
FIGnition is designed to be used immediately for programming. It implements a simple, self-contained language based closely on FIG-forth, a variant of Forth, but with elements borrowed from the Jupiter-Ace computer from the early 1980s. The FIG-forth ROM image has been adapted from the Mark 1 Forth Computer.
This section now includes the beginning of a Forth tutorial. It's followed by a pointer to FIGnition's built-in definitions. Until this section is complete, you'll find the most helpful texts are probably the Jupiter-Ace User manual or Leo Brodie's Starting Forth. Going on from there, the entire set of the Forth Dimensions magazine has been archived and is a great Forth resource.
This version of the tutorial is designed for Firmware releases 0.9.8 and onwards. See Footnotes for differences in earlier firmware.
Introduction
Forth is an amazingly simple, but powerful language. You can use it as a calculator; write any kind of program and extend the language itself. Let's start by doing some simple calculations. When you start FIGnition and it displays its start-up message, type the following exactly as written including the dot at the end, with spaces after the 7, the 6 and the *:
FIGnition
©nichemachines 2011
7 6 * .
Now type <exe> (Press SW5, then release, then press SW8, then release. See Note#2). FIGnition will display a number (42) and an OK message.
FIGnition
©nichemachines 2011
7 6 * . 42 OK
Although it looks rather strange, you can see FIGnition has displayed the answer to 7*6. You can make FIGnition perform lots of simple calculations in the same way, try 12 9 * . <exe> 81 104 - . <exe> 6144 2011 + . <exe> 32000 800 / . <exe>
Forth always works like this, in a very simple way. You provide it with some data (in this case pairs of numbers) and then tell it to do something with the data you gave it (in our cases multiply: * , subtract - , add + , or divide / . ). Simple arithmetic operations take the two most recent numbers, perform a calculation and then remember the result as though you'd typed it in yourself. Dot . displays the most recent number. So if you try: 2011 43 - <exe> (without the dot) you'll just see:
2011 47 - OK
But now if you type . <exe> the result will appear, the year David Braben was born. And similarly, 1964 1968 - . <exe> tells you how much more youthful I am ;-) .
Forth is powerful, but mindless. All it does is read letters and numbers up to the next space and look up the text in its dictionary of commands. If it finds it, it simply executes the command. Then it does the same thing again until it gets to the end of what you typed. So, if you miss out spaces it gets confused. Try 7 6*. <exe> (without a space after 6 or *). Forth displays:
7 6*. <exe> What's 6*. [See Footnote #1]
Which means it doesn't understand 6*. So, in Forth a command is a word which is always followed by a space, it can't tell that symbols like '.' , '*' , '(' or anything else are not normally part of words as in English.
Complex Calculations With Intermediate Results
Forth handles complex calculations just like you do by remembering intermediate results. When we first learned arithmetic we'd write it all down as a sequence, e.g: 2 + 5 + 97 = 104. But in real-life you need to handle intermediate results. For example, the window cleaner came round today. He had to clean 3 windows for one room, 2 for another, and then he had to repeat it for the next flat and repeat that for 3 floors. Then he had to do the other side of the flats where there were 4 windows per flat. To work that out we introduce brackets to tell us to remember intermediate results: ( ( 3 + 2 ) x 2 (flats) x 3 (floors) ) + (4 x 2 x 3).
We work out: 3 + 2 = 5 first (the number of windows on one side of a flat),
then we work out 5 * 2 * 3 = 25 (the number of windows on one floor, then all floors) and remember it as an intermediate result.
Then we work out 4 * 2 * 3 = 20 (the number of windows on the other side) and remember it as an intermediate result.
Finally, we add our intermediate results: 25 + 20 = 45. That's where I'll stop, but the window cleaner will go over to the next set of flats with different arrangements and then to the next street: lots of intermediate results.
Forth naturally handles intermediate results.
3 2 + <exe> ( Forth will calculate the result and remember it )
2 * 3 * <exe> ( Forth takes the last result, multiplies by 2 and remembers it, then multiplies that intermediate result by 3 and remembers it = 25).
4 2 * 3 * <exe> ( Forth remembers the 4, then 2, then multiplies them, remembering the result, then multiplies it by 3 remembering the result).
+ <exe> ( Forth adds the two intermediate results ).
. <exe> 45 OK
You see, mentally, we do calculations in exactly the same way as Forth, except we've been trained to stick the process in our subconsciousness.
Arithmetic Limitations
In FIGnition we're usually limited to doing whole number calculations in the range -32768 to 32767. If you exceed these limits FIGnition will calculate the wrong results. FIGnition has some commands which can handle calculations in the range +/-2 billion, but we won't look at those yet.
Extending The Language
FIGnition has over 100 built-in commands in its language. Programming in Forth is simply about extending its vocabulary. We do this by using the ':' command and the ';' command. Let's say we want to know how old Ben-10 is in days. We can create a new command by typing:
: ben10days 1995 - 365 *
;<exe> OK
In the same sense that when we learn new words we don't immediately act out the explanation, Forth remembers the explanation, but doesn't immediately execute it. But afterwards we can find out how many days he's been around by typing 2011 ben10days . <exe> 5840 OK. Or we can find out how old Ben 10 was in days when our 10 year-old child was born: 2001 ben10days . <exe> 2190 OK.
Handling Text
So far in Forth we've only handled numbers, but Forth has a number of commands which directly handle text. These commands expect text to follow the command (because otherwise Forth would try to look up the text and try to execute it). The simplest one simply displays a message and it only works when you're creating new commands. It's called Dot-Quote (dot as in 'display something' and 'Quote' to refer to text). So let's try that, we'll create the world-famous "Hello World" program in Forth by typing:
: hi ." Hello World!" ; <exe> OK
Note: ." expects a message to finish when it sees another " symbol, as in when we use speech marks to show someone is speaking.
Now when we type hi <exe> Forth displays: Hello World! OK.
Note how compact Forth's version is compared with almost every other computer language. Moreover, it only requires 23 bytes of space in Forth's memory!
Summary
Learning the basics of a language is always slow-going. However, we've learned a great deal about Forth in this simple tutorial. We've found out how the Forth syntax works (it's just a list of words separated by spaces); we've worked out how to make Forth behave like a calculator and even do complicated arithmetic in Forth. We've started to create programs by extending the language and we've even started to make Forth handle text (as well as numbers). We can follow it on with some calculations and then proceed to the next tutorial.
Exercises
@TODO.
Footnotes
#1. In firmware before 0.9.8 error messages were just numbers. So, What's 6*. would be displayed as 6*. ? MSG#0.
#2. In firmware before 0.9.7 you would type in a command by pressing <enter> (SW8 by itself) not <exe> (SW5, release, SW8, release).