duskos

commit ddeb807716c011dac7f27eaca13186f0c51671e3
parent 2cae7099c132e76bedbec799a65fc76fdda0ced0
Author: Virgil Dupras <hsoft@hardcoded.net>
Date:   Sat, 21 Jan 2023 20:16:14 -0500

doc: add lib/wordtbl

Diffstat:
A
fs/doc/lib/wordtbl.txt
 | 
41
+++++++++++++++++++++++++++++++++++++++++

1 file changed, 41 insertions(+), 0 deletions(-)
diff --git a/fs/doc/lib/wordtbl.txt b/fs/doc/lib/wordtbl.txt
@@ -0,0 +1,41 @@
+# Word tables
+
+The /lib/wordtbl.fs unit allows the creation of word tables allowing those words
+to be called by their index. Example:
+
+    3 wordtbl mytbl
+    :w 42 . ;
+    'w anotherword
+    :w 54 . ;
+
+    mytbl 2 wexec \ prints 54
+    : foo mytbl 1 wexec, ;
+    foo \ calls "anotherword"
+
+## API
+
+Words:
+
+wordtbl ( n "tbl" -- a )
+  Create a new table named "tbl" with "n" entries in it, allocate enough space
+  for these entries and yield its address. Following this creation, exactly "n"
+  words must be added to the table with ":w" or "'w".
+
+:w ( a -- a+4? )
+  Define a word like ":" would, but anonymously (no name). Also, write the
+  address of the newly defined word to "a". If there is still free space in the
+  wordtbl, return "a+4", otherwise return nothing. The idea is that after all
+  entries for a table are created, PS doesn't contain "a".
+
+'w ( a "name" -- a+4? )
+  Find "name" in system dict and write its reference to current wordtbl in the
+  same way ":w" does.
+
+wtbl@ ( tbl idx -- w )
+  Return address of word at index "idx" in "tbl".
+
+wexec ( tbl idx -- )
+  Execute word at index "idx" in "tbl".
+
+wexec, ( tbl idx -- )
+  Compile execution of word at index "idx" in "tbl".