Using kForth


2.5 Stack Diagrams

The kForth dictionary contains many words that you may execute simply by typing them at the ok prompt. Some words expect values to have been placed on the stack when they begin executing. During execution of the word, these values may be removed from the stack and other values may be placed onto the stack. The values that are expected on the stack at the beginning of execution and those values that are returned on the stack at the end of execution are stated in the form of a stack diagram for the word. For example, the stack diagram for the word NEGATE is written as follows:

( n -- m )

This diagram indicates that a single integer n must be on the stack prior to executing NEGATE. After NEGATE finishes executing, the original value n has been removed from the stack and is replaced by a new single integer m. Try typing

3 negate

Now, list the items on the stack using .S.

Words that do not expect any items to be on the stack, and which do not return anything on the stack (e.g. CR and DECIMAL) have a stack diagram that looks like

( -- )

The word @ has the stack diagram

( a -- n )

with the meaning that @ expects an address a on the stack and returns a single integer n on the stack. In contrast the word ! has the stack diagram

( n a -- )

with the meaning that ! expects two items to be on the stack, a single integer n and an address a, with "a" being the top item on the stack. During execution, both n and a are removed from the stack, the word ! using and dispensing with them. Nothing is returned on the stack.