LithosAnanke/docs/reference/v4-dictionary.tsv

1	# docs/reference/v4-dictionary.tsv -- the dictionary of v4 (#157): name, stack notation,
2	# description, tab-separated. The names are the live system's (v4/tools/mkdictionary.py
3	# check refuses a missing or a stale one). A row whose description starts TODO is a draft.
4	!	( x addr -- )	Store x in the cell at addr.
5	#	( ud1 -- ud2 )	Pictured output: divide ud1 by BASE, put the remainder's digit in front of the string being built, leave the quotient.
6	#>	( ud -- baddr u )	End pictured output: drop ud and leave the string built since <#.
7	#S	( ud -- 0 0 )	Pictured output: convert digits with # until the number is zero (at least one digit).
8	'	( -- addr )	' xxx: the parameter field address of xxx; compiled as a literal when compiling.
9	(	( -- )	( text): a comment, ended by the first ); immediate.
10	(BITS)	( -- n )	The number of bits in a cell, counted at run time (forth79.4th; used by U/MOD).
11	(CONSOLE)	( -- addr )	Variable: the node that what this node prints is sent to, as messages (core.f18).
12	(LOST)	( -- addr )	Variable: a count of the messages this node has dropped -- nowhere to send them, or no room.
13	(ME)	( -- addr )	Variable: this node's number in the mesh.
14	(NB)	( -- n )	Constant: the bits in a cell, (BITS) counted once at load (forth79.4th).
15	(REFUSED)	( -- addr )	Variable: a count of the messages that came back to this node, refused.
16	(SEAL)	( -- )	What is in the dictionary now is the system: COLD returns to it and FORGET will not go below it.
17	(UD)	( -- addr )	Variable: U/MOD's divisor while it divides (forth79.4th).
18	(WORD-DEFINED)	( -- addr )	Variable: the hook told when an entry is made, with the xt its code will be at.
19	(WORD-FORGOTTEN)	( -- addr )	Variable: the hook told when entries are forgotten, with the word address they went from.
20	*	( n1 n2 -- n3 )	Multiply: the low cell of the product.
21	*/	( n1 n2 n3 -- n4 )	n1 times n2 divided by n3, through a double-cell intermediate product.
22	*/MOD	( n1 n2 n3 -- n4 n5 )	n1 times n2 divided by n3, through a double product: n4 the remainder, n5 the quotient.
23	+	( n1 n2 -- n3 )	Add.
24	+!	( n addr -- )	Add n to the cell at addr.
25	+LOOP	( n -- )	Compile-only: end a DO loop, adding n to the index; the loop ends when the index crosses the limit.
26	,	( x -- )	Compile x into the next cell of the dictionary.
27	-	( n1 n2 -- n3 )	Subtract: n1 minus n2.
28	-!	( n addr -- )	Subtract n from the cell at addr.
29	-->	( -- )	Go on loading with the next block; only in a block being loaded.
30	-ROT	( x1 x2 x3 -- x3 x1 x2 )	Rotate the top three values the other way from ROT.
31	-TRAILING	( baddr u1 -- baddr u2 )	The string without its trailing blanks.
32	.	( n -- )	Print n in the current BASE, then a blank.
33	.R	( n width -- )	Print n right-justified in a field of width characters.
34	.S	( -- )	Print the stack's depth and every value on it, the stack unchanged.
35	/	( n1 n2 -- n3 )	Divide: the quotient of n1 by n2. Division by zero is error 11.
36	/MOD	( n1 n2 -- n3 n4 )	Divide n1 by n2: n3 the remainder, n4 the quotient.
37	0<	( n -- flag )	True if n is negative.
38	0<>	( x -- flag )	True if x is not zero.
39	0=	( x -- flag )	True if x is zero.
40	0>	( n -- flag )	True if n is greater than zero.
41	1+	( n -- n+1 )	Add one.
42	1-	( n -- n-1 )	Subtract one.
43	2!	( x1 x2 addr -- )	Store the cell pair at addr: x2 at addr, x1 in the next cell.
44	2*	( n -- 2n )	Shift left one bit.
45	2+	( n -- n+2 )	Add two.
46	2,	( x1 x2 -- )	Compile the cell pair into the dictionary.
47	2-	( n -- n-2 )	Subtract two.
48	2/	( n -- n/2 )	Shift right one bit, keeping the sign.
49	2>R	( x1 x2 -- ) ( R: -- x1 x2 )	Compile-only: move the pair to the return stack.
50	2@	( addr -- x1 x2 )	Fetch the cell pair at addr.
51	2DROP	( x1 x2 -- )	Drop the top pair.
52	2DUP	( x1 x2 -- x1 x2 x1 x2 )	Copy the top pair.
53	2OVER	( x1 x2 x3 x4 -- x1 x2 x3 x4 x1 x2 )	Copy the second pair to the top.
54	2R>	( -- x1 x2 ) ( R: x1 x2 -- )	Compile-only: move the pair from the return stack.
55	2R@	( -- x1 x2 ) ( R: x1 x2 -- x1 x2 )	Compile-only: copy the pair on the return stack.
56	2ROT	( x1 x2 x3 x4 x5 x6 -- x3 x4 x5 x6 x1 x2 )	Rotate the top three pairs.
57	2SWAP	( x1 x2 x3 x4 -- x3 x4 x1 x2 )	Exchange the top two pairs.
58	79-STANDARD	( -- )	Run to be sure a FORTH-79 system is there; it is.
59	:	( -- )	: xxx: start a definition of xxx; it cannot be found until ; ends it.
60	;	( -- )	Compile-only: end the definition -- compile its return, let it be found, stop compiling.
61	<	( n1 n2 -- flag )	True if n1 is less than n2.
62	<#	( -- )	Begin pictured numeric output.
63	<=	( n1 n2 -- flag )	True if n1 is less than or equal to n2.
64	<>	( x1 x2 -- flag )	True if x1 and x2 differ.
65	=	( x1 x2 -- flag )	True if x1 equals x2.
66	>	( n1 n2 -- flag )	True if n1 is greater than n2.
67	>=	( n1 n2 -- flag )	True if n1 is greater than or equal to n2.
68	>BODY	( xt -- addr )	The parameter field of the word whose execution token is xt.
69	>IN	( -- addr )	Variable: the offset in the input buffer of the next character to read.
70	>LINK	( xt -- lfa )	The link field of the entry whose execution token is xt.
71	>NAME	( xt -- nfa )	The name field of the entry whose execution token is xt.
72	>R	( x -- ) ( R: -- x )	Compile-only: move x to the return stack.
73	?	( addr -- )	Print the number in the cell at addr.
74	?DO	( limit index -- )	Compile-only: begin a DO loop that is skipped when limit equals index.
75	?DUP	( x -- x x | 0 )	Copy x if it is not zero.
76	?TERMINAL	( -- flag )	True if a key has been pressed and is waiting.
77	@	( addr -- x )	Fetch the cell at addr.
78	ABORT	( -- )	Empty the data and return stacks, set execution mode, return control to the terminal.
79	ABS	( n -- u )	The absolute value.
80	ACL-ALLOW!	( flag xt -- )	Set the word's allow flag (the word-level ACL); nothing on a pinned word.
81	ACL-ALLOW@	( xt -- flag )	The word's allow flag.
82	ACL-HEAT@	( xt -- heat )	How often the word has been used: its heat counter.
83	ACL-HOOK	( -- addr )	Variable: the execution token of the ACL recheck word, or 0 for none.
84	ACL-INHERIT	( src dst -- )	dst takes src's ACL mode; it is not pinned, its TTL is 0.
85	ACL-INIT-PRIMITIVES	( -- )	Set every word in every vocabulary to its starting ACL fields.
86	ACL-MODE!	( mode xt -- )	Set the word's ACL mode; nothing on a pinned word.
87	ACL-MODE@	( xt -- mode )	The word's ACL mode.
88	ACL-PIN	( xt -- )	Pin the word: its ACL fields can no longer be changed. One-way.
89	ACL-PINNED?	( xt -- flag )	True if the word is pinned.
90	ACL-TTL!	( n xt -- )	Set the word's ACL time-to-live (0 to 65535); nothing on a pinned word.
91	ACL-TTL@	( xt -- n )	The word's ACL time-to-live.
92	ACL-WORD-ID	( xt -- n )	A number for the word that never changes: its address.
93	AGAIN	( -- )	Compile-only: end a BEGIN loop that repeats for ever.
94	ALIGN	( -- )	Align the dictionary pointer to the next cell.
95	ALLOT	( n -- )	Reserve n cells of dictionary space.
96	AND	( x1 x2 -- x3 )	Bitwise and.
97	AWAIT	( node -- how )	Wait for the node's word on how its text ended: 0 QUIT, 1 completed, otherwise an error.
98	BASE	( -- addr )	Variable: the number base for conversion in and out.
99	BEGIN	( -- )	Compile-only: mark the start of a loop (UNTIL, WHILE ... REPEAT, AGAIN).
100	BL	( -- c )	Constant: the blank character, 32.
101	BLANK	( baddr u -- )	Fill u bytes from baddr with blanks.
102	BLK	( -- addr )	Variable: the block being interpreted, or 0 for the terminal.
103	BLOCK	( n -- baddr )	A buffer holding block n, read from storage if it is not already in one.
104	BUFFER	( n -- baddr )	A buffer assigned to block n, not read from storage.
105	BYE	( -- )	A cold restart of the machine (the kernel's word).
106	C!	( c baddr -- )	Store the byte c at baddr.
107	C,	( c -- )	Compile the byte c into the dictionary.
108	C@	( baddr -- c )	Fetch the byte at baddr.
109	CASE	( -- )	Compile-only: begin a CASE ... OF ... ENDOF ... ENDCASE selection.
110	CELLS	( n1 -- n2 )	n1 cells, in address units.
111	CFA	( pfa -- cfa )	The code field address from the parameter field address.
112	CMOVE	( baddr1 baddr2 u -- )	Copy u bytes from baddr1 to baddr2, lowest first.
113	CMOVE>	( baddr1 baddr2 u -- )	Copy u bytes from baddr1 to baddr2, highest first (for overlapping moves up).
114	COLD	( -- )	Return the system to what it was when its capsules had just been loaded.
115	COMPARE	( baddr1 u1 baddr2 u2 -- n )	Compare two strings: 0 if equal, -1 if the first is lower, 1 if higher.
116	COMPILE	( -- )	COMPILE xxx: when the word containing this runs, compile xxx.
117	CONSTANT	( n -- )	CONSTANT xxx: define xxx, which leaves n.
118	CONTEXT	( -- addr )	Variable: the vocabulary searched first.
119	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.
120	COUNT	( baddr1 -- baddr2 u )	From a counted string: its first character's address and its length.
121	CR	( -- )	Print a new line.
122	CREATE	( -- )	CREATE xxx: an entry whose word leaves the address of its parameter field.
123	CURRENT	( -- addr )	Variable: the vocabulary new definitions go into.
124	D+		TODO ---- section 5.7: doubles ------------------------------------------------
125	D-		TODO ---- doubles and mixed ----
126	D.		TODO
127	D.R		TODO
128	D0<		TODO
129	D0=		TODO
130	D2*		TODO
131	D2/		TODO
132	D<		TODO
133	D=		TODO
134	DABS		TODO
135	DECIMAL		TODO
136	DEFAULT-ROUTE	( port -- )	TODO the port, by its number, leads toward every node not told of
137	DEFER		TODO
138	DEFER@		TODO
139	DEFINITIONS		TODO FORTH-79: new definitions go into the CONTEXT vocabulary from now on.
140	DEPTH		TODO FORTH-79: how many values were on the stack before DEPTH
141	DMAX		TODO
142	DMIN		TODO
143	DNEGATE		TODO
144	DO		TODO
145	DOES>		TODO
146	DROP		TODO
147	DUMP		TODO
148	DUP		TODO ---- stack ----
149	ELSE		TODO
150	EMIT		TODO EMIT puts the character with what has been printed. Everything the node prints goes through EMIT. A is kept: the words that print have always been free to use it across an EMIT. As v3, only the low 8 bits of the character are printed. A BUFFER FOUND FULL is sent first. It is full when a flush of it ended in a fault -- the stack too deep to begin a message -- and what is printed next is that fault's own message: put where (OUT^) points, it would go past the buffer's end, and (OUT^) would never again be at the end to be flushed (MESH.md 7c.6).
151	EMPTY-BUFFERS		TODO FORTH-79: forget what is in the buffers; nothing is written.
152	ENCLOSE	( baddr c -- baddr n1 n2 n3 )	TODO in the zero-terminated string at baddr: n1 the offset of the first character that is not c, n2 the offset of the first c after it, n3 the offset of the first character after that run of c.
153	ENDCASE		TODO
154	ENDOF		TODO
155	ERASE		TODO
156	EXECUTE		TODO
157	EXIT		TODO FORTH-79: return from the definition at this point
158	EXPECT	( baddr n -- )	TODO FORTH-79: characters from the terminal are stored from baddr upward until a new-line or until n have been received; the new-line is taken but not stored. A zero is added after the text, so the buffer must hold n + 1 bytes. No action for n <= 0. SPAN is how many characters were stored (SPAN is not FORTH-79; v3 has it). A line longer than n leaves the rest, its new-line included, to be read next. It is what the prompt reads every line with, with whatever the user has left on the stack beneath it, so it works in (P) -- (P)+0 where the next character goes, (P)+1 how many more may come, (P)+2 where the first went -- and has at most three cells of its own on the data stack (D-2).
159	FALSE		TODO
160	FENCE		TODO
161	FILL		TODO
162	FIND	( -- xt | 0 )	TODO FORTH-79: the compilation address of the next word in the input stream, or 0 if it is not in the dictionary.
163	FLUSH		TODO As v3: the same.
164	FORTH		TODO FORTH-79: the primary vocabulary; it becomes the CONTEXT vocabulary.
165	GONE	( n node -- )	TODO tell the node that node n is gone. It acts on that only if this node is its centre: it forgets the way to n, and if it is waiting for n's answer the wait ends.
166	HERE		TODO
167	HEX		TODO
168	HIDDEN		TODO
169	HOLD		TODO
170	I		TODO
171	IF		TODO Native if leaves the flag, so both ways out of it drop it (section 2): IF a THEN if L1 drop a jump L2 L1: drop L2: IF a ELSE b THEN if L1 drop a jump L2 L1: drop b L2:
172	IMMEDIATE		TODO
173	INTERPRET	( -- )	TODO FORTH-79: take words from the input stream until it is exhausted. A word in the dictionary is executed, or, when compiling and not immediate, compiled. Anything else must be a number in the current BASE: it is left on the stack, or compiled as a literal. What is neither, or a compile-only word met while interpreting, abandons the line, with v3's message: UNKNOWN WORD: 'xxx' xxx: compile-only
174	INVERT		TODO
175	IS		TODO
176	J		TODO
177	KEY		TODO
178	LATEST		TODO
179	LEAVE		TODO
180	LFA		TODO
181	LINK>		TODO
182	LITERAL	( x -- )	TODO FORTH-79: if compiling, compile x as a literal
183	LOAD	( n -- )	TODO FORTH-79: interpret block n, then go on with what follows.
184	LOG-DEBUG		TODO
185	LOG-DEBUG-STR	( baddr u -- )	TODO
186	LOG-ERROR		TODO
187	LOG-ERROR-STR	( baddr u -- )	TODO
188	LOG-INFO		TODO
189	LOG-INFO-STR	( baddr u -- )	TODO
190	LOG-LEVEL!	( n -- )	TODO as v3: a level below 0 is 0, one above 4 is 4
191	LOG-LEVEL@		TODO
192	LOG-TEST		TODO
193	LOG-TEST-STR	( baddr u -- )	TODO
194	LOG-WARN		TODO
195	LOG-WARN-STR	( baddr u -- )	TODO
196	LOOP		TODO
197	M*		TODO The product's sign waits in (F), not on the return stack, for the same reason as SM/REM's.
198	M+		TODO
199	M-		TODO
200	M/MOD		TODO
201	MAX		TODO
202	MIN		TODO
203	MINT-ZUSE		TODO
204	MOD		TODO
205	MOVE		TODO FORTH-79: n cells from addr1 to addr2, the cell at addr1 first.
206	NAME>		TODO
207	NEGATE		TODO
208	NEIGHBOUR	( node port -- )	TODO the node on the other end of the port, by its number; 0: none, or a device. Whoever wires the node tells it, and tells it again when the wiring changes. It is how a node knows who its centre is, the one node whose GONE it believes: (CENTRE).
209	NFA		TODO
210	NO-ROUTE	( node -- )	TODO forget the way to that node, if one is known: what is for it then goes by the way for every node not told of, if there is one. The last way in the table takes its place.
211	NO-ROUTES	( -- )	TODO forget every way: for when the wiring has changed
212	NODE-ERROR		TODO FORTH-79: clear the return stack, set execution mode, return control to the terminal; no message is given. The data stack is left as it is. NODE-ERROR, by name: how a definition written in FORTH raises an error. A store of a code that is not zero is the trap of D-18 -- the word goes no further, the message for the code is printed (-1: the word has printed its own) and the line ends with ERROR. The codes are listed in core.f18.
213	NOP		TODO
214	NOT		TODO
215	NUMBER	( baddr -- d )	TODO FORTH-79. What is not a number gives 0 and sets NODE-ERROR.
216	OCTAL		TODO
217	OF		TODO
218	OR		TODO
219	ORDER	( -- )	TODO as v3's, but true: where names are looked for, and where new ones go
220	OVER		TODO
221	PAD		TODO
222	PAGE	( -- )	TODO clear the screen and put the cursor at the top, as v3: ESC [2J ESC [H
223	PFA		TODO
224	PICK	( n -- x )	TODO FORTH-79: a copy of the n-th value, not counting n itself. 1 PICK is DUP, 2 PICK is OVER. n less than one is an error.
225	PORT!	( w port -- )	TODO write a cell to the port, by its number. It waits until the neighbour has taken it. This is how a node is sent a capsule of F18 code (docs/v4.0.0/MESH.md section 5): the cells go as they are, not as a message, to a node that is executing from its ports.
226	Q.*		TODO ---- multiply ----
227	Q.+		TODO ---- the double words under other names ----
228	Q.-		TODO
229	Q./		TODO
230	Q.0		TODO
231	Q.0=		TODO
232	Q.1		TODO
233	Q.<		TODO
234	Q.=		TODO
235	Q.>		TODO
236	Q.ABS		TODO
237	Q.COS		TODO
238	Q.EXP		TODO ---- e to the x ----
239	Q.FROM-INT		TODO ---- conversion and constants ----
240	Q.LOG		TODO ---- natural logarithm ----
241	Q.MAX		TODO
242	Q.MIN		TODO
243	Q.NEG		TODO
244	Q.PRINT		TODO ---- printing ---- The integer part, a point, five digits, a blank; always in decimal.
245	Q.SCALE		TODO
246	Q.SIN		TODO
247	Q.SQRT		TODO ---- square root ----
248	Q.TO-INT		TODO
249	QUERY	( -- )	TODO FORTH-79: up to 80 characters, or a line, into TIB; >IN to 0.
250	QUIT		TODO
251	R>		TODO
252	R@		TODO
253	REPEAT		TODO
254	ROLL	( n -- )	TODO FORTH-79: the n-th value, not counting n itself, is taken out and put on top. 3 ROLL is ROT, 2 ROLL is SWAP, 1 ROLL does nothing. n less than one is an error.
255	ROT		TODO
256	ROUTE	( node port -- )	TODO the port, by its number, leads toward that node
257	RSHIFT		TODO
258	S>D		TODO
259	SAVE-BUFFERS		TODO FORTH-79: write every block that has been UPDATEd.
260	SCAN		TODO
261	SCR		TODO
262	SEARCH		TODO
263	SEND	( baddr u node -- )	TODO send the node u characters of text to interpret, by the way this node knows to it. What it prints there goes to that node's console. With no way to the node it is error 12.
264	SEND-ON	( baddr u node port -- )	TODO the same by a port this node names, by its number, whatever ways it knows: for a neighbour that has no number of its own yet, to which text is sent as to node 0.
265	SIGN		TODO
266	SKIP		TODO
267	SMUDGE		TODO
268	SOURCE	( -- baddr u )	TODO the input buffer and how much of it is in use
269	SPACE		TODO
270	SPACES		TODO ---- spaces and the number base ----
271	SPAN		TODO
272	STATE		TODO
273	SWAP		TODO
274	THEN		TODO
275	THRU	( first last -- )	TODO as v3: LOAD each block from first to last.
276	TIB		TODO
277	TRAVERSE	( baddr n -- baddr' )	TODO as v3: for n > 0, from a name's count byte to the byte after its last character; otherwise the address unchanged.
278	TRUE		TODO
279	TYPE		TODO
280	U*		TODO
281	U.		TODO
282	U.R		TODO
283	U/MOD		TODO
284	U<		TODO
285	U>		TODO
286	UM*		TODO ---- section 4: multiply ------------------------------------------------
287	UNLOOP		TODO
288	UNTIL		TODO
289	UPDATE		TODO FORTH-79: mark the block most recently asked for as changed, so that it is written before its buffer is used for another.
290	VARIABLE		TODO FORTH-79: CREATE and one cell. The standard leaves its first value to the programme; here it is 0.
291	VERSION	( -- )	TODO which system this is, and its cell width
292	VLIST		TODO
293	VOCABULARY		TODO
294	WARM	( -- )	TODO as v3's message, and then ABORT: both stacks emptied, the prompt
295	WHILE		TODO
296	WITHIN		TODO
297	WORD		TODO
298	WORDS	( -- )	TODO the names in the CONTEXT vocabulary, the newest first, a blank after each, a new line whenever one has passed column 64. Hidden entries -- a definition under way -- are not shown. (Q)+0 is the column.
299	XOR		TODO
300	[		TODO
301	[']		TODO ['] xxx the same inside a definition, whatever STATE is; and [LITERAL], which v3 has as another name for LITERAL.
302	[COMPILE]		TODO [COMPILE] xxx FORTH-79: compile xxx even though it is immediate
303	[LITERAL]		TODO
304	\		TODO
305	]		TODO