~vdupras/duskos

1ec00f29a8ab99b3effe1dc5cb84b91d8d96e72e — Virgil Dupras 4 days ago b1a2f63
doc: add code.txt
1 files changed, 56 insertions(+), 0 deletions(-)

A fs/doc/code.txt
A fs/doc/code.txt => fs/doc/code.txt +56 -0
@@ 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".