6.15.2 Name token ¶

A name token (nt) represents a word, primarily a named word, but in Gforth since 1.0 unnamed words have a name token, too.

The name token is a cell-sized abstract data type that occurs as argument or result of the words below.

The difference between name token and execution token is that an execution token represents one behaviour, whereas a name token represents a word and all its properties, in particular its name and its behaviours (interpretation semantics, compilation semantics, possibly TO word semantics, etc.)

You get the nt of a word x with ``x (since Gforth 1.0) or with

find-name ( c-addr u – nt | 0  ) gforth-0.2

Find the name c-addr u in the current search order. Return its nt, if found, otherwise 0.

find-name-in ( c-addr u wid – nt | 0  ) gforth-1.0

Find the name c-addr u in the word list wid. Return its nt, if found, otherwise 0.

latest ( – nt|0  ) gforth-0.6

If the most recent word defined in the current section has a name, nt is its name token; otherwise, return 0.

latestnt ( – nt  ) gforth-1.0

nt is the name token of the most recent word (named or unnamed) defined in the current section.

>name ( xt – nt|0  ) gforth-0.2 “to-name”

For most words (all words with the default implementation of name>interpret), >name is the inverse of name>interpret: for these words nt name>interpret produces xt. For the other words name produces an nt for which nt default-name>int produces xt. Returns 0 if xt is not an xt (using a heuristic check that has a small chance of misidentifying a non-xt as xt), or (before Gforth 1.0) if xt is of an unnamed word. As of Gforth 1.0, unnamed words have nts, too, and >name produces an nt for xts of unnamed words.

xt>name ( xt – nt  ) gforth-1.0 “xt-to-name”

If xt is an execution token, produces the same nt as >name. Otherwise, nt is an arbitrary value.

You can get all the nts in a wordlist with

traverse-wordlist ( ... xt wid – ...  ) tools-ext

perform xt ( ... nt – f ... ) once for every word nt in the wordlist wid, until f is false or the wordlist is exhausted. xt is free to use the stack underneath.

You can use the nt to access the interpretation and compilation semantics of a word, its name, and the next word in the wordlist:

name>interpret ( nt – xt  ) tools-ext “name-to-interpret”

xt represents the interpretation semantics of the word nt.

name>compile ( nt – xt1 xt2  ) tools-ext “name-to-compile”

xt1 xt2 is the compilation token for the word nt (see Compilation token).

name>string ( nt – addr u  ) tools-ext “name-to-string”

addr count is the name of the word represented by nt.

id. ( nt –  ) gforth-0.6 “i-d-dot”

Print the name of the word represented by nt.

.id ( nt –  ) gforth-0.6 “dot-i-d”

F83 name for id..

compile-only? ( nt – flag  ) gforth-1.0 “compile-only-question”

true if nt is marked as compile-only.

obsolete? ( nt – flag  ) gforth-1.0 “obsolete-question”

true if nt is obsolete, i.e., will be removed in a future version of Gforth.

name>link ( nt1 – nt2 / 0  ) gforth-1.0 “name-to-link”

For a word nt1, returns the previous word nt2 in the same wordlist, or 0 if there is no previous word.

As a usage example, the following code lists all the words in forth-wordlist with non-default compilation semantics (including immediate words):

: ndcs-words ( wid -- )
  [: dup name>compile ['] compile, <> if over id. then 2drop true ;]
  swap traverse-wordlist ;

forth-wordlist ndcs-words

This code assumes that a word has default compilation semantics if the xt part of its compilation token is the xt of compile,.

Since Gforth 1.0 (but not in earlier versions or many other Forth systems), nameless words (see Anonymous Definitions) have nts and compilation semantics, and name>string works on them (producing a zero-length name). They are not in a wordlist, however. You can get the nt of a nameless word with latestnt.

Since Gforth 1.0, for most words the concrete implementation of their nt has the same numeric value as the xt that name>interpret produces for the nt. However for word w that is a synonym, alias, or is defined with interpret/compile:, intsem: etc., the xt produced by name>interpret has a different numeric value than the nt (and using >name on these xts will not produce the nt of w). Therefore, you cannot use xts and nts interchangeably, even if you are prepared to write code specific to Gforth 1.0.

The closest thing to the nt in classic Forth systems like fig-Forth is the name field address (NFA), but there are significant differences: in older Forth systems each word has a unique NFA, LFA, CFA and PFA (in this order, or LFA, NFA, CFA, PFA) and there are words for getting from one to the next. By contrast, in Gforth in general there is an n:1 relation between name tokens and the xt representing interpretation semantics; i.e., when you pass different nts to name>interpret, the result may be the same xt.

Another difference is that the NFA usually points to the start of the header, whereas the nt in Gforth 1.0 points to the body (and header fields are accessed with a negative offset).

Moreover, all of the header fields of the old systems correspond to fields in Gforth, but Gforth 1.0 has a few additional ones (see Header fields).