title: HEADER words
status: unstandard

description:

>HEAD ( xt -- h-id ) "to-head"

 Return h-id, the "header identifier" of a wordlist entry that
 corresponds to xt. (Note 1: an xt may correspond to 0, 1 or many headers).
 (Note 2: on most systems, nfa (name field address) may serve as h-id,
 but in some exotic cases it is better to use some other value as h-id).

HEAD> ( h-id -- xt ) "head-from"

 Obtain the execution token for the word list entry identified by h-id.
 (Note: on some systems (e.g. gForth) multiple execution tokens correspond
 to a word list entry (compilation & interpretation actions)).

H>#NAME ( h-id -- addr len ) "h-to-hash-name"

 Return address and length of a string that contains the name.
 If FOO is defined,
 ' FOO >HEAD H>#NAME TYPE
 should print FOO .
 The word H>#NAME is allowed to store the name in a buffer whose contents
 become invalid after the next invokation of H>#NAME .

HFLAGS! ( x h-id -- ) "h-flags-store"

 store the flags specified by x to the flags field of the header
 specified by h-id.

HFLAGS@ ( h-id -- x ) "h-flags-fetch"

 return the flags from the flags field of the header specified by h-id.

 NB: the meaning of bits other than &IMMEDIATE and &HIDDEN
 is system-defined (e.g. name length & one reserved bit).

&IMMEDIATE ( -- x ) "ampersand-immediate"

 x is the mask of the immediacy bit.
 (x is a value with only one set bit; if the top stack value is an h-id,
 the phrase HFLAGS@ &IMMEDIATE AND returns a non-zero value if the word
 specified by the h-id is immediate. The phrase
 DUP HFLAGS@ &IMMEDIATE OR SWAP HFLAGS! makes the word, whose h-id
 was on the stack top, immediate.)

&HIDDEN ( -- x ) "ampersand-hidden"

 x is the mask of the bit that is set for words invisible for the
 dictionary serch. Some system do not use invisibility bits, but
 this name is reserved for this use.
 (x is a value with only one set bit; if the top stack value is an h-id,
 the phrase HFLAGS@ &HIDDEN AND returns a non-zero value if the word
 specified by the h-id is invisible for dictionary search routines.
 The phrase DUP HFLAGS@ &HIDDEN OR SWAP HFLAGS! makes the word, whose h-id
 was on the stack top, invisible for dictionary search.)

H>NEXT>H ( h-id -- h-id' ) "h-to-next-to-h"
 h-id' describes the next-in-chain word list header.
 When h-id identified the last-in-chain header, h-id' is zero.
 There is no guarantee that all word list entries
 belong to a single chain.

notes:

 These words are usable mostly in debugging/testing code,
 for the convenience of porting programmers.

 These words are user-reusable implementor's words.
 Most applications do not need these words, or need them only at
 the stage of debugging. If you are an implementor, you can use
 these words in your system's code, and know that these words
 may be portably reused. If you are an application programmer,
 you know that you can define these words on almost any Forth
 system with a few lines of system-dependent code.

 For now (Oct 2001) we are not even sure that access to headers needs
 standardization of some sort; but if it *is* needed, the practice
 will show it.

FAQ:

 Q: What is wrong with >NAME ?
 A: Each system defines the value returned by >NAME in its own unique way.
 The value may point to the beginning of the string containing the
 function name, or to the end of this string, or somewhere else.

 Q: Is NFA suitable as h-id?
 A: On some systems, yes. But on some other systems it is more
 convenient to use some other address for internal system purposes
 (for example, LFA). We did not require that h-id is the same as nfa
 to allow the use of h-id in the system internals.

 Q: Could you redefine >NAME to return h-id instead of NFA?
 A: No. (The existing [non-portable] code uses the existing >NAME .)

 Q: What is NFA?
 A: Name Field Address. How to obtain function name knowing that address
 is system-defined.

 Q: What is LFA?
 A: Link Field Address. Contains a sort of pointer to the next header in the
 word list chain. What that pointer is is system-defined.

page-written-by: mlg

notes:

 Guido Draheim writes:

 On the newsgroup most people did later agree that it is okay to let
 the return-value of NAME> to be used as the header-id. The participants
 agreed to call it name-token. An application may not assume a specific
 interpretation of this value, instead the word NAME>STRING must be used
 to convert the name-token into a name-string for COMPARE. This was
 accepted since it became obvious that many system implementations had
 lifted the traditional 31 char limit on names by using very different
 approaches being incompatible with traditional interpretation anyway.

 It was furthermore recognized that no common definition for a link-field
 interpretation can be given and that the problem should indeed be solved
 in a wordset targetting wordlist walking. Proposals came up that sniped
 the existance of a link-field altogether, energized by recognizing that
 many systems implement hashed wordlists and a real wordlist iterator must
 in fact have atleast two values to remember the current position and a
 simple name-token or exec-token or one-cell header-token is simply not
 enough.

 The discussion around bit-flags did not came to a conclusion, possibly
 due to lack of interest. It seems even the flags-get and flags-set
 operations has not found a common ground, some systems implement the
 hidden attribute without a bit btw.

 In the end, this wordset has not reached a consensus beyond mlg's
 considerable efforts in the topic, none of the words discussed
 was adopted widely but for NAME>STRING which can now even be seen
 as semi-standard, being ( name-token -- str-ptr str-len ).