ruv/proposal.md Secret

## proposal.md

      
    Raw
  

              proposal.md
            
          
    Author

Ruv
Change Log

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.
2025-09-03: Huge update. Simplify the prose based on the updated definition for execution semantics.
Update the glossary entry for search-wordlist.
Problem

The descriptions of the problem and solution are the same as in the previous version
"immediate" is used incorrectly, i.e. it is wrong
for dual-xt systems.
The normative text for find is not quite correct and conflicts with other parts of the standard.
This should be corrected.
(from another proposal, to be updated)
it says that FIND returns the execution token of the Forth definition ("its execution token", so it should identify the execution semantics of that definition), but:

FIND may return two different tokens
(one while compiling and another while not compiling)
for the same string
(and, formally, the same Forth definition),
which may identify different semantics;
then at least one of them
does not identify the execution semantics
of the definition (despite the statement).

As a consequence of the above,
It is unclear how to perform the interpretation and compilation semantics for a named Forth definition using find.
But it should be absolutely clear.
The standard is used as the reference for new implementations.
Many of them provide find, and don't provide find-name.
Using find is the only standard way to determine
whether a word is an ordinary word,
or whether a word is an immediate word (because currently "immediate" specified, but wrong for dual-xt systems).
Solution

Update the glossary entry for find

see-also: my comment

Updated and harmonize the glossary entry for search-wordlist with the updated glossary entry for find.
Proposal

Update search find

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.
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 Ertel 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 core find

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 not compiling.
If a definition is found,
the values returned have the following meanings:


If interpreting, xt is the execution token of the found definition,
otherwise this 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 compiling and n is 1, executing xt in compilation state performs
the compilation semantics for the found definition.
An ambiguous condition exists if xt is executed
in interpretation state and at least one of the following is true:
a) the interpretation semantics for the found definition
are undefined by this standard;
b) xt is not the execution token for the found definition.


Note. A definition may be found while compiling but not found while interpreting.
See also:
3.4.2 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,
A.6.1.1550 FIND,
A.3.4.3.2 Interpretation semantics.
Update rationale for core find

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

According to the rules for the returned values,
the following must be true.


For an ordinary word in a single-xt system,
n is always -1
and xt is always the same.


For an ordinary word in a dual-xt system,
n is -1 while interpreting,
but may be 1 while compiling (in which case xt changes).


For an immediate word,
n is always 1,
xt may change, but typically it is always the same.


For a word with special interpretation semantics
and special compilation semantics
(like to)
in a typical dual-xt system,
n is always 1
and xt is one of two values.


If n is always -1 for a word,
then xt always identifies the same semantics.


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 ( c-addr u )
in the word list identified by wid.
If the definition is not found, return zero.
If the definition is found, return its execution token xt
and minus-one (-1)
if appending the execution semantics identified by xt
to the current definition
performs the compilation semantics for the found definition,
one (1) otherwise.
See also:
3.4.2 Finding definition names,
3.1.3.5 Execution tokens,
3.4.3.1 Execution semantics,
A.6.1.2192 SEARCH-WORDLIST.
Update rationale for search-wordlist

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

If the definition found is an immediate word,
the top return value is 1.
But if the top return value is 1,
the found definition is not necessarily an immediate word.
Because it may be a word (not a user-defined one in a standard program)
whose compilation semantics are implemented
using another definition.
If and only if the top return value is -1,
the definition found 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 Forth systems comply with this change.
Some dual-xt Forth systems provide an implementation for find
that is not comply with this change.
They should be updated to fix find or remove it.
ToDo


Add testing.


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

      
    Raw
  

              spec-for-find.variant-a.md
            
          
    (version A)

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-b.md

      
    Raw
  

              spec-for-find.variant-b.md
            
          
    (version B)

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.
If name has default interpretation semantics, xt is the execution token for name,
and n is 1 if name is immediate word, -1 otherwise.
The returned values are the same regardless whether the definition is found in interpretation state or in compilation state.
If name has other than default interpretation semantics, xt is the execution token
for an unspecified implementation-dependent definition,
and n is 1 or -1, and the following conditions are met.


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


When the definition is found in interpretation state: if n is 1,
xt and n are the same when the definition is found in compilation state,
otherwise n is -1, and both xt and n may be different when the definition is found in compilation state;
performing xt in interpretation state performs the interpretation semantics for name.


The definition may be not found in interpretation state but found in compilation state, and vise versa. Also a definition may be not found at all.


An ambiguous condition exists if xt 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 (see also 3.4.3.1). Default interpretation semantics for a definition is to perform its executin semantics in interpretation state (see also 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.
A program is allowed to apply FIND to any string. A definition may be not found even if a Forth system provides interpretation or compilation semantics for the corresponding name (for example, in the case of locals).

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

      
    Raw
  

              spec-for-find.variant-c.md
            
          
    (version C)

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).
No results found