From 6bf147fbb9291f75d24cbb35ae043c5691e647ab Mon Sep 17 00:00:00 2001 From: crc Date: Mon, 13 Nov 2017 02:24:33 +0000 Subject: [PATCH] add a short document on stack comments FossilOrigin-Name: a89d9d182a7f490a2e7503bc52c45abc66a2934514c57c70fe47ddf9bef0238f --- doc/StackComments.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 doc/StackComments.md diff --git a/doc/StackComments.md b/doc/StackComments.md new file mode 100644 index 0000000..8b64497 --- /dev/null +++ b/doc/StackComments.md @@ -0,0 +1,26 @@ +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. + + b, n, m, o, x, y, z are generic numeric values + s represents a string + v represents a variable + p, a represent pointers + q represents a quotation + d represents a dictionary header + f represents a `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 (-)