retroforth/doc/book/techniques/stack-diagrams
crc 84ef7119e8 book: mention sub-stack comments for words consuming quotes
FossilOrigin-Name: ad5f3c67563842c62a09c38a80da2737518ce254ad0a7c1f5b4bdb1892eb73ae
2021-06-22 10:58:56 +00:00

41 lines
1.4 KiB
Text

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