dusk os fork
git clone git://git.alexwennerberg.com/duskos
Log | Files | Refs | README | LICENSE

commit 1ec00f29a8ab99b3effe1dc5cb84b91d8d96e72e
parent b1a2f639e71bf0f337f280e44c8cd977dfb7ebef
Author: Virgil Dupras <hsoft@hardcoded.net>
Date:   Fri,  5 Aug 2022 19:27:54 -0400

doc: add code.txt

Afs/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".