Lesson 3: The Stack and Numbers
The Toka language makes use of a stack to pass data between functions (called quotes or words [when named]). Imagine a stack of blocks with numbers on them. You can add or remove numbers from the top of the stack. You can also rearrange the order of the numbers.
The stack is initially empty. Let's start by putting some numbers on the stack. Type in:
23 7 9182
Excellent! Now print the number on top of the stack using ., which is pronounced dot. This is a hard word to write about in a manual because it is just a single period.
Enter:
.
You should see the last number you entered, 9182, printed. Each time . is used, the top element on the stack is lost. If you want to see what is on the stack, you can use :stack. Try this:
:stack
You should see:
<2> 23 7
The number on the left, enclosed in brackets, is the number of items on the stack. The number to the far right is the top of the stack, or TOS. It should be mentioned that :stack leaves the stack unchanged.
A Quick Introduction to Stack Diagrams
Since Toka uses the stack to hold data being operated on, and it uses the stack to pass data between quotes, it is very important to practice using it. Quotes generally take what they need off of the stack, and put their results back on it. To help understand exactly what each quote consumes and leaves, we use stack diagrams. As an example:
. ( x- )
That is to say, . takes one word off the stack (the 'x') and puts nothing on the stack. In other words, it consumes the TOS.
In the examples that follow, you do not need to type in the comments. When you are programming, liberal use of comments and stack diagrams may make your code easier to read and maintain.
Between examples, you may wish to clear the stack. If you enter reset, the stack will be cleared. Since the stack is central to Toka, it is important to be able to alter it easily. Let's look at some more functions that manipulate the stack. Enter:
reset 777 dup :stack
You will notice that there are two copies of 777 on the stack. dup duplicates TOS. This is useful when you want to use the TOS and still have a copy. The stack diagram for dup would be:
dup ( x-xx )
Another useful stack operation is swap. Enter:
reset 23 7 :stack swap :stack
You should see:
<2> 23 7 <2> 7 23
Notice how the items have been swapped. The stack diagram for swap would be:
swap ( xy-yx )
Now enter:
over :stack
You should see:
<3> 7 23 7
over causes a copy of the second item on the stack to leapfrog over the first. Its stack diagram would be:
over ( xy-xyx )
Here is another commonly used function:
drop ( x- )
Can you guess what we will see if we enter the following?
drop :stack
Another handy function for manipulating the stack is rot (short for rotate). Enter:
11 22 33 44 :stack rot :stack
The stack diagram for rot is, therefore:
rot ( xyz-yzx )
You have now learned most of the common stack manipulation words. These will be present in almost every non-trivial Toka program. I will say that if you see heavy use of these words in your code, you may want to examine and reorganize (refactor) your code. Use of variables, values, and arrays (which we will discuss later) can also help clean things up.
Here are stack diagrams for some other useful stack manipulation functions. Try experimenting with them by putting numbers on the stack and calling them to get a feel for what they do. Again, the text in parentheses is just a comment and need not be entered.
2drop ( xyz--x ) 2dup ( xy-xyxy ) nip ( xyz-xz ) tuck ( xy-yxy )