Digest #323 2026-02-10

Contributions

[422] 2026-02-08 17:05:32 EkkehardSkirl wrote:

proposal - An appendix grouped by word contexts

Author:

Ekkehard Skirl

Change Log:

2026-02-08 Initial proposal

Problem:

Append an appendix with forth words grouped by its contexts. This is in my eyes very useful especially for users that are not deeply knowing forth language yet.

Solution:

Append a appendix I - Context grouped wordlist

Proposal:

In Leo Brodie's book Starting Forth there is an appendix with the forth words grouped by headlines. This grouping of forth words looks very useful and if I started with forth I didn't have it. So many useful words from one context I didn't know about. The Forth Standard has only an alpha appendix of forth words. And of course the words could be members of multiple categories because of the category bridged character of some words.

For instance all words with names starting with 2 belong to 'Double Cell' and some additional to 'arithmetic' others to 'stack' and may be the 'stack' words contain additionally to 'control stack' or/and 'return stack'. So consequentially inside the grouped appendix forth words may appear multiple times if multiple contexts.

Unfortunately my knowledge about the words is not as great as it should be. So a common table would be nice to work on to add and discuss such categories in a draft file to bring things forward if there are enough people to have the same wish.

So here is a first draft as a discussion base for such a grouped appendix. This csv file (tab separated) is based on the standards appendix H and the grouping headlines of Leo Brodie's book Starting FORTH and works with Libre Office Calc. It already contains some additional edits. But it makes no claim to be complete, it's still a long way from that.

The grouping may happen by headlines and subheadlines.

