/ header-uext /

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 ).


generated Wed Jul 23 02:53:38 2003mlg