 ____ ____ ____ ____ 
||n |||i |||m |||f ||
||__|||__|||__|||__||
|/__\|/__\|/__\|/__\|

the nimf guide : the stacks

Ready for a semi-deep dive into the nimf stacks? Me too! A stack is a structure where items can get added and removed. To push an item onto the stack you just need to enter a number (or value that corresponds to a number, such as a character or a memory address). That number will be pushed onto the top of stack, which is often refered to by the shorthand: TOS.

There are many words that can remove an item from the top of the stack, or many items. Items are always removed from the top to the bottom. So, if we want a visual representation, here is what a stack might look like with the values 13, 486, 23, 67, -12, and 4 entered in that order at the nimf REPL:

   |   4 | >--- TOS (top of stack)
   | -12 |
   |  67 |
   |  23 |
   | 486 |
   |  13 | <--- Bottom of stack
  =========

If you think of it like a beaker that is just wide enough to fit a marble. You can fill it up with marbles and you cannot take out a marble from the bottom without first taking out the marbles above it, right?

That is how the stack works. It can also be thought of as last in first out (or first in last out).

The Stack as a Global Structure

The stack is always available in nimf. The vast majority of operations implicitly opperate on the stack, many without your even realizing it.

Any time you enter a number, memory address, or character, you are adding a number to the stack. Using strings often avoids the stack a bit, but to reference strings you still need to put their address on the stack (and often offset values to reference different parts of the string).

Two Stacks: data and return

In nimf there are actually two stacks. The vast majority of the time you will be using the data stack, which is the stack that numbers automatically get added to and most words opperate on. This is the stack we have used for everything in this guide up until this point.

There is another, more hidden, stack called the return stack. The return stack is mostly used for control flow by the nimf system. It helps to keep track of loops and conditional branches. It is perfectly acceptable to use the return stack if you need to, but care should be taken. Here are some rules to live by when using the return stack:

If you put something on the return stack as a part of a word definition, remove it before the word ends
If you put something on the return stack inside a loop, remove it before the loop ends
If you put something on the return stack inside a branch of a conditional statement (if, else) be sure to remove it before the end of that particular branch

In short: if you put something on the return stack, take special care to remove it before the system would need the values that you may have covered up by adding your value. Following the above guidelines will allow you to safely use the return stack without altering the execution of your program in unintended ways.

Right now, as you begin your nimf journey, you will not see much use for the return stack (outside of its automatic system functions, which you don't need to worry about). When we get to the section of the nimf guide that talks about variables in detail you will see a very very good use for the return stack (hint: it allows you to create a local scope for a variable).

Stack Words

The nimf system has a number of builtins for dealing with the stack. We can talk about a few of them here, to get you started with stack manipulations. Once you start to build your own words, you will likely end up using these a lot:

.s outputs a visual representation of the stack
drop removes TOS, does not output it
dup copies TOS and places the copy on TOS
depth adasd the current stack depth to TOS
, removes and outputs TOS
swap swaasp the positions of the top two items on the stack
over copies the second item on the stack and places it on TOS

Those are a few basic building blocks to deal with stack manipulations and are enough to get you going pretty well into manipulating the stack. There are, of course, others... but I find that reaching for many of them creates complicated situations and they should be chosen with care. Feel free to peruse the api docs in the guide to see what other stack manipulators you can find, there are some wild ones out there, though most are created from these humble building blocks.

Open nimf in interactive mode and add some numbers to the stack. Try using the words listed above and use .s often to check what your manipulations are doing.

Return Stack Words

As we discused above, there are two stacks. The return stack has some special words that allow you to interact with it. The level of manipulation provided for the data stack is not provided for the return stack by default. In general manipulations should be done on the data stack and then add or remove values from the return stack if absolutely necessary.

Here are the words that interact directly with the return stack:

.r outputs a visual representation of the return stack
<r removes TOS from the data stack and pushes it to the return stack
r> removes TOS from the return stack and pushs it to the data stack
r@ copies TOS from the return stack and pushes it to the data stack

That is basically it, but it is all you should need for most situations involving the return stack.

Further Resources

There is a lot of information online about stacks as general data structures. As I have done elsewhere in this guide I will link out to wikipedia, where there is a great article on stacks:

Wikipedia: Stack (abstract data type) (web)

PREV: quickstart tutorial

NEXT: modules

the nimf guide