documentation and a little cleanup

1 files changed, 32 insertions, 11 deletions

diff --git a/source/state.cpp b/source/state.cpp
index 27d624c..a2f424c 100644
--- a/source/state.cpp
+++ b/source/state.cpp
@@ -26,7 +26,7 @@ Cell *SP = DICT.data() + DICT.size() - DS;
 Cell *RP = DICT.data() + DICT.size() - DS - RS;
 FuncList IP = nullptr;
 
-std::array<Cell, 2048> DICT;
+std::array<Cell, DictSize> DICT;
 
 Cell& HERE   = DICT[DIdxHere];
 Cell& LATEST = DICT[DIdxLatest];
@@ -34,19 +34,39 @@ Cell& STATE  = DICT[DIdxState];
 
 void executor(FuncList *list)
 {
+    // TODO Use setjmp to recover from errors?
     /*if (setjmp(jmpbuf) == 0)*/ {
-        // Execute the first bit of "word".
-        // If it is a "WordWrap", it will exit without changing IP.
-        // If it is a defined word, IP will be set to the word's body.
-        auto ip = (FuncList)list;
-        auto po = (void (**)(FuncList))*ip;
-        // Pass in po's location so the call can fetch beyond itself.
-        (*po)((FuncList)*ip);
 
+        FuncList body;
+        void (*entry)(FuncList);
+
+        // We are given the pointer to a list of function pointers.
+        // Dereference once to retrieve the function pointer list.
+        // We do not work with IP initially since it needs to be set to zero if
+        // this is a top-level call/execution.
+        body = *list;
+
+        // Enter the execution loop.
+        goto entry;
+
+        // Execution continues so long as IP is not zero.
+        // If this is a top-level execution of a pre-defined word, then IP will
+        // remain zero'd and the loop will immediately exit.
+        // If this is a defined word's execution, then its "call" will overwrite
+        // IP (and push the initial zero-IP to the return stack); execution will
+        // continue until we return to the zero-IP.
         while (IP) {
-            ++IP;
-            auto po = (void (**)(FuncList))*IP;
-            (*po)((FuncList)*IP);
+            // Retrieve next function pointer list.
+            body = (FuncList)*++IP;
+entry:
+            // Dereference `body` to get the first function in the list.
+            // This is casted to take a FuncList as an argument since defined
+            // words need to know their addresses so that they can perform
+            // their "calls".
+            // If the word is pre-defined then the argument will simply be
+            // ignored.
+            entry = (void (*)(FuncList))*body;
+            entry(body);
         }
 
         //std::longjmp(jmpbuf, 1);
@@ -55,6 +75,7 @@ void executor(FuncList *list)
 
 void execute1(Word *word)
 {
+    // IP must initially be zero if executing a word at the top level.
     IP = 0;
     executor(&word->list);
 }