Prev: Forth Justification 
Next: Defining Words
If you have ever used an RPN calculator, you will remember that you had to enter the numbers before you entered the operator instead of the normal, algebraic manner of entering number, operator and number.
Algebraic: x + y x - y x * y x / y
Reverse Polish: x y + x y - x y * x y /
What you are doing to the RPN calculator is placing x and y on the
stack and then operating on them. Stack notation is
commonly used to describe what stack items a word requires and what
the word will leave on the stack. The left side of the double dash
refers to the parameters required by the word before execution and the
right side refers to what the word will leave on the stack after
execution.
( n1 n2 n3 -- n )
Here n1, then n2 and then n3 were placed on the stack. So we have n3
on top, n2 in the middle and n1 on the bottom. This describes a word
which will use three numbers which have to be on the stack prior to
the words execution. When the word is finished, one number is added
to the stack. The original three numbers will no longer exist on the
stack. If you ever see the error:
Stack Underflow
it means that a word expected a number on the stack and it wasn't
there. For instance, you execute a word with a stack notation like (
n1 n2 n3 -- n) and the stack before executing the word looks like:
( n1 n2 )
You can see that n3 is missing. What will happen here is that the
word will use n2 in place of n3, n1 instead of n2, and then try to get
another value which does not exist resulting in an immediate Stack
Underflow error. Now suppose the stack had looked like this:
( a1 a2 n1 n2 )
As above, n2 and n1 will be used in place of n3 and n2, but here a2
will be used for n1 and an error won't occur immediately making
debugging a little bit difficult. Some words expect a string (a single word) to follow them. Our stack notation for this would be:
( "string" -- ) or
( "name" -- )
Actually, anything between quotes is referring to a string of some
sort. The ANS (American Nation Standard) for Forth uses this to
represent a space delimited string except they use the notation
"<spaces>name". It would be used like this (ok is the
usual prompt in Forth):
ok clockpgm clk463h.lod <cr>
The word clockpgm expects a character string with no
whitespace characters in it (i.e. a word followed by a carriage
return) which represents a program to load onto the Spectrum clocking
card. You might also see:
( "rest-of-line" -- ) or
( "line" -- )
which is similar to "string" except that it is delimited by a
carriage return. (e.g. "This is allowed.<cr>") The ANS for Forth
seems to use "ccc" to represent the string of characters delimited
by some type of character. (e.g. "ccc<quote>" is a string
delimited by a double quote character.)
rot ( n1 n2 n3 -- n2 n3 n1 ) causes the 3rd stack item to be moved to the top while the 1st and 2nd stack item are pushed down.
-rot ( n1 n2 n3 -- n3 n1 n2 ) causes the top stack item to be moved to the 3rd item while the 2nd and 3rd items are pushed up. A -rot, following a rot, will return the stack to its original order.
swap ( n1 n2 -- n2 n1 ) Exchange the stack positions of the top two stack items.
drop ( n1 -- ) removes the top item from the stack.
nip ( n1 n2 -- n2 ) drops the second item on the stack.
dup ( n1 -- n1 n1 ) make a copy of the top stack item.
2dup ( n1 n2 -- n1 n2 n1 n2 ) is not shown, but acts like dup applied to the top two stack items.
over ( n1 n2 -- n1 n2 n1 ) copies the 2nd stack item to the top of the stack.
pick ( n1 -- n2 ) copies the nth stack item to the top of the stack. Unfortunately for non-programmers, counting starts from zero:
( n1 n2 n3 -- )
^ ^ ^
| | |_______ The zeroth stack item.
| |__________ The first stack item.
|_____________ The second stack item.
depth ( -- +n ) returns the number of items on the
stack.
Prev: Forth Justification
Next: Defining Words