retroforth/doc/book/techniques/the-stacks

131 lines
3.5 KiB
Text
Raw Normal View History

# The Stacks
The stacks are a defining feature of Forth. They are are used
to pass data between words and to track return addresses for
function calls.
RETRO always has two stacks, and optionally (if built with
floating point support) a third.
## Data Stack
This is the primary stack. Values are placed here, passed to
words which consume them and then return results. When I
refer to "the stack", this is the one I mean. Learning to use
the stack is a crucial part to making effective use of RETRO.
### Placing Values On The Stack
Values can be placed on the stack directly.
| Example | Action |
| -------------- | ---------------------------------------- |
| `#300123` | Push the number `300123` to the stack |
| `$h` | Push the ASCII code for `h` to the stack |
| `'hello_world` | Push a pointer to a string to the stack |
| `&fetch` | Push the address of `fetch` to the stack |
### Reordering The Stack
RETRO provides a number of *shufflers* for reordering items
on the stack.
Some of the most common ones are:
| Word | Before | After |
| ------- |--------- | -------- |
| dup | #1 | #1 #1 |
| drop | #1 #2 | #1 |
| swap | #1 #2 | #2 #1 |
| over | #1 #2 | #1 #2 #1 |
| tuck | #1 #2 | #2 #1 #2 |
| nip | #1 #2 | #2 |
| rot | #1 #2 #3 | #3 #1 #2 |
You can use `push` and `pop` to move values to and from the
address stack. Make sure you `pop` them back before the word
ends or RETRO will crash. These two words can not be used
at the interpreter.
There is also a special one, `reorder`, which allows for big
stack restructuring. This is slow but can be very useful.
As an example, let's say we have four values:
```
#1 #2 #3 #4
```
And we want them to become:
```
#4 #3 #2 #1
```
Doing this with the basic shufflers is difficult. You could end
up with something similar to:
```
swap rot push rot pop swap
```
But with `reorder`, you can just express the before and after
states:
```
'abcd 'dcba reorder
```
### Resetting The Stack
If you need to quickly empty the stack, use `reset`.
### Get The Stack Depth
To find out how many items are on the stack, use `depth`.
### Displaying The Stack
You can display the stack by running `dump-stack`.
### Data Flow Combinators
RETRO provides *combinators* for working with data order on
the stack. These are covered in a later chapter and are worth
learning to use as they can help provide a cleaner, more
structured means of working.
### Tips
The stack is *not* an array in addressable memory. Don't try
to treat it like one.
## Address Stack
This stack primarily holds return addresses for function calls.
You normally won't need to directly interact with this stack,
but you can use `push` and `pop` to move values between the
data stack and this.
## Floating Point Stack
If you are using a build with floating point support a third
stack will be present. Floating point values are kept and
passed between words using this.
See the Floating Point chapter for more details on this.
## Tips
I recommend keeping the data stack shallow. Don't try to juggle
too much; it's better to factor definitions into shorter ones
that deal with simpler parts of the stack values than to have
a big definition with a lot of complex shuffling.
## Notes
The standard system is configured with a very deep data stack
(around 2,000 items) and an address stack that is 3x deeper.
In actual use, your programs are unlikely to ever need this,
but if you do, keep the limits in mind.