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.