A Beginners Guide To FORTH

Welcome to the FORTH Beginner's Guide, !

So, you've crafted a CPU, a Monitor and a Disk Drive, assembled them and turned them on.
You're thinking "What in the world is this, hmm I should probably go and find out."

And you've arrived here, good job! I will try to teach you the fundamentals of FORTH in this guide!

An introduction to FORTH

FORTH is a stack based language, meaning you have to put the numbers in use into a stack first before you can use them in a calculation.
So if you wanted the computer to calculate 2 + 2, you would type:
MineOS v1.1 Initialized
600 bytes free
> 2
> 2
You have put 2 numbers, 2 and 2, into the stack. The stack now looks like this:
[ 2 ]
[ 2 ]
To add them together you now need to put an operator into the stack, in this case a plus sign, and now the console should look like this:
MineOS v1.1 Initialized
600 bytes free
> 2
> 2
> +
The '+' sign is a word that takes the last two numbers from the stack, add them together and places the answer back into the stack:
The stack 2 2 4
\ / |
The word + -------->--^
So the stack should now be like this:
[ 4 ]
But why can't we see the answer, you ask? It's because you haven't asked for it yet!
That is what the "." word does.
The "." just takes the first thing on the stack and prints it to the screen.
So to make it tell you the answer, just type ".".
MineOS v1.1 Initialized
600 bytes free
> 2
> 2
> +
> . 4
Note that "." removes the value that it prints from the stack (now the stack is empty).

What we have learned

1. FORTH is stack based
2. A simple calculation in FORTH
3. The "." prints to the screen

2. On to more interesting subjects (sort of)

Steve: "Ok ,so I know how FORTH works but how can I apply that to Minecraft? You still haven't told me how to use the computers."

The computers run Eloraam's special flavor of FORTH.
They may look daunting at first but they are in fact friendly creatures and can be tamed.

Steve: "Grr! Come on, tell me how to use them already! I'm bored!"

Fine, I will!

The very first program you should learn in any language is the "Hello World" program.

First create a word like this (Note: in FORTH, a "word" is a program. You can use words in other words to help you manage your code in a modular form.)
MineOS v1.1 Initialized
600 bytes free
> : HelloWorld
and press Enter. This will open the compiler, allowing you to define the word "HelloWorld".
Steve: "Ok, I've done that."
Now type
Compile: ." HelloWorld"
and press Enter.
Notice how we are using ." <string>" to print to the screen. The word ." <string>" prints the string to the screen.
Note: The space between the first quotation mark and the word is required!

Now we end the program and return to the console by typing ";" and pressing <Enter>.
The semicolon tells the compiler that you are done defining the word.

The finished program should look like this:
: HelloWorld
." HelloWorld"
To run your program, just type the name of your program (HelloWorld in this example) into the computer. It should then print "HelloWorld", like this:
MineOS v1.1 Initialized
600 bytes free
> : HelloWorld
Compile: ." HelloWorld"
Compile: ;
> HelloWorld HelloWorld

We have now learned how to:

1. Create a word
2. Print messages to the screen
3. Run a word

3. The world outside

Steve: "Tell me something more interesting! Helloworld is booooooooring!"

How about controlling redstone?
Steve: "OK, computer controlled death rays! Mwahaha!"

(You will need an IO expander connected to your computer via Ribbon Cable for this example, and a line of Bundled Cable attached to the IO expander with all colours broken out using Insulated Wires. For easy testing, I would suggest putting Lamps on the ends of wires to display the output.)

Ok, so you want to control Redstone? That's what the IO Expander does.
There are 4 words you can use to control the IO Expander:
First we will look at "IOX!". This will send a value to the IO Expander, which will be translated into 16-bit binary and sent through the Bundled Cable.
This is how it is used:
> 1 IOX!
will send "1" to the IO Expander, which will turn the white wire (Binary 1) on.

The "!" basically just sends what it is given to the IOX.

Steve: "Simples teach', that was easy. Ok next question, how do I recieve values from the IOX?"
(^^ Reference to a TV advert if you were confused by that)

That's easy! Just use IOX@ instead:
> IOX@ .
This time we are requesting a value from the IOX but we need "." to print the value from the stack.

Steve: "I'm getting the hang of this now! You were right, FORTH isn't that hard."
I'm glad you're learning!
Steve: "Oh wait, I have another question. How do you turn on individual bits without changing the others?"
That's simple as well! In fact, that what the next two words I was going to teach you. IOXSET and IOXRST are used for just that!
They will edit individual bits independent of the other bits.
IOXSET sets the specified bit to 1.
And IOXRST resets the bit to 0.

