Welcome to RetroForth

The Forth language is based on the concept of a stack. Imagine a stack of blocks with numbers on them. You can add or remove numbers from the top of the stack. You can also rearrange the order of the numbers. Forth uses two stacks.

The data stack is the one used for passing data between Forth words so we will concentrate our attention there. The return stack is another Forth stack that is primarily for internal system use but is often used to store temporary values. In this tutorial, when we refer to the stack, we will be referring to the data stack. For reference, we'll call the return stack RS.

The stack is initially empty. Start up RetroForth, and notice you are greeted by something like:

RetroForth 8.0 :: Visit http://www.retroforth.org for updates

The interpreter is now awaiting your command. Let's start by putting some numbers on the stack. Type in:

23 7 9182

Excellent! Now print the number on top of the stack using the Forth word ., which is pronounced dot. This is a hard word to write about in a manual because it is just a single period. Enter:

.

You should see the last number you entered, 9182, printed. RetroForth has a very handy word for showing you what's on the stack. It is .s, which is pronounced dot S. The name was constructed from dot for print, and S for stack. If you enter:

.s

You will see the numbers 0 0 0 0 0 0 0 0 23 7, in a list. The number at the far right is the one on top of the stack. The word .s displays the top ten entries on the stack, so if you have fewer values, the number 0 will be showed instead. Notice that 9182 is not on the stack. The word . removes the number on top of the stack before printing it. In contrast, .s leaves the stack untouched.

Forth uses the stack to hold data being operated on, and it uses the stack to pass data from word to word. Essentially, a word takes whatever it needs from the stack, and puts whatever its results are on the stack. This is a very powerful aspect of Forth, but one which requires practice to understand. It also means that documenting what each word does to the stack is important and useful.

The standard technique for documenting the effect words have on the stack is by means of a stack diagram. Stack diagrams begin with a left-parenthesis, contain the stack-effect diagram, and end with a right-parenthesis. In Forth, parentheses indicate a comment, and everything between them is ignored. So while you could put whatever you like between parentheses and treat them as ordinary comments, the usual use of parentheses is for stack-comments. For example, the stack-digram for the word 'dot' which we used before, would be:

. ( n -- )

That is to say, . takes one word off the stack (the n) and puts nothing on the stack. In other words, it consumes the top stack item (hereafter called TOS).

In the examples that follow, you should not type in the comments. When you are programming, of course, use of comments and stack diagrams may make your code more readable and maintainable. Besides the parenthesis, you may use the vertical-bar character | as comment to end-of-line. In other words, anything after the | on that line is ignored:

dup swap | This is all a comment

Note: | comments are not supported in definitions, use the ( ) form instead.

Between examples, you may wish to clear the stack. If you enter reset, the stack will be cleared. Since the stack is central to Forth, it is important to be able to alter it easily. Let's look at some more words that manipulate the stack. Enter:

777 dup .s

You will notice that there are two copies of 777 on the stack. The word dup duplicates TOS. This is useful when you want to use the TOS and still have a copy. The stack diagram for dup would be:

dup ( n -- n n )

Another useful word is swap. Enter:

23 7 .s
swap .s

The stack should have 7 23 now. The stack diagram for swap would be:

swap ( a b -- b a )

Now enter:

over .s

You should see 23 7 23. The word over causes a copy of the second item on the stack to leapfrog over the first. Its stack diagram would be:

over ( a b -- a b a )

Here is another commonly used Forth word:

drop ( a -- )

Can you guess what we will see if we enter:

drop .s

Another handy word for manipulating the stack is rot. Enter:

11 22 33 44 .s
rot .s

The stack diagram for rot is, therefore:

rot ( a b c -- b c a )

You have now learned the more important stack manipulation words. You will see these in almost every Forth program. I should caution you that if you see too many stack manipulation words being used in your code then you may want to reexamine and perhaps reorganize your code. You will often find that you can avoid excessive stack manipulations by using variables, which will be discussed later. It is also likely that factoring your code -- that is, breaking it into smaller words -- may help reduce the stack juggling.

I have included the stack diagrams for some other useful stack manipulation words. Try experimenting with them by putting numbers on the stack and calling them to get a feel for what they do. Again, the text in parentheses is just a comment and need not be entered.

2drop ( a b c -- a )
2dup ( a b -- a b a b )
nip ( a b c -- a c )
tuck ( a b -- b a b )
-rot ( a b c -- c a b )