ruv/find.test.fth Secret

## find.test.fth
\ 2026-05-31


\ A bit of a compatibility layer and test harness

synonym take-lexeme-maybe parse-name

: take-lexeme ( -- sd )
  take-lexeme-maybe dup if exit then
  -16 throw
;
: find-word ( sd -- 0 | xt 1 | xt -1 )
  <# dup >r holds r> hold 0. #> drop
  dup >r find
  dup if r> drop exit then
  swap r> <> abort" `find` changes c-addr"
;
: find-word-comp ( sd -- 0 | xt 1 | xt -1 )
  state @ >r ] find-word r> 0= if postpone [ then
;


\ Test cases


\ test `search-wordlist` in some edge cases

t{ s" \" forth-wordlist search-wordlist -> ' \  1 }t
t{ take-lexeme s" forth-wordlist search-wordlist -> ' s" 1 }t
t{ s" to" forth-wordlist search-wordlist -> ' to  1 }t
t{ s" is" forth-wordlist search-wordlist -> ' is  1 }t
t{ s" action-of" forth-wordlist search-wordlist -> ' action-of  1 }t


\ test `find` in some edge cases

t{ take-lexeme s" find-word swap ' s" = -> 1 true }t
t{ take-lexeme s" find-word-comp nip -> 1 }t

: s2"
  state @ if
    [ take-lexeme s" find-word-comp drop compile, ]
  else
    [ take-lexeme s" find-word drop compile, ]
  then
; immediate

t{ s2" foo" s" foo" compare 0= -> true }t
t{ :noname s2" foo" s" foo" compare 0= ; execute -> true }t

t{ s" to" find-word swap ' to = -> 1 true }t
t{ s" to" find-word-comp nip -> 1 }t

t{ 0 value x -> }t
t{ 1 ' to execute x  x -> 1 }t

: to2
  state @ if
    [ s" to" find-word-comp drop compile, ]
  else
    [ s" to" find-word drop compile, ]
  then
; immediate

t{ 2 to2 x  x -> 2 }t
t{ :noname 3 to2 x ; execute x -> 3 }t

## proposal.md

      
    Raw
  

              proposal.md
            
          
    Author

Ruv
Change Log

(the latest at the bottom)
2019-10-08: Initial version
2020-08-28: Avoid ambiguous clause "xt is the execution token for name" in the case of a word with non default interpretation semantics.
2021-04-18: Allow to return the different xt for any definition. More tight meaning of n in interpretation state. Avoid "implementation-dependent definition" and make the wording simpler.
2021-05-06: Correct meaning of n in interpretation state:
iff n is -1,
then xt identifies the execution semantics for name.
Eliminate the "default interpretation semantics" notion from the normative part.
2026-05-31: Major update.
Describe problems.
Simplify normative text using the updated execution semantics term description.
Update the glossary entry for search-wordlist.
2026-06-03: (to be updated)
Add links.
Improve wording in some places.
Problem

The proposal
[251] Clarification for execution token
already addresses the problems related to the lack of ambigous conditions in find and search-wordlist.
The remaining problems concern cases where
find returns different xt values depending on STATE.


The rationale A.6.1.1550
for 6.1.1550 FIND
explains that a word may exist in two versions: a compiling version and an interpreting version.
This means that each version of such a word has its own execution token
that identifies its own semantics,
and the phrase "its execution token" may refer to
one of these versions depending on STATE.
However, the normative parts of the standard
imply that a standard word has at most one execution token,
which identifies the execution semantics of the word.
So, the wording in the find specification leads to confusing.


The phrase "if the definition is immediate" is misleading
because, according to the rationale,
it may refer to different versions of the word depending on STATE,
but the normative parts of the standard
does not reflect this conception.


To ensure compatibility between classic single-xt systems
and dual-xt systems,
if special interpretation semantics are defined by the standard
for the found word
(such as for the words s" and to),
find must return 1 at the top regardless of STATE,
even if the word is not an immediate word.


Despite find-name has been standardized,
it is still worth clarifying the semantics of find
as find is provided more broadly than find-name
and is usually implemented in new Forth systems
(where the standard is used as the reference).
For example, in Forth implementations hosted on GitHub,
the word find (implemented in Forth) appears
approximately twice as often as the word find-name (implemented in Forth).

findin 136 files (at the date)
find-name in 66 files (at the date)

It should be noted that
incompatibilities caused by the aforementioned issues
can arise only on Forth systems where find depends on STATE
or where some unordinary words are not immediate;
howerver, in most Forth systems,
all unordinary words are immediate,
and find does not depend on STATE.
In turn,
a problem with search-wordlist can arise in cases
where find for the same word depends on STATE.
In some such cases the top output paramenter of search-wordlist
is 1,
but the word is not immediate
(i.e., performing its execution semantics in compilation state
does not perform the compilation semantics for the word).
Note: if a word is immediate, performing its execution semantics
in compilation state performs the compilation semantics for the word.
Solution

Update the glossary entry for find.
Update and harmonize with find
the glossary entry for search-wordlist
(see-also my comment).


Avoid referring to the execution token of the compiling version of a word (if any)
as the execution token of the word ("its execution token").


Avoid using the term "immediate".
Instead, specify how to perform the compilation semantics for the word.


Proposal

Update find in the Search-Order word set

In the glossary entry
16.6.1.1550 FIND
(in the optional
Search-Order word set),
remove the semantic description,
except the "See also" sub-section.
Add the following paragraph:

Note: If the optional Search-Order word set is provided,
FIND shall search all the word lists in the search order.

In the "See also" sub-section,
add:

16.3.3 Finding definition names.
16.6.1.1647 GET-ORDER.
16.6.1.2197 SET-ORDER.

Rationale

This glossary entry duplicates the glossary entry for
core find,
with only one difference: it mentions the search order.
However, this is no longer necessary,
as the term "find" is now updated by the Search-Order word set,
per the proposal
[115] Remove the “rules of FIND”
accepted in 2020.
The glossary entry itself should be kept to contain
the reference implementation
E.16.6.1.1550 FIND
from Annex E: Reference Implementations
and the test
F.16.6.1.1550 FIND
from Annex F: Test Suite.
See also:
the comment [r1372]
by Anton Ertl on 2024-11-25.
Note: If we remove the glossary entry 16.6.1.1550,
we should also remove the corresponding reference implementation and test,
but they are useful since find is actually indirectly updated
by the Search-Order word set
through updating the definition of the term "find".
Update find in the Core word set

In the glossary entry
6.1.1550 FIND,
replace the
semantic description
with the following:

( c-addr -- c-addr 0 | xt n )
Find a named Forth definition whose name matches the counted string at c-addr.
If the definition is not found, return c-addr and zero.
Otherwise, return the execution token xt
and n, which is either -1 or  1.
For a given string, the values returned while compiling
may differ from those returned while interpreting.
If a definition is found,
the following conditions shall be met:


If the definition is found in interpretation state,
xt is the execution token of the definition;
otherwise, the relationship between xt and the definition is implementation dependent.


If n is -1,
appending the execution semantics identified by xt
to the current definition
performs the compilation semantics for the found definition.


If the definition is found in compilation state and n is 1,
then:

Executing xt in compilation state performs
the compilation semantics for the definition.
An ambiguous condition exists if xt is executed
in interpretation state and at least one of the following conditions is true:

a) xt is not the execution token of the definition;
b) interpretation semantics for the definition
are undefined by this standard;


Note. A definition may be found while compiling but not found while interpreting.
See also:
3.4.2 Finding definition names,
16.3.3 Finding definition names,
3.1.3.5 Execution tokens,
3.4.3.1 Execution semantics,
3.4.3.2 Interpretation semantics,
3.4.3.3 Compilation semantics,
6.1.0070 ',
A.6.1.1550 FIND,
A.3.4.3.2 Interpretation semantics.

Rationale

The expression "the execution token of the definition" means
that we refer to the single execution token of the definition,
which is also returned by ' (Tick) and search-wordlist
(provided an appropriate word list is specified)
for the same definition.
There is no need to repeat the ambiguous conditions declared in
3.4.3.1 Execution semantics
(the updated version).
Update rationale for find in Core word set

In the section
A.6.1.1550 FIND,
add the following paragraphs at the end:

If the word find is executed in interpretation state and a definition is found,
it returns the same execution token
as ' (Tick) and search-wordlist (provided an appropriate word list is specified)
for the the same input string.
According to the requirements for the find word,
its resulting value ( xt n )
satisfies the following conditions.


If n is always -1 for a word (regardless of STATE),
then xt always identifies the same semantics
(even if it varies depending on STATE).


For an ordinary word in a single-xt system,
n is always -1
and xt is always the same (regardless of STATE).


For an ordinary word, its compilation semantics
in a dual-xt system
can be implemented in a separate definition
(typically, for optimization purposes),
in which case
n is -1 in interpretation state
and 1 in compilation state,
and xt varies depending on STATE.


For an immediate word,
n is always 1,
xt may vary depending on STATE
in a dual-xt system
(but typically it is always the same).


For a standard word with special interpretation semantics
and special compilation semantics
(like to and s") in a dual-xt system,
n is always 1
and xt may vary depending on STATE.


Update search-wordlist

In the glossary entry
16.6.1.2192 SEARCH-WORDLIST,
replace the
semantic description
with the following:

( c-addr u wid -- 0 | xt 1 | xt -1 )
Find a named Forth definition
whose name matches the character string identified by ( c-addr u )
in the word list identified by wid.
If no such definition is found, return zero;
otherwise return one of the other two options, where:

xt is the execution token of the found definition;
the top output parameter is minus-one (-1)
if appending the execution semantics identified by xt
to the current definition
performs the compilation semantics for the found definition;
otherwise the top output parameter is one (1).

See also:
16.3.3 Finding definition names,
3.1.3.5 Execution tokens,
3.4.3.1 Execution semantics,
A.6.1.2192 SEARCH-WORDLIST.

Rationale

There is no need to repeat the ambiguous conditions declared in
3.4.3.1 Execution semantics
(the updated version).
The terms "input stack parameters" and "output stack parameters"
are used in 2.2.2 Stack notation
(in the sentence "Stack parameters input to and output from a definition are ..."),
thus, they can be used normatively to refer to a stack parameter.
Alternative formulations include:

"the top output parameter is ...";
"the top returned value is ...";
specify the data type of the top output parameter as n (instead of 1 or -1)
in the stack diagram,
and refer to it using this data type symbol: "n is ...";

Update rationale for search-wordlist

In the section
A.6.1.2192 SEARCH-WORDLIST,
add the following paragraphs at the end:

If the found definition is an immediate word,
then the top output parameter is 1.
However, if the top output parameter is 1,
the found definition is not necessarily an immediate word,
since it may be a word (not a user-defined word in a standard program)
whose compilation semantics are implemented
using another definition.
If and only if the top output parameter is -1,
the found definition is an ordinary word
(a word with default interpretation semantics and default compilation semantics).
See also:
A.6.1.1550 FIND,
3.4.3.2 Interpretation semantics,
3.4.3.3 Compilation semantics.

Consequences

All classic single-xt Forth systems comply with this change.
In a few dual-xt Forth systems, the words find
or search-wordlist
do not comply with the prposed change.
They should be updated to ensure compliance.
Testing

See
find.test.fth.

  
## spec-for-find.variant-a.md

      
    Raw
  

              spec-for-find.variant-a.md
            
          
    (option A, 2020-03-06)

FIND
( c-addr -- c-addr 0 | xt n )
Find the definition name whose name matches the counted string at c-addr. If the definition is not found, return c-addr and zero. Otherwise the definition is found, return xt and n, where xt is the execution token for name, and n is 1 or -1.
If name has other than default interpretation semantics, all the returned values may differ between interpretation and compilation state; otherwise they are the same.
When the definition is found in interpretation state: if the definition is immediate then n is 1, otherwise n is -1; performing xt in interpretation state performs the interpretation semantics for name.
When the definition is found in compilation state: if n is -1, appending the execution semantics identified by xt to the current definition performs the compilation semantics for name, otherwise performing xt in compilation state performs the compilation semantics for name.
An ambiguous condition exists if xt returned by FIND is performed in the conditions that are not met the conditions specified above.

"Performing xt" means performing the execution semantics identified by the execution token xt.
A definition has default interpretation semantics if and only if the "Interpretation:" section is absent in the corresponding glossary entry, and the "Execution:" section is present. Default interpretation semantics for a definition is to perform its executin semantics in interpretation state (see also 3.4.3.2).

  
## spec-for-find.variant-c.md

      
    Raw
  

              spec-for-find.variant-c.md
            
          
    (option C, 2021-04-15)

Rationale
Features

Cover single-xt, dual-nt, and dual-xt systems.
Avoid ambiguous clause "xt is the execution token for name" in the case of a word with non default interpretation semantics.
Allow to return the different xt for any definition.
Tight meaning of n in interpretation state.
Gurantee that if name has default interpretation semantics, then ' name in interpretation state returns the same xt that FIND returns for name in interpretation state.


FIND
( c-addr -- c-addr 0 | xt n )
Find the definition name whose name matches the counted string at c-addr. If the definition is not found, return c-addr and zero.
Otherwise, return xt and n, where xt is an execution token and n is -1 or 1. The returned values may differ between interpretation and compilation state, and the following conditions shall be met:

if the definition is found in interpretation state, then

if and only if name is immediate, n is 1, otherwise n is -1;
if name has default interpretation semantics, xt indetifies the execution semantics for name;
performing xt in interpretation state performs the interpretation semantics for name;


if the definition is found in compilation state, then

if n is 1, performing xt in compilation state performs the compilation semantics for name;
if n is -1, appending the execution semantics identified by xt to the current definition performs the compilation semantics for name.


A definition may be found in compilation state but not found in interpretation state (or vise versa).
If the execution semantics identified by xt are specified either for interpretatin or for compilation state only (i.e., in the cases when the interpretation semantics for name are not default), it's ambiguous to perform these semantics in a state they are not specified for.

"Performing xt" means performing the execution semantics identified by the execution token xt.
A definition has default interpretation semantics if and only if the "Interpretation:" section is absent in the corresponding glossary entry (see 3.4.3.2).
If interpretation semantics are undefined for a definition, a Forth system is allowed to provide implementation-defined interpretation semantics for this definition (see A.3.4.3.2). In such case, when the definition is found in interpretation state, performing the returned xt in interpretation state performs the implementation-defined interpretation semantics for name.
If immediacy is not specified for a definition with non default interpretation semantics, a Forth system is still allowed to implement this definition as an immediate word by providing implementation-dependent execution semantics for this definition (see A.6.1.2033, A.6.1.1550).

  
## test-dualxt-via-find.fth
\ 2026-07-01 ruv
\
\ Count the number of words in forth-wordlist
\ for which `find` returns different results depending on STATE

[undefined] enter-compilation [if]
: compilation ( -- flag )  state @  0<> ;
: enter-compilation  ( -- )           ] ;
: leave-compilation  ( -- ) postpone  [ ;
[then]

: find-word ( sd -- 0 | xt 1 | xt -1 )
  <# dup >r holds r> hold 0. #> drop
  dup >r find
  dup if r> drop exit then
  swap r> <> abort" `find` changes c-addr"
;
: find-word-comp ( sd -- 0 | xt 1 | xt -1 )
  compilation invert >r  enter-compilation
    find-word
  r> if leave-compilation then
;

[undefined] ?found [if]
: ?found ( 0 -- never | x1\0 -- x1 )
  dup if exit then -13 throw
;
[then]

: is-nt-dualxt-via-find ( nt -- flag )
  name>string
  2dup find-word ?found
  2swap find-word-comp ?found
  d= invert
;


: (print-dualxt-via-find) ( n1 nt -- n2 true )
  dup is-nt-dualxt-via-find ( nt flag )
  if name>string type cr  1+ else drop then
  true
;
: print-dualxt-via-find ( -- )
  cr cr
  ." ----- dual-xt words in forth-wordlist" cr
  0 ['] (print-dualxt-via-find) forth-wordlist traverse-wordlist
  ." ----- number of dual-xt words: " . cr
;

synonym test print-dualxt-via-find

cr cr .( run `test` to check `find` for all words in forth-wordlist ) cr cr
	\ 2026-05-31


	\ A bit of a compatibility layer and test harness

	synonym take-lexeme-maybe parse-name

	: take-lexeme ( -- sd )
	take-lexeme-maybe dup if exit then
	-16 throw
	;
	: find-word ( sd -- 0 \| xt 1 \| xt -1 )
	<# dup >r holds r> hold 0. #> drop
	dup >r find
	dup if r> drop exit then
	swap r> <> abort" `find` changes c-addr"
	;
	: find-word-comp ( sd -- 0 \| xt 1 \| xt -1 )
	state @ >r ] find-word r> 0= if postpone [ then
	;



	\ Test cases


	\ test `search-wordlist` in some edge cases

	t{ s" \" forth-wordlist search-wordlist -> ' \ 1 }t
	t{ take-lexeme s" forth-wordlist search-wordlist -> ' s" 1 }t
	t{ s" to" forth-wordlist search-wordlist -> ' to 1 }t
	t{ s" is" forth-wordlist search-wordlist -> ' is 1 }t
	t{ s" action-of" forth-wordlist search-wordlist -> ' action-of 1 }t


	\ test `find` in some edge cases

	t{ take-lexeme s" find-word swap ' s" = -> 1 true }t
	t{ take-lexeme s" find-word-comp nip -> 1 }t

	: s2"
	state @ if
	[ take-lexeme s" find-word-comp drop compile, ]
	else
	[ take-lexeme s" find-word drop compile, ]
	then
	; immediate

	t{ s2" foo" s" foo" compare 0= -> true }t
	t{ :noname s2" foo" s" foo" compare 0= ; execute -> true }t

	t{ s" to" find-word swap ' to = -> 1 true }t
	t{ s" to" find-word-comp nip -> 1 }t

	t{ 0 value x -> }t
	t{ 1 ' to execute x x -> 1 }t

	: to2
	state @ if
	[ s" to" find-word-comp drop compile, ]
	else
	[ s" to" find-word drop compile, ]
	then
	; immediate

	t{ 2 to2 x x -> 2 }t
	t{ :noname 3 to2 x ; execute x -> 3 }t
	\ 2026-07-01 ruv
	\
	\ Count the number of words in forth-wordlist
	\ for which `find` returns different results depending on STATE

	[undefined] enter-compilation [if]
	: compilation ( -- flag ) state @ 0<> ;
	: enter-compilation ( -- ) ] ;
	: leave-compilation ( -- ) postpone [ ;
	[then]

	: find-word ( sd -- 0 \| xt 1 \| xt -1 )
	<# dup >r holds r> hold 0. #> drop
	dup >r find
	dup if r> drop exit then
	swap r> <> abort" `find` changes c-addr"
	;
	: find-word-comp ( sd -- 0 \| xt 1 \| xt -1 )
	compilation invert >r enter-compilation
	find-word
	r> if leave-compilation then
	;

	[undefined] ?found [if]
	: ?found ( 0 -- never \| x1\0 -- x1 )
	dup if exit then -13 throw
	;
	[then]

	: is-nt-dualxt-via-find ( nt -- flag )
	name>string
	2dup find-word ?found
	2swap find-word-comp ?found
	d= invert
	;


	: (print-dualxt-via-find) ( n1 nt -- n2 true )
	dup is-nt-dualxt-via-find ( nt flag )
	if name>string type cr 1+ else drop then
	true
	;
	: print-dualxt-via-find ( -- )
	cr cr
	." ----- dual-xt words in forth-wordlist" cr
	0 ['] (print-dualxt-via-find) forth-wordlist traverse-wordlist
	." ----- number of dual-xt words: " . cr
	;

	synonym test print-dualxt-via-find

	cr cr .( run `test` to check `find` for all words in forth-wordlist ) cr cr