3.0 KiB
The Stack
The stack is the heart of Forth. Every value you type goes onto the stack. Every word you call takes values from the stack and puts results back. There are no variables in the traditional sense, just this pile of values that grows and shrinks as your program runs.
Pushing Values
When you type a number or a string, it goes on top of the stack:
| Input | Stack (top on right) |
|---|---|
3 |
3 |
4 |
3 4 |
5 |
3 4 5 |
The stack grows to the right. The rightmost value is the top.
Words Consume and Produce
Words take values from the top and push results back. The + word pops two numbers and pushes their sum:
| Input | Stack |
|---|---|
3 |
3 |
4 |
3 4 |
+ |
7 |
This is why Forth uses postfix notation: operands come first, then the operator.
Stack Notation
Documentation describes what words do using stack effect notation:
( before -- after )
The word + has the effect ( a b -- sum ). It takes two values and leaves one.
The word dup has the effect ( a -- a a ). It takes one value and leaves two.
Thinking in Stack
The key to Forth is learning to visualize the stack as you write. Consider this program:
| Input | Stack | What happens |
|---|---|---|
3 |
3 |
Push 3 |
4 |
3 4 |
Push 4 |
+ |
7 |
Add them |
2 |
7 2 |
Push 2 |
* |
14 |
Multiply |
This computes (3 + 4) * 2. The parentheses are implicit in the order of operations. You can use line breaks and white spaces to keep organized, and the editor will also show the stack at each step for you if you ask it nicely :)
Rearranging Values
Sometimes you need values in a different order. Stack manipulation words like dup, swap, drop, and over let you shuffle things around. You will find them in the dictionary. Here is a common pattern. You want to use a value twice:
| Input | Stack |
|---|---|
3 |
3 |
dup |
3 3 |
+ |
6 |
The word dup duplicates the top, so 3 dup + doubles the number.
Another pattern. You have two values but need them swapped:
| Input | Stack |
|---|---|
3 |
3 |
4 |
3 4 |
swap |
4 3 |
- |
1 |
Without swap, 3 4 - would compute 3 - 4 = -1. With swap, you get 4 - 3 = 1.
Stack Errors
Two things can go wrong with the stack:
- Stack underflow happens when a word needs more values than the stack has. If you write
+with only one number on the stack, there is nothing to add. The script stops with an error.
3 + ;; error: stack underflow
The fix is simple: make sure you push enough values before calling a word. Check the stack effect in the dictionary if you are unsure.
- Stack overflow is the opposite: too many values left on the stack. This is less critical but indicates sloppy code. If your script leaves unused values behind, you probably made a mistake somewhere.
3 4 5 + . ;; plays a sound, but 3 is still on the stack
The 3 was never used. Either it should not be there, or you forgot a word that consumes it.