Implement READ_WORD

[rrq/jonasforth.git] / notes.md

diff --git a/notes.md b/notes.md
index 7788c33ff7e5228f3bc7e7d73dda2f531d886955..e828a805007a9940a2fa949480325deb8abcc5d6 100644 (file)
--- a/notes.md
+++ b/notes.md
@@ -101,3 +101,49 @@ Literals are handled in a special way. There is a word in Forth, called LIT,
 implemented in assembly. When executed, this word looks at the next Forth
 instruction (i.e. the value of ESI), and places that on the stack as a literal,
 and then manipulates ESI to skip over the literal value.
 implemented in assembly. When executed, this word looks at the next Forth
 instruction (i.e. the value of ESI), and places that on the stack as a literal,
 and then manipulates ESI to skip over the literal value.

+
+## Built-in variables
+
+* **STATE** -- Is the interpreter executing code (0) or compiling a word (non-zero)?
+* **LATEST** -- Points to the latest (most recently defined) word in the dictionary.
+* **HERE** -- Points to the next free byte of memory.  When compiling, compiled words go here.
+* **S0** -- Stores the address of the top of the parameter stack.
+* **BASE** -- The current base for printing and reading numbers.
+
+## Input and lookup
+
+`WORD` reads a word from standard input and pushes a string (in the form of an
+address followed by the length of the string) to the stack. (It uses an internal
+buffer that is overwritten each time it is called.)
+
+`FIND` takes a word as parsed by `WORD` and looks it up in the dictionary. It
+returns the address of the dictionary header of that word if it is found.
+Otherwise, it returns 0.
+
+`>CFA` turns a dictionary pointer into a codeword pointer. This is used when
+compiling.
+
+## Compilation
+
+The Forth word INTERPRET runs in a loop, reading in words (with WORD), looking
+them up (with FIND), turning them into codeword pointers (with >CFA) and then
+deciding what to do with them.
+
+In immediate mode (when STATE is zero), the word is simply executed immediately.
+
+In compilation mode, INTERPRET appends the codeword pointer to user memory
+(which is at HERE). However, if a word has the immediate flag set, then it is
+run immediately, even in compile mode.
+
+### Definition of `:` and `;`
+
+The word `:` starts by reading in the new word. Then it creates a new entry for
+that word in the dictoinary, updating the contents of `LATEST`, to which it
+appends the word `DOCOL`. Then, it switches to compile mode.
+
+The word `;` simply appends `EXIT` to the currently compiling definition and
+then switches back to immediate mode.
+
+These words rely on `,` to append words to the currently compiling definition.
+This word simply appends some literal value to `HERE` and moves the `HERE`
+pointer forward.