1 The Stack

This short tutorial will introduce you to the Forth stack.

1.1 What is the Stack?

The stack is used to carry data between words (Forth speak for sub-routines). Forth does have variables that can be used to hold data, but using the stack can be much more efficient, and faster.

The stack is only used for holding for holding numbers. Each 'entry' on the stack is called a cell. A cell is 16 bits in TurboForth.

1.2 Putting Numbers On the Stack

To put a number on the stack, simply type the number. For example, with the cursor blinking on the TurboForth command line, just type:

And press enter. TurboForth will respond with ok:1

The number 1 after the ok simply means that there is one number (99) on the stack.

Now type 59 and press enter. TurboForth responds with ok:2 - there are now two numbers on the stack.

The stack works like a stack of plates in a restaurant. You can only deal with the top most plate. Think of stack entries as plates with numbers written on them. In our example, the stack now looks like this:

  59
  99

59 is the top-most (the 'most accessible') stack value.

1.3 Taking Numbers Off the Stack

Many words in the Forth language are designed to work on the top-most stack value. Often, in doing so, they consume that value at the same time.

For example, the "word" to display a number (which is on the top of the stack) is . (dot). So, just type

Then press enter. TurboForth displays 59 ok:1 - the 59 was the top-most value on the stack, and the 1 after the ok means there is one value remaining on the stack (in other words, the 59 was consumed by .)

Now type . again. TurboForth responds with 99 ok:0 - our stack is now empty.

1.4 Moving Numbers Around the Stack

Sometimes, you might want to access numbers "further down" the stack. There are a number of words that can manipulate the stack for you. One such word is SWAP. SWAP swaps the top two stack items. So, if you type:

  99 59

You get two numbers on the stack, with 59 at the top of the stack.

Now type:

  SWAP

Now, type . and press enter. TurboForth displays 99 - SWAP moved the 99 to the top of the stack. Now type . (and press enter) again. TurboForth displays 59.

A useful word is .S (dot S) which lets you see the stack without removing or changing the data on the stack. For example:

  100 99 5 77 21 24 .S

Displays

  100 99 5 77 21 24 <--TOP

Notice how TurboForth shows you which value is the top of the stack.

Now type:

  SWAP .S

And you will see

  100 99 5 77 24 21<--TOP

See? The top two items were swapped.

Try:

  DUP .S

DUP means DUPlicate the top stack item.

The language reference has a section on the stack manipulation words.

1.5 Forth: A Sojourn Into Stack Comments

Comments, and stack comments/stack signatures in particular are essential to writing clear Forth code, so it’s worth learning the best practices up front.

So… stack comments in Forth. They are essential to making your code more understandable for ourselves and others; and making it easier to re-use code later on. Here’s what a stack comment looks like for a word (Forth parlance for a function or subroutine) that multiplies a value on the top of the stack by 2:

( n – n*2 )

The opening bracket/parenthesis “starts” the comment (the equivalent of REM). Again a space is required after the bracket. Next we see “n”. This is simply a symbolic representation of a number. Note that it is on the left hand side of that – symbol. That symbol separates inputs from outputs. The stuff on the left side are the inputs and the outputs are on the right side. So, this comment tells us that this word expects one number on the stack, and its output will be the same number multiplied by two. How simple is that?

Here’s a stack signature for a multiply word:

( a b – product )

Here, this word takes two inputs from the stack. A and B. Note that B is on the top of the stack (the rightmost value is always the top of the stack) and A is “underneath it” on the stack. So, that’s the “inputs” dealt with. We can see that it produces one output called “product”. Note, that a and b are missing on the output side. This is crucial. It means that the word CONSUMES the A and B inputs (removed them from the stack) when it executes.

Here’s the stack signature for SWAP:

( a b – b a )

So, before execution, two values should be on the stack, b (at the top) and a underneath it, and after execution, a will be on the top (it’s the furthest to the right) and b will be underneath it).

Here’s DUP, which duplicates the topmost stack item:

( n – n n )

You can probably follow that one easily enough.

Here’s the stack signature for a division word:

( quotient divisor – dividend remainder )

So, this word expects two numbers on the stack. The quotient, and divisor (which is at the top). After execution, the quotient and divisor have consumed, and the dividend and remainder will be pushed to the stack.

Note the closing parenthesis which closes the comment. Anything after this will be seen as code that your Forth system should interpret in some way.

Okay, that’s a brief tour of stack comments. As mentioned, they are not essential, but they do make life easier when you come back to your code months later (or look at somebody else’s code).

<-- Back to Tutorials