Forth

• a forth has two stacks: the parameter stack and the return stack
• avoid using then use exit instead
• .", s", (, \ must all have a space that follows it
• a lot of words works differently at compile time v.s. run time. like .s, if, loop. For example, loops and branches cannot be used outside of column defintions (: ... ;)

• the notation ( ... -- ... ) are called stack effects or stack comments or stack notations or stack annotations…
• gforth uses .fs as file extension. Elsewhere, I've also seen .fth or just .f. Wikipedia also mentions .forth and .4th.
• gforth's official release is very old compared to the latest version, all linux distributions I've used (not that many) packages a "very" old version of gforth. The one on Android's app store is fine though.
• Words usualy have the destination on the TOS ( source destination – )
• the parsing is extremely simple:
  • skip whitespaces
  • read until next whitespace
  • lookup the token in the dictionary
  • if not found: try to interpret as number
  • if not a number: 💀

• tos stands for "Top Of Stack", it refers to the "first" element on the stack (usually the parameter stack)
• nos stands for "Next Of Stack", it refers to the "second" element on the stack
• sos stands for "Second On Stack", it means the same thing as nos
• xt execution token, that's analoguous to a function pointer in C or a symbol in lisp

These are not strict, this is forth, you do you. But it might still be useful for reading other people's code.

• @
  • at the start of a word: save a value
    • e.g. @foo could save the ToS into the variable foo
  • at the end of a word: fetch a value
    • e.g. r@ copies a value from the return stack into the parameter stack
    • e.g. c@ fetches a character at c-addr
• !
  • at the start of a word: initialise or reset a value (but I much prefer 0name)
  • at the end of a word: stores into
    • e.g. c! store a character at c-addr
• c for characters
• > and < for "into"/"from"
• 0name for initialisation or re-initialisation
• :name for defining words
• name:, ;name: often used for DSLs
• slight variants to a word is sometimes denoted by adding a single quote at the end
  • e.g. allocate' could denote a variant of allocate that initialise the allocated memory with 0s
• surrounding a word with square brackets ([...]) usually means that it is executed at compile-time
  • a.k.a. "immediate words"
• a word that ends with , means that it puts somethings in the dictionary.
  • or in the case of an assembler, into the target
• an array is usually named using the pluralized name of its elements, like names, people, filenames
• you can define a word to get the current number of elements in a collection (an array), the convention is to prepend a # to the pluralized name of the elements
  • #names, #people, #filenames
  • "number of …"
• the current element number is denoted by appending a # to the name (not pluralized)
  • e.g. name#, person#, #filename
  • "… number", or "… id"
• advance to the next element
  • e.g. +name, +person, +filename
  • increments the variable name# (e.g. name#)

• a for address
• c-addr character-aligned address
• a-addr "address unit"-aligned address (pointer)

• : word ... ;
• : word ... ; immediate
• =/ line comment =
• ( block comment )

many of those have variants prefixed with 2, which work on pairs of cells instead of just one cell. for example:

2swap ( a b c d -- c d a b )

• >r, r>
• 2>r, 2r>
• r@, 2r@
• n>r, nr>

• e.g. use a buffer to store the result
• "target words"

in short: YAGNI

e.g. how to funcall a word?

execute

• inner (next?) v.s. outer

See "moving forth"

Moving Forth: a series on writing Forth kernels