8th Tutorial

Lession 3: RPN and the stack

Note: if you haven’t yet installed 8th, please do so right now and follow the installation instructions as presented in the manual!

What is RPN?

8th uses a syntax called “RPN”, which stands for “Reverse Polish Notation”. What that means is that instead of typing 1 + 1 as you might in most other languages, you type 1 1 + instead. That is, the “operator” comes after the items on which it operates.

So in the console, if you want to know what 256 divided by 8 is, you would type in 256 8 / — go ahead, try it!

If you tried it, you’ll have noticed that 8th accepted what you typed rather stoically. It didn’t complain, nor did it tell you anything. The reason it remained silent is because you didn’t tell it to say anything. So get it to speak up by typing in: . cr — now it should have printed the number “32”. The reason 8th works with RPN syntax, is because information is passed to and from words via the “stack”.

The stack

The most fundamental part of 8th is something called the stack or more properly, the data-stack. A “stack” is something like one of those dish-dispensers in a cafeteria, or a Pez candy dispenser.

What that means to you is that items are “pushed” onto the stack, and at some later time are “popped” back off of it. The last item pushed onto it is the first item popped off, because it’s at the “top” of the stack. Just like that stack of dishes in the cafeteria. Conversely, the first item pushed onto it is the last item popped off, since it is “below” all the other items on the stack. You are almost always going to be concerned chiefly with the top few items on the stack. In 8th we refer to the topmost item (e.g. the item which was most recently pushed onto the stack) as “TOS”, or “top-of-stack”.

Time to experiment! Start 8th, and type 256 and press ENTER. As before, note that 8th is the strong, silent type. This time, however, tell it to show what’s on the stack by invoking the word .s. That is, type .s in the console and press ENTER. Your session should look something like:

ok> 256
ok>
ok> .s
1 n: 00007ffb4b835ae0 1 256 ok>

The word .s means “print stack”, and it will display the top ten items on the stack. In this case, there’s only one item on the stack, the number you put there. There’s quite a bit if information in that line of text. The number on the left is the slot on the stack which is being displayed. So this is the item in slot number 1. After that appears n:, which means that the item being shown is from the “n” namespace; that means it’s a number. Following that is the address of the item, which mainly serves to let you know items are different. The number 1 is the “reference count” of the item. Finally, the value of the item, “256”, is shown. The .s word is one you’re going to use a lot; it’s very useful for keeping track of things!

Now type “8” and press ENTER, then “.s” and ENTER. Now the stack should look like this:

2 n: 00007ffb4b835b00 1 8 1 n: 00007ffb4b835ae0 1 256 ok>

Now type “/” and press ENTER, then “.s” and ENTER. Now the stack should look like this:

1 n: 00007ffb4b835b20 1 32 ok>

What you’ve just looked at is the stack in action. By typing 256 8 you’ve told 8th to put those two numbers on the stack. When you type / you invoked the / word, which consumes two numbers on the stack and divides them, and puts the result back on the stack.

Stack-effect diagrams

Because each word you invoke may affect the stack, it’s important to know exactly how a specific word affects the stack. The way 8th does that is by using a “stack-effect diagram”.

As an example, the word / we invoked has a stack-effect diagram that looks like this: \ n m -- q

To interpret that, split it in two sections separated by the --. On the left side is the items which the word expects on the stack; on the right is what the word leaves on the stack. The left side begins with a \ followed by a space, which means “ignore everything until the end of this line”. That is, it’s a “comment” character.

In this case, / expects to get two items (the documentation tells us they are numbers) and leaves one item (also a number). So we can expect that after invoking /, the stack will have one less item than it had before the invocation.

The order of items in the diagram is: “left-most is bottom-most”. So “m” in the diagram is TOS on entering the word /.

Exercises

Try the following:

  • Type help n:+. Notice the line that begins with “stack:” – that is the stack-effect diagram for the numeric + word.
  • What would the diagram for a word that took one item and returned two look like?
  • What about for a word that took no items and returned none?

Conclusion

In this lesson you learned that the 8th stack is used to pass values to and from 8th words. You also learned how to read the “stack-effect diagram”. Now let’s learn how you can manipulate the stack.