Stack

Forth passes arguments and results on a parameter stack. This is a consequence of its postfix notation.

The stack is often used heavily for intermediate storage of values, and Forth provides a range of words for manipulation of the stack: dup swap over rot drop and others. This can make Forth programs cryptic for the uninitiated. However, there is no need to (ab)use the stack. It is perfectly ok to use local variables in a Forth word, if this leads to a clear definition.

HolonTForth encourages the use of the stack merely for passing parameters, and to use locals inside a word definition. This works very well with Tcl locals.

The locals are defined in the stack notation of HolonTForth.

Stack Notation

Usually in Forth a pair of parentheses are treated as a comment and ignored by the interpreter. Thus the stack notation is a comment in Forth.

In HolonTForth, however, the stack notation is a declaration of the local parameters of the code or colon word. [Therefore parentheses are not available for comments in HolonTForth. Use the backslash comment.]

The stack notation has the general form  ( in | local -- out ). There can be several or none values each for in, local and out.

Example: ( in1 in2 | loc1 loc2 -- out )

For each stack item HolonTForth sets up a local variable.

The input items (before the vertical bar) are set to the arguments on the stack.
The top-of-stack goes to in2, the second-on-stack goes to in1, and the arguments are removed from the stack.

Loc1 and 2 represent further locals that are used in the word. These locals are set to zero initially.

The output locals are defined but not initialized. They are meant to be set by the word. At the end of the word, the out values are pushed on the stack.

Implementation

The compiler adds two stubs of code for the stack handling. For the example above:

In front of the words code it inserts:  

set in2 [pop]; set in1 [pop]; set loc1 0; set loc2 0;

At the end it appends:  

push $out