For example:
will turn the pink(3rd wire = Binary 4) wire on and then off again.

What we have learned:

1. How to send and receive redstone sinals via the IO Expander
2. More advanced ways to control bits.

4. Storage

Steve: "Can I build my super-duper PIGFRYER2000 Death Ray yet?"

Not quite yet, there are a few more things you will need to learn first.
*Pigs cheering*

Steve: "Why can't I build it now?! What am I missing?"
Steve: "What do chests have to do with FORTH?"
No, not that kind of storage. I'm talking about Variables and Constants. You might want to count how many pigs you've fried.
Steve: "Yeah, alright then."

OK, Variables are spaces where numbers can be entered and stored until needed by the program.
Variables can change during a program, making them useful for, say, calibrating a quarry mid-program.
Constants are very similar to variables, but constants are fixed and cannot change. They are fixed numbers like Pi or the number 2 and could be used for making a pantograph that scales the block pattern by 2. The constant would be 2 and you would just enter it where required.

Both variables and constants have to be defined before they can be used.
To define a variable or constant you do this:
0 CONSTANT const
The first line creates a variable called "var".
The second creates a constant called "const" and sets it to 0.

All variables must be defined before they can be used in a program.

If you need to modify a pre-defined variable during the program,
*Value* *Varname* !
will send the value into the variable using the word "!". The way that "!" works is that it takes the two topmost values on the stack, the first being the memory address and the second being the value, and writes the value to the memory address. So the above code is actually putting first the value and then the memory address onto the stack, then running the "!" word to assign the value to the variable.

Here's an example of a program where variables could be useful:
> VARIABLE Raytime
> 1 CONSTANT Laser
> : Deathray
Compile: 20 Raytime !
Compile: Laser IOXSET
Compile: Raytime @ TICKS
Compile: Laser IOXRST
Compile: ;
This is an example program for a Death Ray controller.
Steve: "Sweet! How does it work?"

Well, the laser is attached to the white wire, which is wire 1. We are using the constant "Laser" to remember that for us.
Raytime is how long the laser should be on, in this case 20 ticks or 1 second. We covered how the IO Expander works in the last chapter so there is nothing new there.
Although we haven't seen "TICKS" before, it is very simple. When the program encounters "Raytime @ TICKS", it gets the value of Raytime and waits that many ticks before continuing to the next line.
Simply put, this program turns the laser on, waits one second, and then turns it off again.

What we've learned:

1. How to define Variables and Constants
2. How to change and retrieve the value of a Variable
3. A practical use for "Vars" and "Consts"

5. Loop da loop

Steve: "Yay it works! Zapping pigs is fun!"
Poor pigs :(
Steve: "But, but, I'm getting bacon! How could you not like bacon?"
I'm a computer, I hate bacon. It's too greasy.
Steve: "Um OK you're weird, bacon is the food of choice for any sentient race."
Alright then.
Steve: "The only problem is that my PIGFRYER2000 is rather slow because I have to keep running the word every time I want to kill a pig."

You can use loops to fix that.
Namely the DO loop. Know as "for" loops in other languages, DO loops repeat the specified code again and again for however many times you specify.
The DO reference: ( n1 n2 -- )
Used like this:
<Ending number> <Starting number> DO
There is also a better version, ?DO, which checks the condition before going into the loop. This can be better because the normal DO will loop 63365 times if n1 = n2.

They aren't very hard to use either, as they only take two inputs. Here's an example:
10 0 DO
." Hi, I am an iteration of a DO loop."
This is an example of a loop that will print "Hi, I am an iteration of a DO loop." ten times.

The second number can be used to set the starting number:
10 5 DO
." Blah"
Will print Blah '10 minus 5' times.
This is really only useful due to the fact that you can find out which iteration the for loop is on using the variable I, which starts at the 2nd number and goes to the 1st.

So if you wanted to fire your laser 5 times every time you run the program, you could do this:
5 0 DO
That will turn on the laser for 1 second and then turn it off for 1 second, but it will do that FIVE TIMES.

Steve: "Oh cool! Thank you so much for teaching me the basics of FORTH!"
You are welcome! You learned very quickly, you should be proud!
Steve: "I'm going to go brag about it to my friends now! Bye Computer!"
Bye Steve! I hope you have fun! Remember to check the FORTH Dictionary if you need any more help!
Steve: "Thanks, I will! Bye!"