commit 1ec00f29a8ab99b3effe1dc5cb84b91d8d96e72e
parent b1a2f639e71bf0f337f280e44c8cd977dfb7ebef
Author: Virgil Dupras <hsoft@hardcoded.net>
Date: Fri, 5 Aug 2022 19:27:54 -0400
doc: add code.txt
Diffstat:
| A | fs/doc/code.txt | | | 56 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 56 insertions(+), 0 deletions(-)
diff --git a/fs/doc/code.txt b/fs/doc/code.txt
@@ -0,0 +1,56 @@
+# Code conventions
+
+## Patterns in code
+
+@ means "fetch". Its presence in a word indicate that we fetch a value from
+somewhere.
+
+! means "store", the opposite of "fetch".
+
+, means "write", that is, storing a value to "here" and increment here by that
+value's width.
+
+Those symbols above are sometimes accompanied by letters such as "c" (character)
+or "w" (word), which means that instead of being 4 bytes wide (the default
+width everywhere), it's 1 or 2 bytes wide.
+
+' means "address of".
+
+. means "print".
+
+_ means "anonymous definitions" that are meant to be used locally and once.
+
+_ as a prefix indicates a private word that is meant to be only used in the
+context of the local unit.
+
+? at the beginning of the word means "maybe we'll do it maybe we won't". For
+example, "?dup" is meant as "maybe dup".
+
+? at the end of a word indicate a yes/no answer. For example, "ws?" means "is
+it a whitespace?".
+
+^ means "opposite order". For now, it's only used in "-^" as a shortcut to
+"swap -". Maybe we'll drop this...
+
+[] indicates a range. For example, "[]=" means "compare ranges for equality".
+
+[ as a suffix indicates the beginning of a special interpretation of words. For
+example, "foo scratch[" overrides the default scratchpad until "]scratch" is
+reached.
+
+] as a prefix indicates the end of a special interpretation loop.
+
+( as a suffix indicates the beginning of a buffer. For example, "in(" is the
+address of the first char of the input buffer in sys/rdln.
+
+) as a prefix indicates the end of a buffer, exclusively. For example, ")in c@"
+is an out- of bounds fetch. ")in 1- c@" fetches the last char of the buffer.
+
+> has ambiguous meaning. It's generally meant as "movement" or
+"transformation". ">r" means "move element from PS to RS" and "[]>str" means
+"transform a range into a string".
+
+(words), that is, words inside parens, are "false words", that is, words that
+you aren't expected to call directly, but rather to compile in a special
+context. For example, calling "(?br)" makes no sense. "(?br)" is compiled by
+"if".
