Stack effect

From RevaWiki

Glossary entry

---

"Stack Effect" is a description of what a particular word does to the stack(s).

The standard technique for documenting the effect words have on the stack is by means of a stack diagram. Typically, they begin with a left-parenthesis, contain the "stack-effect diagram", and end with a right-parenthesis. In Forth, parentheses indicate a comment, and everything between them is ignored. So while you could put whatever you like between parentheses and treat them as ordinary comments, the usual use of parentheses is for stack-comments. For example, the stack-diagram for the word 'dot' is:

. ( n -- )

That is to say, . takes one word off the stack (the 'n') and puts nothing on the stack. In other words, it consumes the top stack item (TOS).

Sometimes a word also affects the FP stack. In such a case, the Reva standard (see "lib/math/floats") is to indicate the data stack-effect first, followed by a backslash, and then the FP stack effect. For instance, f=:

f= ( -- f \ a b -- )

This indicates that the FP values "a" and "b" are consumed, and a flag value "f" is put in TOS.