Filename: forth_words_grouped_draft_V0.1a_tabs_20260208_1730.csv
Word Reference Description Wordset Category 1 Category 2 Category 3 Category 4 Category 5
2* 6.1.0320 two-star CORE Arithmetic Double Cell
2/ 6.1.0330 two-slash CORE Arithmetic Double Cell
* 6.1.0090 star CORE Arithmetic Single Cell
*/ 6.1.0100 star-slash CORE Arithmetic Single Cell
*/MOD 6.1.0110 star-slash-mod CORE Arithmetic Single Cell
+ 6.1.0120 plus CORE Arithmetic Single Cell
1+ 6.1.0290 one-plus CORE Arithmetic Single Cell
1- 6.1.0300 one-minus CORE Arithmetic Single Cell
ABS 6.1.0690 abs CORE Arithmetic Single Cell
- 6.1.0160 minus CORE Arithmetic
/ 6.1.0230 slash CORE Arithmetic
/MOD 6.1.0240 slash-mod CORE Arithmetic
FM/MOD 6.1.1561 f-m-slash-mod CORE Arithmetic
M* 6.1.1810 m-star CORE Arithmetic
MAX 6.1.1870 CORE Arithmetic
MIN 6.1.1880 CORE Arithmetic
MOD 6.1.1890 CORE Arithmetic
NEGATE 6.1.1910 CORE Arithmetic
SM/REM 6.1.2214 s-m-slash-rem CORE Arithmetic
UM* 6.1.2360 u-m-star CORE Arithmetic
UM/MOD 6.1.2370 u-m-slash-mod CORE Arithmetic
AND 6.1.0720 CORE Bitwise Operations
INVERT 6.1.1720 CORE Bitwise Operations
LSHIFT 6.1.1805 l-shift CORE Bitwise Operations
OR 6.1.1980 CORE Bitwise Operations
RSHIFT 6.1.2162 r-shift CORE Bitwise Operations
XOR 6.1.2490 x-or CORE Bitwise Operations
BLK 7.6.1.0790 b-l-k BLOCK Block I/O
BLOCK 7.6.1.0800 BLOCK Block I/O
BUFFER 7.6.1.0820 BLOCK Block I/O
EMPTY-BUFFERS 7.6.2.1330 BLOCK EXT Block I/O
FLUSH 7.6.1.1559 BLOCK Block I/O
LIST 7.6.2.1770 BLOCK EXT Block I/O
LOAD 7.6.1.1790 BLOCK Block I/O
SAVE-BUFFERS 7.6.1.2180 BLOCK Block I/O
SCR 7.6.2.2190 s-c-r BLOCK EXT Block I/O
THRU 7.6.2.2280 BLOCK EXT Block I/O
UPDATE 7.6.1.2400 BLOCK Block I/O
BL 6.1.0770 b-l CORE Characters
C" 6.2.0855 c-quote CORE EXT Characters
CHAR 6.1.0895 char CORE Characters
CHAR 18.6.2.0895 XCHAR EXT Characters
( 6.1.0080 paren CORE Comments
( 11.6.1.0080 paren FILE Comments
\ 6.2.2535 backslash CORE EXT Comments
\ 7.6.2.2535 backslash BLOCK EXT Comments
0< 6.1.0250 zero-less CORE Comparison Single Cell
0<> 6.2.0260 zero-not-equals CORE EXT Comparison Single Cell
0= 6.1.0270 zero-equals CORE Comparison Single Cell
0> 6.2.0280 zero-greater CORE EXT Comparison Single Cell
< 6.1.0480 less-than CORE Comparison Single Cell
<> 6.2.0500 not-equals CORE EXT Comparison Single Cell
= 6.1.0530 equals CORE Comparison Single Cell
> 6.1.0540 greater-than CORE Comparison Single Cell
U< 6.1.2340 u-less-than CORE Comparison
U> 6.2.2350 u-greater-than CORE EXT Comparison
WITHIN 6.2.2440 CORE EXT Comparison
' 6.1.0070 tick CORE Compilation
COMPILE, 6.2.0945 compile-comma CORE EXT Compilation
EXECUTE 6.1.1370 CORE Compilation
LITERAL 6.1.1780 CORE Compilation
QUIT 6.1.2050 CORE Compilation
[ 6.1.2500 left-bracket CORE Compilation
['] 6.1.2510 bracket-tick CORE Compilation
[CHAR] 6.1.2520 bracket-char CORE Compilation
[CHAR] 18.6.2.2520 bracket-char XCHAR EXT Compilation
] 6.1.2540 right-bracket CORE Compilation
, 6.1.0150 comma CORE Compiling Single Cell
[COMPILE] 6.2.2530 bracket-compile CORE EXT Compiling
+LOOP 6.1.0140 plus-loop CORE Control Flow
?DO 6.2.0620 question-do CORE EXT Control Flow
AGAIN 6.2.0700 CORE EXT Control Flow
BEGIN 6.1.0760 CORE Control Flow
CASE 6.2.0873 CORE EXT Control Flow
DO 6.1.1240 CORE Control Flow
ELSE 6.1.1310 CORE Control Flow
ENDCASE 6.2.1342 end-case CORE EXT Control Flow
ENDOF 6.2.1343 end-of CORE EXT Control Flow
EXIT 6.1.1380 CORE Control Flow
IF 6.1.1700 CORE Control Flow
LEAVE 6.1.1760 CORE Control Flow
LOOP 6.1.1800 CORE Control Flow
OF 6.2.1950 CORE EXT Control Flow
REPEAT 6.1.2140 CORE Control Flow
THEN 6.1.2270 CORE Control Flow
UNLOOP 6.1.2380 CORE Control Flow
UNTIL 6.1.2390 CORE Control Flow
WHILE 6.1.2430 CORE Control Flow
+FIELD 10.6.2.0135 plus-field FACILITY EXT Data Structure
BEGIN-STRUCTURE 10.6.2.0763 FACILITY EXT Data Structure
CFIELD: 10.6.2.0893 c-field-colon FACILITY EXT Data Structure
END-STRUCTURE 10.6.2.1336 FACILITY EXT Data Structure
FIELD: 10.6.2.1518 field-colon FACILITY EXT Data Structure
2CONSTANT 8.6.1.0360 two-constant DOUBLE Data Structures Double Cell
2VARIABLE 8.6.1.0440 two-variable DOUBLE Data Structures Double Cell
CONSTANT 6.1.0950 CORE Data Structures
DEFER 6.2.1173 CORE EXT Data Structures
FCONSTANT 12.6.1.1492 f-constant FLOATING Data Structures
VALUE 6.2.2405 CORE EXT Data Structures
VARIABLE 6.1.2410 CORE Data Structures
TIME&DATE 10.6.2.2292 time-and-date FACILITY EXT Date Time
? 15.6.1.0600 question TOOLS Debugging
ACTION-OF 6.2.0698 CORE EXT Deferred Words
DEFER! 6.2.1175 defer-store CORE EXT Deferred Words
DEFER@ 6.2.1177 defer-fetch CORE EXT Deferred Words
IS 6.2.1725 CORE EXT Deferred Words
>IN 6.1.0560 to-in CORE Dictionary
BASE 6.1.0750 CORE Dictionary
DECIMAL 6.1.1170 CORE Dictionary
FIND 6.1.1550 CORE Dictionary
FIND 16.6.1.1550 SEARCH Dictionary
HEX 6.2.1660 CORE EXT Dictionary
PARSE 6.2.2008 CORE EXT Dictionary
PARSE 18.6.2.2008 XCHAR EXT Dictionary
SOURCE 6.1.2216 CORE Dictionary
WORD 6.1.2450 CORE Dictionary
2LITERAL 8.6.1.0390 two-literal DOUBLE Double Number Double Cell
2VALUE 8.6.2.0435 two-value DOUBLE EXT Double Number Double Cell
D+ 8.6.1.1040 d-plus DOUBLE Double Number
D- 8.6.1.1050 d-minus DOUBLE Double Number
D. 8.6.1.1060 d-dot DOUBLE Double Number
D.R 8.6.1.1070 d-dot-r DOUBLE Double Number
D0< 8.6.1.1075 d-zero-less DOUBLE Double Number
D0= 8.6.1.1080 d-zero-equals DOUBLE Double Number
D2* 8.6.1.1090 d-two-star DOUBLE Double Number
D2/ 8.6.1.1100 d-two-slash DOUBLE Double Number
D< 8.6.1.1110 d-less-than DOUBLE Double Number
D= 8.6.1.1120 d-equals DOUBLE Double Number
D>S 8.6.1.1140 d-to-s DOUBLE Double Number
DABS 8.6.1.1160 d-abs DOUBLE Double Number
DMAX 8.6.1.1210 d-max DOUBLE Double Number
DMIN 8.6.1.1220 d-min DOUBLE Double Number
DNEGATE 8.6.1.1230 d-negate DOUBLE Double Number
DU< 8.6.2.1270 d-u-less DOUBLE EXT Double Number
M*/ 8.6.1.1820 m-star-slash DOUBLE Double Number
M+ 8.6.1.1830 m-plus DOUBLE Double Number
S>D 6.1.2170 s-to-d CORE Double Number
ABORT 6.1.0670 CORE Exceptions
ABORT 9.6.2.0670 EXCEPTION EXT Exceptions
ABORT" 6.1.0680 abort-quote CORE Exceptions
ABORT" 9.6.2.0680 abort-quote EXCEPTION EXT Exceptions
CATCH 9.6.1.0875 EXCEPTION Exceptions
THROW 9.6.1.2275 EXCEPTION Exceptions
EKEY>XCHAR 18.6.2.1306.60 e-key-to-x-char XCHAR EXT Extended Characters
X-SIZE 18.6.1.2486.50 XCHAR Extended Characters
X-WIDTH 18.6.2.2486.70 XCHAR EXT Extended Characters
XC!+ 18.6.1.2487.10 x-c-store-plus XCHAR Extended Characters
XC!+? 18.6.1.2487.15 x-c-store-plus-query XCHAR Extended Characters
XC, 18.6.1.2487.20 x-c-comma XCHAR Extended Characters
XC-SIZE 18.6.1.2487.25 x-c-size XCHAR Extended Characters
XC-WIDTH 18.6.2.2487.30 x-c-width XCHAR EXT Extended Characters
XC@+ 18.6.1.2487.35 x-c-fetch-plus XCHAR Extended Characters
XCHAR+ 18.6.1.2487.40 x-char-plus XCHAR Extended Characters
XCHAR- 18.6.2.2487.45 x-char-minus XCHAR EXT Extended Characters
XEMIT 18.6.1.2488.10 x-emit XCHAR Extended Characters
XHOLD 18.6.2.2488.20 x-hold XCHAR EXT Extended Characters
XKEY 18.6.1.2488.30 x-key XCHAR Extended Characters
XKEY? 18.6.1.2488.35 x-key-query XCHAR Extended Characters
R/O 11.6.1.2054 r-o FILE File Access
R/W 11.6.1.2056 r-w FILE File Access
W/O 11.6.1.2425 w-o FILE File Access
BIN 11.6.1.0765 FILE File I/O
CLOSE-FILE 11.6.1.0900 FILE File I/O
CREATE-FILE 11.6.1.1010 FILE File I/O
DELETE-FILE 11.6.1.1190 FILE File I/O
FILE-POSITION 11.6.1.1520 FILE File I/O
FILE-SIZE 11.6.1.1522 FILE File I/O
FILE-STATUS 11.6.2.1524 FILE EXT File I/O
FLUSH-FILE 11.6.2.1560 FILE EXT File I/O
INCLUDE 11.6.2.1714 FILE EXT File I/O
INCLUDE-FILE 11.6.1.1717 FILE File I/O
INCLUDED 11.6.1.1718 FILE File I/O
OPEN-FILE 11.6.1.1970 FILE File I/O
READ-FILE 11.6.1.2080 FILE File I/O
READ-LINE 11.6.1.2090 FILE File I/O
RENAME-FILE 11.6.2.2130 FILE EXT File I/O
REPOSITION-FILE 11.6.1.2142 FILE File I/O
REQUIRE 11.6.2.2144.10 FILE EXT File I/O
REQUIRED 11.6.2.2144.50 FILE EXT File I/O
RESIZE-FILE 11.6.1.2147 FILE File I/O
WRITE-FILE 11.6.1.2480 FILE File I/O
WRITE-LINE 11.6.1.2485 FILE File I/O
>FLOAT 12.6.1.0558 to-float FLOATING Floating Point
D>F 12.6.1.1130 d-to-f FLOATING Floating Point
DF! 12.6.2.1203 d-f-store FLOATING EXT Floating Point
DF@ 12.6.2.1204 d-f-fetch FLOATING EXT Floating Point
DFALIGN 12.6.2.1205 d-f-align FLOATING EXT Floating Point
DFALIGNED 12.6.2.1207 d-f-aligned FLOATING EXT Floating Point
DFFIELD: 12.6.2.1207.40 d-f-field-colon FLOATING EXT Floating Point
DFLOAT+ 12.6.2.1208 d-float-plus FLOATING EXT Floating Point
DFLOATS 12.6.2.1209 d-floats FLOATING EXT Floating Point
F! 12.6.1.1400 f-store FLOATING Floating Point
F* 12.6.1.1410 f-star FLOATING Floating Point
F** 12.6.2.1415 f-star-star FLOATING EXT Floating Point
F+ 12.6.1.1420 f-plus FLOATING Floating Point
F- 12.6.1.1425 f-minus FLOATING Floating Point
F. 12.6.2.1427 f-dot FLOATING EXT Floating Point
F/ 12.6.1.1430 f-slash FLOATING Floating Point
F0< 12.6.1.1440 f-zero-less-than FLOATING Floating Point
F0= 12.6.1.1450 f-zero-equals FLOATING Floating Point
F< 12.6.1.1460 f-less-than FLOATING Floating Point
F>D 12.6.1.1470 f-to-d FLOATING Floating Point
F>S 12.6.2.1471 F to S FLOATING EXT Floating Point
F@ 12.6.1.1472 f-fetch FLOATING Floating Point
FABS 12.6.2.1474 f-abs FLOATING EXT Floating Point
FACOS 12.6.2.1476 f-a-cos FLOATING EXT Floating Point
FACOSH 12.6.2.1477 f-a-cosh FLOATING EXT Floating Point
FALIGN 12.6.1.1479 f-align FLOATING Floating Point
FALIGNED 12.6.1.1483 f-aligned FLOATING Floating Point
FALOG 12.6.2.1484 f-a-log FLOATING EXT Floating Point
FASIN 12.6.2.1486 f-a-sine FLOATING EXT Floating Point
FASINH 12.6.2.1487 f-a-cinch FLOATING EXT Floating Point
FATAN 12.6.2.1488 f-a-tan FLOATING EXT Floating Point
FATAN2 12.6.2.1489 f-a-tan-two FLOATING EXT Floating Point
FATANH 12.6.2.1491 f-a-tan-h FLOATING EXT Floating Point
FCOS 12.6.2.1493 f-cos FLOATING EXT Floating Point
FCOSH 12.6.2.1494 f-cosh FLOATING EXT Floating Point
FDEPTH 12.6.1.1497 f-depth FLOATING Floating Point
FDROP 12.6.1.1500 f-drop FLOATING Floating Point
FDUP 12.6.1.1510 f-dupe FLOATING Floating Point
FE. 12.6.2.1513 f-e-dot FLOATING EXT Floating Point
FEXP 12.6.2.1515 f-e-x-p FLOATING EXT Floating Point
FEXPM1 12.6.2.1516 f-e-x-p-m-one FLOATING EXT Floating Point
FFIELD: 12.6.2.1517 f-field-colon FLOATING EXT Floating Point
FLITERAL 12.6.1.1552 f-literal FLOATING Floating Point
FLN 12.6.2.1553 f-l-n FLOATING EXT Floating Point
FLNP1 12.6.2.1554 f-l-n-p-one FLOATING EXT Floating Point
FLOAT+ 12.6.1.1555 float-plus FLOATING Floating Point
FLOATS 12.6.1.1556 FLOATING Floating Point
FLOG 12.6.2.1557 f-log FLOATING EXT Floating Point
FLOOR 12.6.1.1558 FLOATING Floating Point
FMAX 12.6.1.1562 f-max FLOATING Floating Point
FMIN 12.6.1.1565 f-min FLOATING Floating Point
FNEGATE 12.6.1.1567 f-negate FLOATING Floating Point
FOVER 12.6.1.1600 f-over FLOATING Floating Point
FROT 12.6.1.1610 f-rote FLOATING Floating Point
FROUND 12.6.1.1612 f-round FLOATING Floating Point
FS. 12.6.2.1613 f-s-dot FLOATING EXT Floating Point
FSIN 12.6.2.1614 f-sine FLOATING EXT Floating Point
FSINCOS 12.6.2.1616 f-sine-cos FLOATING EXT Floating Point
FSINH 12.6.2.1617 f-cinch FLOATING EXT Floating Point
FSQRT 12.6.2.1618 f-square-root FLOATING EXT Floating Point
FSWAP 12.6.1.1620 f-swap FLOATING Floating Point
FTAN 12.6.2.1625 f-tan FLOATING EXT Floating Point
FTANH 12.6.2.1626 f-tan-h FLOATING EXT Floating Point
FTRUNC 12.6.2.1627 f-trunc FLOATING EXT Floating Point
FVALUE 12.6.2.1628 f-value FLOATING EXT Floating Point
FVARIABLE 12.6.1.1630 f-variable FLOATING Floating Point
F~ 12.6.2.1640 f-proximate FLOATING EXT Floating Point
PRECISION 12.6.2.2035 FLOATING EXT Floating Point
REPRESENT 12.6.1.2143 FLOATING Floating Point
S>F 12.6.2.2175 S to F FLOATING EXT Floating Point
SET-PRECISION 12.6.2.2200 FLOATING EXT Floating Point
SF! 12.6.2.2202 s-f-store FLOATING EXT Floating Point
SF@ 12.6.2.2203 s-f-fetch FLOATING EXT Floating Point
SFALIGN 12.6.2.2204 s-f-align FLOATING EXT Floating Point
SFALIGNED 12.6.2.2206 s-f-aligned FLOATING EXT Floating Point
SFFIELD: 12.6.2.2206.40 s-f-field-colon FLOATING EXT Floating Point
SFLOAT+ 12.6.2.2207 s-float-plus FLOATING EXT Floating Point
SFLOATS 12.6.2.2208 s-floats FLOATING EXT Floating Point
SOURCE-ID 6.2.2218 source-i-d CORE EXT Input Handling
SOURCE-ID 11.6.1.2218 source-i-d FILE Input Handling
AT-XY 10.6.1.0742 at-x-y FACILITY Input/Output Mouse Handling
ACCEPT 6.1.0695 CORE Input/Output Terminal Input
EKEY 10.6.2.1305 e-key FACILITY EXT Input/Output Terminal Input
EKEY>CHAR 10.6.2.1306 e-key-to-char FACILITY EXT Input/Output Terminal Input
EKEY>FKEY 10.6.2.1306.40 e-key-to-f-key FACILITY EXT Input/Output Terminal Input
EKEY? 10.6.2.1307 e-key-question FACILITY EXT Input/Output Terminal Input
KEY 6.1.1750 CORE Input/Output Terminal Input
KEY? 10.6.1.1755 key-question FACILITY Input/Output Terminal Input
. 6.1.0180 dot CORE Input/Output Terminal Output
." 6.1.0190 dot-quote CORE Input/Output Terminal Output
.( 6.2.0200 dot-paren CORE EXT Input/Output Terminal Output
.R 6.2.0210 dot-r CORE EXT Input/Output Terminal Output
CR 6.1.0990 c-r CORE Input/Output Terminal Output
EMIT 6.1.1320 CORE Input/Output Terminal Output
EMIT? 10.6.2.1325 emit-question FACILITY EXT Input/Output Terminal Output
PAGE 10.6.1.2005 FACILITY Input/Output Terminal Output
SPACE 6.1.2220 CORE Input/Output Terminal Output
SPACES 6.1.2230 CORE Input/Output Terminal Output
TYPE 6.1.2310 CORE Input/Output Terminal Output
U. 6.1.2320 u-dot CORE Input/Output Terminal Output
U.R 6.2.2330 u-dot-r CORE EXT Input/Output Terminal Output
(LOCAL) 13.6.1.0086 paren-local-paren LOCAL Local Variables
LOCALS| 13.6.2.1795 locals-bar LOCAL EXT Local Variables
FALSE 6.2.1485 CORE EXT Logic
TRUE 6.2.2298 CORE EXT Logic
I 6.1.1680 CORE Loop Control
J 6.1.1730 CORE Loop Control
2! 6.1.0310 two-store CORE Memory Access Double Cell
2@ 6.1.0350 two-fetch CORE Memory Access Double Cell
! 6.1.0010 store CORE Memory Access Single Cell
+! 6.1.0130 plus-store CORE Memory Access Single Cell
@ 6.1.0650 fetch CORE Memory Access
C! 6.1.0850 c-store CORE Memory Access
C@ 6.1.0870 c-fetch CORE Memory Access
ALIGN 6.1.0705 CORE Memory Management
ALIGNED 6.1.0706 CORE Memory Management
ALLOCATE 14.6.1.0707 MEMORY Memory Management
ALLOT 6.1.0710 CORE Memory Management
BUFFER: 6.2.0825 buffer-colon CORE EXT Memory Management
CELL+ 6.1.0880 cell-plus CORE Memory Management
CELLS 6.1.0890 CORE Memory Management
CHAR+ 6.1.0897 char-plus CORE Memory Management
CHARS 6.1.0898 chars CORE Memory Management
ERASE 6.2.1350 CORE EXT Memory Management
FILL 6.1.1540 CORE Memory Management
FREE 14.6.1.1605 MEMORY Memory Management
HERE 6.1.1650 CORE Memory Management
MOVE 6.1.1900 CORE Memory Management
PAD 6.2.2000 CORE EXT Memory Management
RESIZE 14.6.1.2145 MEMORY Memory Management
# 6.1.0030 number-sign CORE Number Formatting
#> 6.1.0040 number-sign-greater CORE Number Formatting
#S 6.1.0050 number-sign-s CORE Number Formatting
<# 6.1.0490 less-number-sign CORE Number Formatting
HOLD 6.1.1670 CORE Number Formatting
HOLDS 6.2.1675 CORE EXT Number Formatting
SIGN 6.1.2210 CORE Number Formatting
S" 6.1.2165 s-quote CORE Other
S" 11.6.1.2165 s-quote FILE Other
SYNONYM 15.6.2.2264 TOOLS EXT Other
S" 11.6.2.2266 s-backslash-quote FILE EXT Other
S" 6.2.2266 s-backslash-quote CORE EXT Other
TO 6.2.2295 CORE EXT Other
UNUSED 6.2.2395 CORE EXT Other
{: 13.6.2.2550 brace-colon LOCAL EXT Other
>NUMBER 6.1.0570 to-number CORE Parsing
PARSE-NAME 6.2.2020 CORE EXT Parsing
REFILL 6.2.2125 CORE EXT Parsing
REFILL 7.6.2.2125 BLOCK EXT Parsing
REFILL 11.6.2.2125 FILE EXT Parsing
RESTORE-INPUT 6.2.2148 CORE EXT Parsing
SAVE-INPUT 6.2.2182 CORE EXT Parsing
2>R 6.2.0340 two-to-r CORE EXT Return Stack Double Cell
2R> 6.2.0410 two-r-from CORE EXT Return Stack Double Cell
2R@ 6.2.0415 two-r-fetch CORE EXT Return Stack Double Cell
>R 6.1.0580 to-r CORE Return Stack
R> 6.1.2060 r-from CORE Return Stack
R@ 6.1.2070 r-fetch CORE Return Stack
ALSO 16.6.2.0715 SEARCH EXT Search Order Dictionaries
DEFINITIONS 16.6.1.1180 SEARCH Search Order Dictionaries
FORTH 16.6.2.1590 SEARCH EXT Search Order Dictionaries
FORTH-WORDLIST 16.6.1.1595 SEARCH Search Order Dictionaries
GET-CURRENT 16.6.1.1643 SEARCH Search Order Dictionaries
GET-ORDER 16.6.1.1647 SEARCH Search Order Dictionaries
PREVIOUS 16.6.2.2037 SEARCH EXT Search Order Dictionaries
SEARCH-WORDLIST 16.6.1.2192 SEARCH Search Order Dictionaries
SET-CURRENT 16.6.1.2195 SEARCH Search Order Dictionaries
SET-ORDER 16.6.1.2197 SEARCH Search Order Dictionaries
ONLY 16.6.2.1965 SEARCH EXT Search Order
WORDLIST 16.6.1.2460 SEARCH Search Order
2DROP 6.1.0370 two-drop CORE Stack Manipulation Double Cell
2DUP 6.1.0380 two-dupe CORE Stack Manipulation Double Cell
2OVER 6.1.0400 two-over CORE Stack Manipulation Double Cell
2ROT 8.6.2.0420 two-rote DOUBLE EXT Stack Manipulation Double Cell
2SWAP 6.1.0430 two-swap CORE Stack Manipulation Double Cell
?DUP 6.1.0630 question-dupe CORE Stack Manipulation
DEPTH 6.1.1200 CORE Stack Manipulation
DROP 6.1.1260 CORE Stack Manipulation
DUP 6.1.1290 dupe CORE Stack Manipulation
NIP 6.2.1930 CORE EXT Stack Manipulation
OVER 6.1.1990 CORE Stack Manipulation
PICK 6.2.2030 CORE EXT Stack Manipulation
ROLL 6.2.2150 CORE EXT Stack Manipulation
ROT 6.1.2160 rote CORE Stack Manipulation
SWAP 6.1.2260 CORE Stack Manipulation
TUCK 6.2.2300 CORE EXT Stack Manipulation
-TRAILING-GARBAGE 18.6.2.0175 minus-trailing-garbage XCHAR EXT Strings Xchar
+X/STRING 18.6.2.0145 plus-x-string XCHAR EXT Strings
-TRAILING 17.6.1.0170 dash-trailing STRING Strings
/STRING 17.6.1.0245 slash-string STRING Strings
BLANK 17.6.1.0780 STRING Strings
C, 6.1.0860 c-comma CORE Strings
CMOVE 17.6.1.0910 c-move STRING Strings
CMOVE> 17.6.1.0920 c-move-up STRING Strings
COMPARE 17.6.1.0935 STRING Strings
COUNT 6.1.0980 CORE Strings
REPLACES 17.6.2.2141 STRING EXT Strings
SEARCH 17.6.1.2191 STRING Strings
SLITERAL 17.6.1.2212 STRING Strings
SUBSTITUTE 17.6.2.2255 STRING EXT Strings
UNESCAPE 17.6.2.2375 STRING EXT Strings
X\STRING- 18.6.2.2495 x-string-minus XCHAR EXT Strings
.S 15.6.1.0220 dot-s TOOLS System
BYE 15.6.2.0830 TOOLS EXT System
DUMP 15.6.1.1280 TOOLS System
ENVIRONMENT? 6.1.1345 environment-query CORE System
EVALUATE 6.1.1360 CORE System
EVALUATE 7.6.1.1360 BLOCK System
MARKER 6.2.1850 CORE EXT System
MS 10.6.2.1905 FACILITY EXT System
SEE 15.6.1.2194 TOOLS System
WORDS 15.6.1.2465 TOOLS System
K-ALT-MASK 10.6.2.1740.01 FACILITY EXT Terminal Input Keyboard Key
K-CTRL-MASK 10.6.2.1740.02 FACILITY EXT Terminal Input Keyboard Key
K-DELETE 10.6.2.1740.03 FACILITY EXT Terminal Input Keyboard Key
K-DOWN 10.6.2.1740.04 FACILITY EXT Terminal Input Keyboard Key
K-END 10.6.2.1740.05 FACILITY EXT Terminal Input Keyboard Key
K-F1 10.6.2.1740.06 k-f-1 FACILITY EXT Terminal Input Keyboard Key
K-F10 10.6.2.1740.07 k-f-10 FACILITY EXT Terminal Input Keyboard Key
K-F11 10.6.2.1740.08 k-f-11 FACILITY EXT Terminal Input Keyboard Key
K-F12 10.6.2.1740.09 k-f-12 FACILITY EXT Terminal Input Keyboard Key
K-F2 10.6.2.1740.10 k-f-2 FACILITY EXT Terminal Input Keyboard Key
K-F3 10.6.2.1740.11 k-f-3 FACILITY EXT Terminal Input Keyboard Key
K-F4 10.6.2.1740.12 k-f-4 FACILITY EXT Terminal Input Keyboard Key
K-F5 10.6.2.1740.13 k-f-5 FACILITY EXT Terminal Input Keyboard Key
K-F6 10.6.2.1740.14 k-f-6 FACILITY EXT Terminal Input Keyboard Key
K-F7 10.6.2.1740.15 k-f-7 FACILITY EXT Terminal Input Keyboard Key
K-F8 10.6.2.1740.16 k-f-8 FACILITY EXT Terminal Input Keyboard Key
K-F9 10.6.2.1740.17 k-f-9 FACILITY EXT Terminal Input Keyboard Key
K-HOME 10.6.2.1740.18 FACILITY EXT Terminal Input Keyboard Key
K-INSERT 10.6.2.1740.19 FACILITY EXT Terminal Input Keyboard Key
K-LEFT 10.6.2.1740.20 FACILITY EXT Terminal Input Keyboard Key
K-NEXT 10.6.2.1740.21 FACILITY EXT Terminal Input Keyboard Key
K-PRIOR 10.6.2.1740.22 FACILITY EXT Terminal Input Keyboard Key
K-RIGHT 10.6.2.1740.23 FACILITY EXT Terminal Input Keyboard Key
K-SHIFT-MASK 10.6.2.1740.24 FACILITY EXT Terminal Input Keyboard Key
K-UP 10.6.2.1740.25 FACILITY EXT Terminal Input Keyboard Key
AHEAD 15.6.2.0702 TOOLS EXT Tools
ASSEMBLER 15.6.2.0740 TOOLS EXT Tools
CODE 15.6.2.0930 TOOLS EXT Tools
CS-PICK 15.6.2.1015 c-s-pick TOOLS EXT Tools
CS-ROLL 15.6.2.1020 c-s-roll TOOLS EXT Tools
EDITOR 15.6.2.1300 TOOLS EXT Tools
FORGET 15.6.2.1580 TOOLS EXT Tools
N>R 15.6.2.1908 n-to-r TOOLS EXT Tools
NAME>COMPILE 15.6.2.1909.10 name-to-compile TOOLS EXT Tools
NAME>INTERPRET 15.6.2.1909.20 name-to-interpret TOOLS EXT Tools
NAME>STRING 15.6.2.1909.40 name-to-string TOOLS EXT Tools
NR> 15.6.2.1940 n-r-from TOOLS EXT Tools
STATE 6.1.2250 CORE Tools
STATE 15.6.2.2250 TOOLS EXT Tools
TRAVERSE-WORDLIST 15.6.2.2297 TOOLS EXT Tools
[DEFINED] 15.6.2.2530.30 bracket-defined TOOLS EXT Tools
[ELSE] 15.6.2.2531 bracket-else TOOLS EXT Tools
[IF] 15.6.2.2532 bracket-if TOOLS EXT Tools
[THEN] 15.6.2.2533 bracket-then TOOLS EXT Tools
[UNDEFINED] 15.6.2.2534 bracket-undefined TOOLS EXT Tools
: 6.1.0450 colon CORE Word Definition
:NONAME 6.2.0455 colon-no-name CORE EXT Word Definition
; 6.1.0460 semicolon CORE Word Definition
;CODE 15.6.2.0470 semicolon-code TOOLS EXT Word Definition
CREATE 6.1.1000 CORE Word Definition
DOES> 6.1.1250 does CORE Word Definition
IMMEDIATE 6.1.1710 CORE Word Definition
POSTPONE 6.1.2033 CORE Word Definition
RECURSE 6.1.2120 CORE Word Definition
>BODY 6.1.0550 to-body CORE Word Handling
ORDER 16.6.2.1985 SEARCH EXT Word List Dictionaries
[423] 2026-02-09 11:33:18 EkkehardSkirl wrote:

requestClarification - The buffer containing c-addr u may be transient and valid until the next invocation of NAME>STRING

(1) Being transient until the next call to 'NAME>STRING' necessitates that this word requires its own transient space and cannot use the transient spaces of other words or a central transient space while, for example, a word search is running " (see also (3)(a)). So more precise may be "... and is valid ...".

(2) Not being transient leads to duplicate longtime storage of the same information in cases where the name is stored in a system-specific way other than returned.

(3) What is the purpose of this word? To retrieve the name of a compiled word. But for what purpose? Since the name of a word only plays a role in interpretation and is then only implicitly stored as 'xt', I currently find only two reasons:

(3a) Word searches during interpretation or compilation, especially in systems that use a different form of name storage.

(3b) Debugging or recompiling a word.

However, neither of these necessitates storing the name string non-transiently as long as NAME>STRING uses its own transient area.

(4) The standard does not impose a transient storage area on any system, because it states "The buffer containing c-addr u may be ...".

Replies

[r1610] 2025-12-28 14:41:57 mykesx replies:

requestClarification - Getting the block contents

@ruv

You don’t have to define the blocks word set version of EVALUATE before you define LOAD. That would be a bug, so don’t do it that way.

My implementation of EVALUATE is

: LOAD BLOCK 1024 EVALUATE ; : EVALUATE 0 BLK ! EVALUATE ;

Both use the base EVALUATE.

[r1611] 2025-12-28 19:36:55 ruv replies:

requestClarification - Getting the block contents

@mykesx, previously you wrote: "This uses the EVALUATE defined in the BLOCKs wordset".

It is incorrect to use EVALUTE defined in BLOCKs wordset because it stores 0 in BLK, but BLK must contain the actual block number.

My implementation of EVALUATE is
: LOAD BLOCK 1024 EVALUATE ; : EVALUATE 0 BLK ! EVALUATE ;

Both use the base EVALUATE.

It is possible to use the base EVALUATE, but I don't see where you store u in BLK, and where you restore BLK (to restore the input source specification).

A possible implementation:

: LOAD ( i*x u -- j*x )
  BLK @ >R  DUP BLK !
  BLOCK 1024  ['] EVALUATE CATCH
  R> BLK !   THROW
;
: EVALUATE ( i*x c-addr u -- j*x )
  BLK @ >R  0 BLK !
  ['] EVALUATE CATCH
  R> BLK !   THROW
;

Testcase:

1 CONSTANT N \ block number for testing
N BLOCK 1024 BLANK \ clear the block N (in the memory only)
'|' PARSE  BLK @  S" BLK @" EVALUATE BLK @ |  CHARS  N BLOCK SWAP MOVE  T{ N LOAD -> N 0 N }T
[r1612] 2026-02-01 16:37:31 ruv replies:

proposal - New words: latest-name and latest-name-in

Interestingly, in FIG-Forth the word latest behaves very similarly to the proposed latest-name. Citation:

LATEST --- addr
        Leave the name field address of the topmost word in the CURRENT
        vocabulary.
[r1613] 2026-02-08 12:00:23 EkkehardSkirl replies:

proposal - Relax documentation requirements of Ambiguous Conditions

I agree with the publisher of the proposal. Why shouldn't a FORTH system be considered a standard if part of the documentation is missing, even though the system itself meets the standard?

An ambiguous situation is, at first glance, always ambiguous. Therefore, the programmer must handle and mitigate it to ensure the software's security. Any documentation merely serves to simplify things for the programmer, helping them understand the current system's response.

However, the goal of a standard is maximum portability. To achieve portable software, documented ambiguous situations must be addressed, and this is the responsibility of the programmer using such a system.

And I also agree that it makes sense to strive to reduce the number of ambiguous situations. Unfortunately, some are due to differences in physical systems, and others arise from the desire for the broadest possible compatibility with existing systems.

[r1614] 2026-02-08 22:29:46 AntonErtl replies:

proposal - Recognizer committee proposal 2025-09-11

Recognizer committee proposal 2025-09-11

The committee has found consensus on the words in this proposal. I was asked to write it up.

Author:

M. Anton Ertl (based on previous work by Matthias Trute, Bernd Paysan, and others, and the input of the standardization committee).

Change Log:

  • 2026-02-08 Fleshed out proposal; worked in feedback up to now.
  • 2025-09-12 [r1535] Some fixes
  • 2025-09-12 [412] Initial version

Problem:

The classical text interpreter is inflexible: E.g., adding floating-point recognizers requires hardcoding the change; several systems include system-specific hooks (sometimes more than one) for plugging in functionality at various places in the text interpreter.

The difficulty of adding to the text interpreter may also have led to missed opportunities: E.g., for string literals the standard did not task the text interpreter with recognizing them, but instead introduced S" and S\" (and their complicated definition with interpretation and compilation semantics).

Solution:

The recognizer proposal is a factorization of the central part of the text interpreter.

As before the text interpreter parses a white-space-delimited string. Unlike before, the string is now passed to the recognizers in the default recognizer sequence rec-forth, one recognizer after another, until one matches. The result of the matching recognizer is a translation, an on-stack representation of the word or literal. The translation is then processed according to the text-interpreter's state (interpreting, compiling, postponing).

There are five usage levels of recognizers and related recognizer words:

  1. Programs that use the default recognizers. This is the common case, and is essentially like using the traditional hard-coded Forth text interpreter. You do not need to use recognizer words for this level, but you can inform yourself about the recognizers in the current default recognizer sequence with recs. The default recognizer sequence contains at least rec-name and rec-number, and, if the Floating-Point wordset is present, rec-float. Moreover, programmers can now postpone numbers and other recognized things.

  2. Programs that change which of the existing recognizers are used and in what order. The default recognizer sequence is rec-forth. You can get the recognizers in it with get-recs and set them with set-recs. You can also create a recognizer sequence (which is a recognizer itself) with rec-sequence:. This proposal contains pre-defined recognizers rec-name rec-number rec-float rec-none, which can be used with set-recs or for defining a recognizer sequence.

  3. Programs that define new recognizers that use existing translation tokens. New recognizers are usually colon definitions, proposed-standard translation tokens are translate-none translate-cell translate-dcell translate-float translate-name.

  4. Programs that define new translation tokens. New translation tokens are defined with translate:.

  5. Programs that define text interpreters and programming tools that have to deal with recognizers. Words for achieving that are not defined in this proposal, but discussed in the rationale.

See the rationale for more detail and answers to specific questions.

Reference implementation:

TBD.

Testing:

TBD.

Proposal:

Usage requirements:

Data Types

translation: The result of a recognizer; the input of interpreting, compiling, and postponing; it's a semi-opaque type that consists of a translation token at the top of the data stack and additional data on various stacks below.

translation token: (This has formerly been called a rectype.) Single-cell item that identifies a certain translation.

Translations and text-interpretation

A recognizer pushes a translation on the stack(s). The text interpreter (and other users, such as postpone) removes the translation from the stack(s), and then either performs the interpreting run-time, compiling run-time, or postponing run-time.

All the proposed-standard translate-... words only push a translation token. Their stack effects are specified as expecting some data on the stack and pushing a translation. This shows what data is required in addition to the translation token to form a complete translation. A proposed-standard translate-... word pushes the same translation token every time it is invoked.

Compiling and postponing run-time

Unless otherwise specified, the compiling run-time compiles the interpreting run-time. The postponing run-time compiles the compiling run-time.

Exceptions

Add the following exception to table 9.1:

-80 too many recognizers

Words

rec-name ( c-addr u -- translation )

(formerly rec-nt)

If c-addr u is the name of a visible local or a visible named word, translation represents the text-interpretation semantics (interpreting, compiling, postponing) of that word (see translate-name). If not, translation is translate-none.

rec-number ( c-addr u -- translation )

(formerly rec-num) If c-addr u is a single or double number (without or with prefix), or a character, all as described in section 3.4.1.3 (Text interpreter input number conversion), translation represents pushing that number at run-time (see translate-cell, translate-dcell). If not, translation is translate-none.

rec-float ( c-addr u -- translation )

If c-addr u is a floating-point number, as described in section 12.3.7 (Text interpreter input number conversion), translation represents pushing that number at run-time (see translate-float). If c-addr u has the syntax of a double number without prefix according to section 8.3.1 (Text interpreter input number conversion), and it corresponds to the floating-point number r according to section 12.6.1.0558 (>float), translation may represent pushing r at run-time. If c-addr u is not recognized as a floating-point number, translation is translate-none.

rec-none ( c-addr u -- translation )

This word does not recognize anything. For its translation, see translate-none.

recs ( -- )

(formerly .recognizers) Print the recognizers in the recognizer sequence in rec-forth, the first searched recognizer leftmost.

rec-forth ( c-addr u -- translation )

(formerly forth-recognize) This is a deferred word that contains the recognizer (sequence) that is used by the Forth text interpreter.

rec-sequence: ( xtu .. xt1 u "name" -- )

Define a recognizer sequence "name" containing u recognizers represented by their xts. If set-recs is implemented, the sequence must be able to accomodate at least 16 recognizers.

name execution: ( c-addr u -- translation )

Execute xt1; if the resulting translation is the result of translate-none, restore the data stack to ( c-addr u -- ) and try the next xt. If there is no next xt, remove ( c-addr u -- ) and perform translate-none.

translate-none ( -- translation )

(formerly r:fail or notfound)

translation interpreting run-time: ( ... -- )

-13 throw

translation compiling run-time: ( ... -- )

-13 throw

translation postponing run-time: ( ... -- )

-13 throw

translate-cell ( x -- translation )

(formerly translate-num)

translation interpreting run-time: ( -- x )

translate-dcell ( xd -- translation )

(formerly translate-dnum)

translation interpreting run-time: ( -- xd )

translate-float ( r -- translation )

translation interpreting run-time: ( -- r )

translate-name ( nt -- translation )

(formerly translate-nt)

translation interpreting run-time: ( ... -- ... )

Perform the interpretation semantics of nt.

translation compiling run-time: ( ... -- ... )

Perform the compilation semantics of nt.

translate: ( xt-int xt-comp xt-post "name" -- )

(formerly rectype:)

Define "name"

"name" exection: ( i*x -- translation )

"name" interpreting action: ( ... translation -- ... )

Remove the top of stack (the translation token) and execute xt-int.

"name" compiling action: ( ... translation -- ... )

Remove the top of stack (the translation token) and execute xt-comp.

"name" postponing action: ( translation -- )

Remove the top of stack (the translation token) and execute xt-post.

get-recs ( xt -- xt_u ... xt_1 u )

xt is the execution token of a recognizer sequence. xt_1 is the first recognizer searched by this sequence, xt_u is the last one.

set-recs ( xt_u ... xt_1 u xt -- )

xt is the execution token of a recognizer sequence. Replace the contents of this sequence with xt_u ... xt_1, where xt_1 is searched first, and xt_u is searched last. Throw -80 (too many recognizers) if u exceeds the number of elements supported by the recognizer sequence.

postpone

Interpretation:

Interpretation semantics for this word are undefined.

Compilation: ( "<spaces>name" -- )

Skip leading space delimiters. Parse name delimited by a space. Use rec-forth to recognize name, resulting in translation with translation-token. For a system-defined translation token, first consume the translation, then compile the 'compiling' run-time. For a user-defined translation token, remove it from the stack and execute its post-xt.

Rationale

Names

The names of terms and the proposed Forth words in this proposal have been arrived at after several lengthy discussions in the committee. Experience tells me that many readers (including from the committee) will take issue with one or the other name, but any suggestion for changing names will be ignored by the me. If you want them changed, petition the committee (but I hope they will be as weary of renamings as I am).

In particular, I suggested to use "recognized" instead of "translation", and IIRC also to rename the translate-... words accordingly, but the committee eventually decided to stay with translation and translate-....

Face it: The names are good enough. Any renaming, even if it results in a better name, increases the confusion more than it helps: even committee members (culprits in the renaming game themselves) have complained about being confused by the new, possibly better names for concepts and words that have already been present in Matthias Trute's proposal.

If you want to improve the proposal, please read it, play with the words in Gforth, read the reference implementation and the tests when they arrive, and point out any mistake or lack of clarity.

Translation tokens and translate-... words

[r1541] points out interesting uses of knowledge about translation tokens, and, conflictingly, potential implementation variations. This proposal decides against the implementation variations and for the uses by specifying in the Usage Requirements that a translate-... word just pushes a translation token, and it always pushes the same one.

Discarding a translation

[r1541] also asks for a way to discard a translation. This need has also come up in some recognizers implemented in Gforth (e.g., rec-tick), and Gforth uses (non-standard) words like sp@ and sp! for that. Standard options would be to wrap the word that pushes a translation into catch and discard the stacks with a non-zero throw, or to use depth and fdepth in combination with loops of drop and fdrop; both ways are cumbersome. My feeling is that many in the committee and in the wider Forth community do not see the need for discard-translation yet; this may change in the future.

Consumers of translations (Usage level 5)

The committee has decided not to standardize words that consume translations for now. Such words would be useful for defining a user-defined text interpreter, but the experience with recognizers has shown that a recognizer-using text interpreter is flexible enough that it is no longer necessary to write such text interpreters, so such words are only used internally in the text interpreter, eliminating the need to standardize them.

However, to give an idea how all this works together, here's the words that Gforth provides for that purpose:

interpreting ( ... translation -- ... )

For a system-defined translation token, first remove the translation from the stack(s), then perform the interpreting run-time specified for the translation token. For a user-defined translation token, remove it from the stack and execute its int-xt.

compiling ( ... translation -- ... )

For a system-defined translation token, first remove the translation from the stacks, then perform the compiling run-time specified for the translation token, or, if none is specified, compile the 'interpreting' run-time. For a user-defined translation token, remove it from the stack and execute its comp-xt.

postponing ( ... translation -- )

For a system-defined translation token, first consume the translation, then compile the 'compiling' run-time. For a user-defined translation token, remove it from the stack and execute its post-xt.

Typical use:

s" 123" rec-forth ( translation ) interpreting ( n ) \ leaves 123 on the stack

: umin ( u1 u2 -- u )
  2dup u< if drop else nip then ;

: string-prefix? ( c-addr1 u1 c-addr2 u2 -- f )
    tuck 2>r umin 2r> compare 0= ;

: rec-tick ( addr u -- translation )
    2dup "`" string-prefix? if
        1 /string find-name dup if
            name>interpret translate-cell
        else
            drop translate-none then
        exit then
    \ this recognizer did not recognize anything, therefore:
    rec-none ;

' noop                       ( x -- x )                             \ int-xt
' lit,                       ( compilation: x -- ; run-time: -- x ) \ comp-xt
:noname lit, postpone lit, ; ( postponing: x -- ;  run-time: -- x ) \ post-xt
translate: translate-cell
[r1615] 2026-02-09 19:27:30 AntonErtl replies:

proposal - Recognizer committee proposal 2025-09-11

Recognizer committee proposal 2025-09-11

The committee has found consensus on the words in this proposal. I was asked to write it up.

Author:

M. Anton Ertl (based on previous work by Matthias Trute, Bernd Paysan, and others, and the input of the standardization committee).

Change Log:

  • 2026-02-09 Specify the translation tokens of the rec-... words. Also provide ( -- translation-token ) stack effects for translate-... words.

  • 2026-02-08 [r1614] Fleshed out proposal; worked in feedback up to now.

  • 2025-09-12 [r1535] Some fixes

  • 2025-09-12 [412] Initial version

Problem:

The classical text interpreter is inflexible: E.g., adding floating-point recognizers requires hardcoding the change; several systems include system-specific hooks (sometimes more than one) for plugging in functionality at various places in the text interpreter.

The difficulty of adding to the text interpreter may also have led to missed opportunities: E.g., for string literals the standard did not task the text interpreter with recognizing them, but instead introduced S" and S\" (and their complicated definition with interpretation and compilation semantics).

Solution:

The recognizer proposal is a factorization of the central part of the text interpreter.

As before the text interpreter parses a white-space-delimited string. Unlike before, the string is now passed to the recognizers in the default recognizer sequence rec-forth, one recognizer after another, until one matches. The result of the matching recognizer is a translation, an on-stack representation of the word or literal. The translation is then processed according to the text-interpreter's state (interpreting, compiling, postponing).

There are five usage levels of recognizers and related recognizer words:

  1. Programs that use the default recognizers. This is the common case, and is essentially like using the traditional hard-coded Forth text interpreter. You do not need to use recognizer words for this level, but you can inform yourself about the recognizers in the current default recognizer sequence with recs. The default recognizer sequence contains at least rec-name and rec-number, and, if the Floating-Point wordset is present, rec-float. Moreover, programmers can now postpone numbers and other recognized things.

  2. Programs that change which of the existing recognizers are used and in what order. The default recognizer sequence is rec-forth. You can get the recognizers in it with get-recs and set them with set-recs. You can also create a recognizer sequence (which is a recognizer itself) with rec-sequence:. This proposal contains pre-defined recognizers rec-name rec-number rec-float rec-none, which can be used with set-recs or for defining a recognizer sequence.

  3. Programs that define new recognizers that use existing translation tokens. New recognizers are usually colon definitions, proposed-standard translation tokens are translate-none translate-cell translate-dcell translate-float translate-name.

  4. Programs that define new translation tokens. New translation tokens are defined with translate:.

  5. Programs that define text interpreters and programming tools that have to deal with recognizers. Words for achieving that are not defined in this proposal, but discussed in the rationale.

See the rationale for more detail and answers to specific questions.

Reference implementation:

TBD.

Testing:

TBD.

Proposal:

Usage requirements:

Data Types

translation: The result of a recognizer; the input of interpreting, compiling, and postponing; it's a semi-opaque type that consists of a translation token at the top of the data stack and additional data on various stacks.

translation token: (This has formerly been called a rectype.) Single-cell item that identifies a certain kind of translation.

Translations and text-interpretation

A recognizer pushes a translation on the stack(s). The text interpreter (and other users, such as postpone) removes the translation from the stack(s), and then either performs the interpreting run-time, compiling run-time, or postponing run-time.

All the proposed-standard translate-... words only push a translation token, and that stack effect is given, but in addition the definitions of these words also show a "Stack effect to produce a translation"; this stack effect points out which additional stack items need to be pushed before the translation token in order to produce a translation.

A proposed-standard translate-... word pushes the same translation token every time it is invoked.

Compiling and postponing run-time

Unless otherwise specified, the compiling run-time compiles the interpreting run-time. The postponing run-time compiles the compiling run-time.

Exceptions

Add the following exception to table 9.1:

-80 too many recognizers

Words

rec-name ( c-addr u -- translation )

(formerly rec-nt)

If c-addr u is the name of a visible local or a visible named word, translation represents the text-interpretation semantics (interpreting, compiling, postponing) of that word, and has the translation token translate-name. If not, translation is translate-none.

rec-number ( c-addr u -- translation )

(formerly rec-num) If c-addr u is a single-cell or double-cell number (without or with prefix), or a character, all as described in section 3.4.1.3 (Text interpreter input number conversion), translation represents pushing that number at run-time. If a single-cell number is recognized, the translation token of translation is translate-cell, for a double cell translate-dcell. If neither is recognized, translation is translate-none.

rec-float ( c-addr u -- translation )

If c-addr u is a floating-point number, as described in section 12.3.7 (Text interpreter input number conversion), rec-float recognizes it as floating-point number r. If c-addr u has the syntax of a double number without prefix according to section 8.3.1 (Text interpreter input number conversion), and it corresponds to the floating-point number r according to section 12.6.1.0558 (>float), rec-float may (but is not required to) recognize it as a floating-point number. If rec-float recognized c-addr u as floating-point number, translation represents pushing that number at run-time, and the translation token is translate-float. If c-addr u is not recognized as a floating-point number, translation is translate-none.

rec-none ( c-addr u -- translation )

This word does not recognize anything. Its translation and translation token is translate-none.

recs ( -- )

(formerly .recognizers) Print the recognizers in the recognizer sequence in rec-forth, the first searched recognizer leftmost.

rec-forth ( c-addr u -- translation )

(formerly forth-recognize) This is a deferred word that contains the recognizer (sequence) that is used by the Forth text interpreter.

rec-sequence: ( xtu .. xt1 u "name" -- )

Define a recognizer sequence "name" containing u recognizers represented by their xts. If set-recs is implemented, the sequence must be able to accomodate at least 16 recognizers.

name execution: ( c-addr u -- translation )

Execute xt1; if the resulting translation is the result of translate-none, restore the data stack to ( c-addr u -- ) and try the next xt. If there is no next xt, remove ( c-addr u -- ) and perform translate-none.

get-recs ( xt -- xt_u ... xt_1 u )

xt is the execution token of a recognizer sequence. xt_1 is the first recognizer searched by this sequence, xt_u is the last one.

set-recs ( xt_u ... xt_1 u xt -- )

xt is the execution token of a recognizer sequence. Replace the contents of this sequence with xt_u ... xt_1, where xt_1 is searched first, and xt_u is searched last. Throw -80 (too many recognizers) if u exceeds the number of elements supported by the recognizer sequence.

translate-none ( -- translation-token )

(formerly r:fail or notfound)

Stack effect to produce a translation: ( -- translation )

translation interpreting run-time: ( ... -- )

-13 throw

translation compiling run-time: ( ... -- )

-13 throw

translation postponing run-time: ( ... -- )

-13 throw

translate-cell ( -- translation-token )

(formerly translate-num)

Stack effect to produce a translation: ( x -- translation )

translation interpreting run-time: ( -- x )

translate-dcell ( -- translation-token )

(formerly translate-dnum)

Stack effect to produce a translation: ( xd -- translation )

translation interpreting run-time: ( -- xd )

translate-float ( -- translation-token )

Stack effect to produce a translation: ( r -- translation )

translation interpreting run-time: ( -- r )

translate-name ( -- translation-token )

(formerly translate-nt)

Stack effect to produce a translation: ( nt -- translation )

translation interpreting run-time: ( ... -- ... )

Perform the interpretation semantics of nt.

translation compiling run-time: ( ... -- ... )

Perform the compilation semantics of nt.

translate: ( xt-int xt-comp xt-post "name" -- )

(formerly rectype:)

Define "name"

"name" exection: ( -- translation-token )

Stack effect to produce a translation: ( i*x -- translation )

"name" interpreting action: ( ... translation -- ... )

Remove the top of stack (the translation token) and execute xt-int.

"name" compiling action: ( ... translation -- ... )

Remove the top of stack (the translation token) and execute xt-comp.

"name" postponing action: ( translation -- )

Remove the top of stack (the translation token) and execute xt-post.

postpone

Interpretation:

Interpretation semantics for this word are undefined.

Compilation: ( "<spaces>name" -- )

Skip leading space delimiters. Parse name delimited by a space. Use rec-forth to recognize name, resulting in translation with translation-token. For a system-defined translation token, first consume the translation, then compile the 'compiling' run-time. For a user-defined translation token, remove it from the stack and execute its post-xt.

Rationale

Names

The names of terms and the proposed Forth words in this proposal have been arrived at after several lengthy discussions in the committee. Experience tells me that many readers (including from the committee) will take issue with one or the other name, but any suggestion for changing names will be ignored by the me. If you want them changed, petition the committee (but I hope they will be as weary of renamings as I am).

In particular, I suggested to use "recognized" instead of "translation", and IIRC also to rename the translate-... words accordingly, but the committee eventually decided to stay with translation and translate-....

Face it: The names are good enough. Any renaming, even if it results in a better name, increases the confusion more than it helps: even committee members (culprits in the renaming game themselves) have complained about being confused by the new, possibly better names for concepts and words that have already been present in Matthias Trute's proposal.

If you want to improve the proposal, please read it, play with the words in Gforth, read the reference implementation and the tests when they arrive, and point out any mistake or lack of clarity.

Translation tokens and translate-... words

[r1541] points out interesting uses of knowledge about translation tokens, and, conflictingly, potential implementation variations. This proposal decides against the implementation variations and for the uses by specifying in the Usage Requirements that a translate-... word just pushes a translation token, and it always pushes the same one.

Moreover, this proposal specifies the translation tokens that the proposed-standard recognizers produce. This is useful in various contexts where recognizers are not used directly in rec-forth, and it also makes it possible to write tests for the recognizers.

Discarding a translation

[r1541] also asks for a way to discard a translation. This need has also come up in some recognizers implemented in Gforth (e.g., rec-tick), and Gforth uses (non-standard) words like sp@ and sp! for that. Standard options would be to wrap the word that pushes a translation into catch and discard the stacks with a non-zero throw, or to use depth and fdepth in combination with loops of drop and fdrop; both ways are cumbersome. My feeling is that many in the committee and in the wider Forth community do not see the need for discard-translation yet; this may change in the future.

Consumers of translations (Usage level 5)

The committee has decided not to standardize words that consume translations for now. Such words would be useful for defining a user-defined text interpreter, but the experience with recognizers has shown that a recognizer-using text interpreter is flexible enough that it is no longer necessary to write such text interpreters, so such words are only used internally in the text interpreter, eliminating the need to standardize them.

However, to give an idea how all this works together, here's the words that Gforth provides for that purpose:

interpreting ( ... translation -- ... )

For a system-defined translation token, first remove the translation from the stack(s), then perform the interpreting run-time specified for the translation token. For a user-defined translation token, remove it from the stack and execute its int-xt.

compiling ( ... translation -- ... )

For a system-defined translation token, first remove the translation from the stacks, then perform the compiling run-time specified for the translation token, or, if none is specified, compile the 'interpreting' run-time. For a user-defined translation token, remove it from the stack and execute its comp-xt.

postponing ( ... translation -- )

For a system-defined translation token, first consume the translation, then compile the 'compiling' run-time. For a user-defined translation token, remove it from the stack and execute its post-xt.

Typical use:

s" 123" rec-forth ( translation ) interpreting ( n ) \ leaves 123 on the stack

: umin ( u1 u2 -- u )
  2dup u< if drop else nip then ;

: string-prefix? ( c-addr1 u1 c-addr2 u2 -- f )
    tuck 2>r umin 2r> compare 0= ;

: rec-tick ( addr u -- translation )
    2dup "`" string-prefix? if
        1 /string find-name dup if
            name>interpret translate-cell
        else
            drop translate-none then
        exit then
    \ this recognizer did not recognize anything, therefore:
    rec-none ;

' noop                       ( x -- x )                             \ int-xt
' lit,                       ( compilation: x -- ; run-time: -- x ) \ comp-xt
:noname lit, postpone lit, ; ( postponing: x -- ;  run-time: -- x ) \ post-xt
translate: translate-cell