docs(dictionary): batch 1 -- the symbols, the digits, A..C (#157) [skip ci]

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GE3SDvQn5EoxdGufk84zz2
This commit is contained in:
Claude
2026-11-10 11:26:58 +00:00
parent a53cc82dd5
commit 1c9a65c970
+126 -126
View File
@@ -1,132 +1,132 @@
# docs/reference/v4-dictionary.tsv -- the dictionary of v4 (#157): name, stack notation, # docs/reference/v4-dictionary.tsv -- the dictionary of v4 (#157): name, stack notation,
# description, tab-separated. The names are the live system's (v4/tools/mkdictionary.py # description, tab-separated. The names are the live system's (v4/tools/mkdictionary.py
# check refuses a missing or a stale one). A row whose description starts TODO is a draft. # check refuses a missing or a stale one). A row whose description starts TODO is a draft.
! TODO ! ( x addr -- ) Store x in the cell at addr.
# TODO # ( ud1 -- ud2 ) Pictured output: divide ud1 by BASE, put the remainder's digit in front of the string being built, leave the quotient.
#> TODO #> ( ud -- baddr u ) End pictured output: drop ud and leave the string built since <#.
#S TODO #S ( ud -- 0 0 ) Pictured output: convert digits with # until the number is zero (at least one digit).
' ( -- addr ) TODO FORTH-79: the next word's parameter field address; if compiling, compiled as a literal ' ( -- addr ) ' xxx: the parameter field address of xxx; compiled as a literal when compiling.
( TODO ---- comments (5.15) ------------------------------------------------------- PAREN skips to the closing parenthesis; BACKSLASH skips the rest of the line. ( ( -- ) ( text): a comment, ended by the first ); immediate.
(.") TODO The run time of ." : print the string after the call, go on after it. It takes the return address off before it calls anything and keeps the count there instead, so a word that prints text goes no deeper than one that calls any other word. (.") ( -- ) The run time of .": print the string compiled after the call, and go on after it.
(ABORT") ( flag -- ) TODO the run time of ABORT" : if the flag is not zero print the string after the call, start a new line and ABORT; otherwise go on after the string. (ABORT") ( flag -- ) The run time of ABORT": if flag is not zero, print the string compiled after the call and ABORT.
(BITS) ( -- n ) TODO (BITS) ( -- n ) The number of bits in a cell, counted at run time (forth79.4th; used by U/MOD).
(CONSOLE) TODO (CONSOLE) ( -- addr ) Variable: the node that what this node prints is sent to, as messages (core.f18).
(LOG") ( level -- ) TODO the run time of LOG-xxx" : the text is after the call, as for ." ; log it at that level and go on after it. (LOG") ( level -- ) The run time of LOG-xxx": print the string compiled after the call if level is at or below LOG-LEVEL.
(LOST) TODO (LOST) ( -- addr ) Variable: a count of the messages this node has dropped -- nowhere to send them, or no room.
(ME) TODO (ME) ( -- addr ) Variable: this node's number in the mesh.
(NB) TODO (NB) ( -- n ) Constant: the bits in a cell, (BITS) counted once at load (forth79.4th).
(REFUSED) TODO (REFUSED) ( -- addr ) Variable: a count of the messages that came back to this node, refused.
(S") TODO The run time of S" : leave the address and length of the string after the call, and go on after it. (S") ( -- baddr u ) The run time of S": leave the address and length of the string compiled after the call.
(SEAL) ( -- ) TODO WHAT IS IN THE DICTIONARY NOW IS THE SYSTEM: COLD comes back to it and FORGET will not go below it. Whoever has loaded a node's capsules has it do this (system.f18, (BOOT) and FENCE). (SEAL) ( -- ) What is in the dictionary now is the system: COLD returns to it and FORGET will not go below it.
(UD) TODO (UD) ( -- addr ) Variable: U/MOD's divisor while it divides (forth79.4th).
(WORD-DEFINED) TODO (WORD-DEFINED) ( -- addr ) Variable: the hook told when an entry is made, with the xt its code will be at.
(WORD-FORGOTTEN) TODO (WORD-FORGOTTEN) ( -- addr ) Variable: the hook told when entries are forgotten, with the word address they went from.
* TODO The low cell of the product, by N steps of +* with nothing but the count on the return stack. UM* drop gives the same cell but needs two more return entries, which a word inside two DO loops does not have (D-2). The low cell is exact: what +* loses at the top of T (D-3) takes N shifts to reach the bit that moves into A, and the loop ends first. * ( n1 n2 -- n3 ) Multiply: the low cell of the product.
*/ TODO */ ( n1 n2 n3 -- n4 ) n1 times n2 divided by n3, through a double-cell intermediate product.
*/MOD TODO */MOD ( n1 n2 n3 -- n4 n5 ) n1 times n2 divided by n3, through a double product: n4 the remainder, n5 the quotient.
+ TODO ---- arithmetic ---- + ( n1 n2 -- n3 ) Add.
+! TODO +! ( n addr -- ) Add n to the cell at addr.
+LOOP TODO +LOOP ( n -- ) Compile-only: end a DO loop, adding n to the index; the loop ends when the index crosses the limit.
, TODO , calls nothing: the code generator calls it from as deep as anything goes. , ( x -- ) Compile x into the next cell of the dictionary.
- TODO - ( n1 n2 -- n3 ) Subtract: n1 minus n2.
-! TODO -! ( n addr -- ) Subtract n from the cell at addr.
--> ( -- ) TODO go on with the next block. Only in a block being loaded: at the terminal it is an error (code 14). --> ( -- ) Go on loading with the next block; only in a block being loaded.
-ROT TODO -ROT ( x1 x2 x3 -- x3 x1 x2 ) Rotate the top three values the other way from ROT.
-TRAILING TODO -TRAILING ( baddr u1 -- baddr u2 ) The string without its trailing blanks.
. TODO . ( n -- ) Print n in the current BASE, then a blank.
." TODO FORTH-79: ." text" prints the text -- now, if interpreting; when the word it is compiled into runs, if compiling. ." ( -- ) ." text": print the text -- now when interpreting, when the word runs when compiling.
.R TODO .R ( n width -- ) Print n right-justified in a field of width characters.
.S ( -- ) TODO as v3: the depth between < and >, then every value on the stack, the deepest first, each followed by a blank; then a new line. The stack is left as it was. It reads each value with PICK, so it needs a few cells of the stack free to work in. .S ( -- ) Print the stack's depth and every value on it, the stack unchanged.
/ TODO / ( n1 n2 -- n3 ) Divide: the quotient of n1 by n2. Division by zero is error 11.
/MOD TODO /MOD ( n1 n2 -- n3 n4 ) Divide n1 by n2: n3 the remainder, n4 the quotient.
0< TODO 0< ( n -- flag ) True if n is negative.
0<> TODO ---- comparison ---- 0<> ( x -- flag ) True if x is not zero.
0= TODO 0= ( x -- flag ) True if x is zero.
0> TODO 0> ( n -- flag ) True if n is greater than zero.
1+ TODO 1+ ( n -- n+1 ) Add one.
1- TODO 1- ( n -- n-1 ) Subtract one.
2! TODO 2! ( x1 x2 addr -- ) Store the cell pair at addr: x2 at addr, x1 in the next cell.
2* TODO 2* ( n -- 2n ) Shift left one bit.
2+ TODO 2+ ( n -- n+2 ) Add two.
2, TODO 2, ( x1 x2 -- ) Compile the cell pair into the dictionary.
2- TODO 2- ( n -- n-2 ) Subtract two.
2/ TODO 2/ ( n -- n/2 ) Shift right one bit, keeping the sign.
2>R TODO 2>R ( x1 x2 -- ) ( R: -- x1 x2 ) Compile-only: move the pair to the return stack.
2@ TODO ---- memory ---- 2@ ( addr -- x1 x2 ) Fetch the cell pair at addr.
2DROP TODO 2DROP ( x1 x2 -- ) Drop the top pair.
2DUP TODO 2DUP ( x1 x2 -- x1 x2 x1 x2 ) Copy the top pair.
2OVER TODO 2OVER ( x1 x2 x3 x4 -- x1 x2 x3 x4 x1 x2 ) Copy the second pair to the top.
2R> TODO 2R> ( -- x1 x2 ) ( R: x1 x2 -- ) Compile-only: move the pair from the return stack.
2R@ TODO 2R@ ( -- x1 x2 ) ( R: x1 x2 -- x1 x2 ) Compile-only: copy the pair on the return stack.
2ROT TODO 2ROT ( x1 x2 x3 x4 x5 x6 -- x3 x4 x5 x6 x1 x2 ) Rotate the top three pairs.
2SWAP TODO ---- stack ---- 2SWAP ( x1 x2 x3 x4 -- x3 x4 x1 x2 ) Exchange the top two pairs.
79-STANDARD TODO FORTH-79: execute to be sure a FORTH-79 system is there. It is: nothing happens. (v3's prints two lines and leaves a flag.) 79-STANDARD ( -- ) Run to be sure a FORTH-79 system is there; it is.
: TODO FORTH-79: start a definition; it cannot be found until ; ends it. The CONTEXT vocabulary is set to the CURRENT one. (C)+2 holds LATEST while the entry is made, to tell whether one was. : ( -- ) : xxx: start a definition of xxx; it cannot be found until ; ends it.
; TODO FORTH-79: compile the return, let the word be found, stop compiling ; ( -- ) Compile-only: end the definition -- compile its return, let it be found, stop compiling.
< TODO < ( n1 n2 -- flag ) True if n1 is less than n2.
<# TODO ---- pictured output ---- <# ( -- ) Begin pictured numeric output.
<= TODO <= ( n1 n2 -- flag ) True if n1 is less than or equal to n2.
<> TODO <> ( x1 x2 -- flag ) True if x1 and x2 differ.
= TODO = ( x1 x2 -- flag ) True if x1 equals x2.
> TODO > ( n1 n2 -- flag ) True if n1 is greater than n2.
>= TODO >= ( n1 n2 -- flag ) True if n1 is greater than or equal to n2.
>BODY TODO >BODY ( xt -- addr ) The parameter field of the word whose execution token is xt.
>IN TODO >IN ( -- addr ) Variable: the offset in the input buffer of the next character to read.
>LINK TODO >LINK ( xt -- lfa ) The link field of the entry whose execution token is xt.
>NAME TODO >NAME ( xt -- nfa ) The name field of the entry whose execution token is xt.
>R TODO ---- return stack: in line, and only inside a definition ---- >R ( x -- ) ( R: -- x ) Compile-only: move x to the return stack.
? ( addr -- ) TODO print what the cell holds ? ( addr -- ) Print the number in the cell at addr.
?DO TODO ?DO ( limit index -- ) Compile-only: begin a DO loop that is skipped when limit equals index.
?DUP TODO ?DUP ( x -- x x | 0 ) Copy x if it is not zero.
?TERMINAL TODO ---- strings and memory ---- ?TERMINAL ( -- flag ) True if a key has been pressed and is waiting.
@ TODO ---- memory ---- @ ( addr -- x ) Fetch the cell at addr.
ABORT TODO FORTH-79: clear the data and return stacks, set execution mode, return control to the terminal. As v3, the line it stops ends with " ok". Both are emptied before anything is called: ABORT may be run with the return stack full. ABORT ( -- ) Empty the data and return stacks, set execution mode, return control to the terminal.
ABORT" ( flag -- ) TODO ABORT" text" as v3 (it is FORTH-83's, not FORTH-79's): if the flag is not zero, print the text and ABORT. ABORT" ( flag -- ) ABORT" text": if flag is not zero, print the text and ABORT.
ABS TODO ABS ( n -- u ) The absolute value.
ACL-ALLOW! TODO ACL-ALLOW! ( flag xt -- ) Set the word's allow flag (the word-level ACL); nothing on a pinned word.
ACL-ALLOW@ TODO ACL-ALLOW@ ( xt -- flag ) The word's allow flag.
ACL-HEAT@ ( xt -- heat ) TODO how often the word has been used. The node's heat counters are not readable from a programme yet (D-6): 0. ACL-HEAT@ ( xt -- heat ) How often the word has been used: its heat counter.
ACL-HOOK TODO ACL-HOOK ( -- addr ) Variable: the execution token of the ACL recheck word, or 0 for none.
ACL-INHERIT ( src dst -- ) TODO as v3: dst takes src's mode; it is not pinned, its TTL is 0 and it is allowed. This is the one word that unpins. ACL-INHERIT ( src dst -- ) dst takes src's ACL mode; it is not pinned, its TTL is 0.
ACL-INIT-PRIMITIVES ( -- ) TODO as v3: do that to every word in the dictionary, in every vocabulary ACL-INIT-PRIMITIVES ( -- ) Set every word in every vocabulary to its starting ACL fields.
ACL-MODE! TODO ACL-MODE! ( mode xt -- ) Set the word's ACL mode; nothing on a pinned word.
ACL-MODE@ TODO ACL-MODE@ ( xt -- mode ) The word's ACL mode.
ACL-PIN TODO ACL-PIN ( xt -- ) Pin the word: its ACL fields can no longer be changed. One-way.
ACL-PINNED? TODO ACL-PINNED? ( xt -- flag ) True if the word is pinned.
ACL-TTL! TODO as v3: below 0 is 0. The TTL is sixteen bits here: above 65535 is 65535. ACL-TTL! ( n xt -- ) Set the word's ACL time-to-live (0 to 65535); nothing on a pinned word.
ACL-TTL@ TODO ACL-TTL@ ( xt -- n ) The word's ACL time-to-live.
ACL-WORD-ID ( xt -- n ) TODO a number for the word that never changes: its address ACL-WORD-ID ( xt -- n ) A number for the word that never changes: its address.
AGAIN TODO AGAIN ( -- ) Compile-only: end a BEGIN loop that repeats for ever.
ALIGN TODO ALIGN ( -- ) Align the dictionary pointer to the next cell.
ALLOT TODO ALLOT ( n -- ) Reserve n cells of dictionary space.
AND TODO ---- logic and comparison ---- AND ( x1 x2 -- x3 ) Bitwise and.
AWAIT ( node -- how ) TODO WAIT FOR THE NODE'S WORD OF HOW TEXT ENDED: 0 QUIT, 1 completed, 2 an error. (AWAIT-FROM) holds the node while this node waits, and 0 otherwise. It sleeps, executing nothing, until a message comes; then it passes on what is for other nodes, (SERVE), and goes through what is for itself (MESH.md 7d.4): the answer -- a message of type 3 from that node -- is taken, and the wait is over; a NACK is taken: about that node, the wait ends in error 19, Message refused; about another it is counted, as at any time; a GONE is taken: believed (its centre sent it: (GONE?)) and about that node, the wait ends in error 20, Node gone; text from its console ends the wait in error 21, Interrupted (7b.6). The text is not taken: it stays on its wire and is done when this text has been finished with. It is the one way to end a wait on a node that is alive and never answers, short of Hera's killing that node; anything else stays on its wire, in its order, for when this node has nothing to do. WHAT HAS COME ALREADY is on the wires and is found the first time through: the node looks before it sleeps. A message it left on a wire does not keep it awake. The stack what it does needs is tried first, (ROOM), core.f18: text that has left too little ends "Stack overflow" with nothing taken off a wire. AWAIT ( node -- how ) Wait for the node's word on how its text ended: 0 QUIT, 1 completed, otherwise an error.
BASE TODO BASE ( -- addr ) Variable: the number base for conversion in and out.
BEGIN TODO A loop that tests at its end jumps back with the flag still there, so it jumps back to a drop laid just ahead of the body: BEGIN a UNTIL jump L0 Ld: drop L0: a if Ld drop BEGIN a WHILE b REPEAT jump L0 Ld: drop L0: a if Lx drop b jump L0 Lx: drop BEGIN a AGAIN jump L0 Ld: drop L0: a jump L0 The control-flow stack holds Ld, L0 and 3. BEGIN ( -- ) Compile-only: mark the start of a loop (UNTIL, WHILE ... REPEAT, AGAIN).
BL TODO ---- in-line addresses and constants ---- BL ( -- c ) Constant: the blank character, 32.
BLANK TODO BLANK ( baddr u -- ) Fill u bytes from baddr with blanks.
BLK TODO BLK ( -- addr ) Variable: the block being interpreted, or 0 for the terminal.
BLOCK ( n -- baddr ) TODO FORTH-79: the address of a buffer that holds block n, read from storage if it is not already in one. BLOCK ( n -- baddr ) A buffer holding block n, read from storage if it is not already in one.
BUFFER ( n -- baddr ) TODO FORTH-79: the address of a buffer assigned to block n. What the buffer holds is not read from storage. BUFFER ( n -- baddr ) A buffer assigned to block n, not read from storage.
BYE TODO BYE ( -- ) A cold restart of the machine (the kernel's word).
C! TODO C! ( c baddr -- ) Store the byte c at baddr.
C, TODO C, ( c -- ) Compile the byte c into the dictionary.
C@ TODO C@ ( baddr -- c ) Fetch the byte at baddr.
CASE TODO CASE ( -- ) Compile-only: begin a CASE ... OF ... ENDOF ... ENDCASE selection.
CELLS TODO CELLS ( n1 -- n2 ) n1 cells, in address units.
CFA TODO CFA ( pfa -- cfa ) The code field address from the parameter field address.
CMOVE TODO ---- section 5.9: strings ------------------------------------------------ CMOVE ( baddr1 baddr2 u -- ) Copy u bytes from baddr1 to baddr2, lowest first.
CMOVE> TODO CMOVE> ( baddr1 baddr2 u -- ) Copy u bytes from baddr1 to baddr2, highest first (for overlapping moves up).
COLD ( -- ) TODO the system as it was when the capsule had just been loaded: everything defined since is gone, there is one vocabulary, numbers are decimal, the block buffers are empty. Then as WARM. COLD ( -- ) Return the system to what it was when its capsules had just been loaded.
COMPARE TODO COMPARE ( baddr1 u1 baddr2 u2 -- n ) Compare two strings: 0 if equal, -1 if the first is lower, 1 if higher.
COMPILE TODO COMPILE xxx FORTH-79: when the word this is in runs, xxx is compiled COMPILE ( -- ) COMPILE xxx: when the word containing this runs, compile xxx.
CONSTANT ( n -- ) TODO FORTH-79: an entry whose word leaves n CONSTANT ( n -- ) CONSTANT xxx: define xxx, which leaves n.
CONTEXT TODO ---- vocabularies (FORTH-79) ---------------------------------------------------- A vocabulary is two cells: its head -- the xt of its newest entry, or 0 -- and the address of the vocabulary defined before it, or 0. VOC-LINK holds the newest one's address. FORTH's head is (LATEST) and it is in no chain. CONTEXT ( -- addr ) Variable: the vocabulary searched first.
CONVERT ( d1 baddr1 -- d2 baddr2 ) TODO FORTH-79: the characters from baddr1 + 1 on are taken as digits in the current BASE, each accumulated into the double after it is multiplied by BASE, until one is not a digit; baddr2 is its address. (P)+2 holds the digit while the double is multiplied and (P)+5 the address, so nothing waits on the return stack across the calls. CONVERT ( d1 baddr1 -- d2 baddr2 ) Convert the digits from baddr1+1 into d1 in BASE; baddr2 is the first character that is not a digit.
COUNT TODO COUNT ( baddr1 -- baddr2 u ) From a counted string: its first character's address and its length.
CR TODO CR ( -- ) Print a new line.
CREATE TODO FORTH-79: an entry whose word leaves the address of its parameter field CREATE ( -- ) CREATE xxx: an entry whose word leaves the address of its parameter field.
CURRENT TODO CURRENT ( -- addr ) Variable: the vocabulary new definitions go into.
D+ TODO ---- section 5.7: doubles ------------------------------------------------ D+ TODO ---- section 5.7: doubles ------------------------------------------------
D- TODO ---- doubles and mixed ---- D- TODO ---- doubles and mixed ----
D. TODO D. TODO
Can't render this file because it contains an unexpected character in line 10 and column 3.