Author: Virgil Dupras <email@example.com>
Date: Fri, 5 Aug 2022 19:27:54 -0400
doc: add code.txt
|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
+! means "store", the opposite of "fetch".
+, means "write", that is, storing a value to "here" and increment here by that
+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
+] 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