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 Underflowit 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.