retroforth/doc/book/techniques/stack-diagrams

# Stack Diagrams

Most words in RETRO have a stack comment. These look like:

    (-)
    (nn-n)

As with all comments, a stack comment begins with `(` and
should end with a `)`. There are two parts to the comment.
On the left side of the `-` is what the word *consumes*. On
the right is what it *leaves*.

RETRO uses a short notation, with one character per value
taken or left. In general, the following symbols represent
certain types of values.

    | Notation            | Represents              |
    | ------------------- | ----------------------- |
    | b, n, m, o, x, y, z | generic numeric values  |
    | s                   | string                  |
    | v                   | variable                |
    | p, a                | pointers                |
    | q                   | quotation               |
    | d                   | dictionary header       |
    | f                   | `TRUE` or `FALSE` flag. |

In the case of something like `(xyz-m)`, RETRO expects z to be
on the top of the stack, with y below it and x below the y
value. And after execution, a single value (m) will be left on
the stack.

Words with no stack effect have a comment of (-)

For combinators (words consuming quotations), you can include
a sub-comment indicating the expected stack effect of the
quote. E.g.,

    (q(-f)-)

Indicates a word consuming a quote and returning nothing. The
quote should return a flag.