The new Gforth word header is object-oriented and supports the following methods (method selectors):
method overrider field
execute set-execute >cfa
opt-compile, set-optimizer >hmcompile,
defer! set-to >hmto
defer@ set-defer@ >hmdefer@
>hmextra
name>interpret set->int >hm>int
name>compile set->comp >hm>comp
name>string set-name>string >hm>string
name>link set-name>link >hm>link
Many of these words are not stable Gforth words, but Gforth has stable higher-level words that we mention below.
Setter words change the most recent definition (which does not include completed quotations or closures).
The execute method is actually stored in the >cfa field
in the header rather than in the header-methods table for performance
reasons; also it is implemented through a native-code address, while
the other methods are implemented by calling an xt. The high-level
way to set this method is
set-execute ( ca – ) gforth-1.0 “Changes”
jumps to the native code at ca. Also changes the
compile, implementation to the most general (and
slowest) one. Call set-optimizer afterwards if you want
a more efficient implementation.
To get a code address for use with set-execute, you can use
words like docol: or >code-address, See Threading Words.
There is also set-does> (see User-defined Defining Words),
which takes an xt.
Moreover, there are the low-level code-address! and
definer!, See Threading Words.
The opt-compile, method is what compile, does on most
Gforth engines (gforth-itc uses , instead). You can
define a more efficient implementation of compile, for the
current word with set-optimizer. Note that the end result must
be equivalent to postpone literal postpone execute.
set-optimizer ( xt – ) gforth-1.0 “set-optimizer”
Changes the current word such that compile,ing it
executes xt (with the same stack contents as passed to
compile,. Note that compile, must be consistent
with execute, so you must use set-optimizer only
to install a more efficient implementation of the same
behaviour.
As an example of the use of set-optimizer, consider the
following definition of constant:
: constant ( n "name" -- ; name: -- n )
create ,
['] @ set-does>
;
5 constant five
: foo five ; see foo
The Forth system does not know that the value of a constant must not
be changed, and just sees a created word (which can be changed
with >body), and foo first pushes the body address of
five and then fetches from there. With set-optimizer
the definition of constant can be optimized as follows:
: constant ( n "name" -- ; name: -- n )
create ,
['] @ set-does>
[: >body @ postpone literal ;] set-optimizer
;
Now foo contains the literal 5 rather than a call to
five.
Note that set-execute and set-does> perform
set-optimizer themselves in order to ensure that execute
and compile, agree, so if you want to add your own optimizer,
you should add it afterwards.
The defer! (aka (to) method implements defer!
for words defined with defer and similar words, but it is also
the core of to. The general stack effect of the
defer!/(to) method is ( val xt -- ), where
xt identifies the word stored into, and val is the value (of
appropriate type) stored there.
(to) ( val xt – ) gforth-1.0 “paren-to”
xt is of a value like word name. Stores val to name.
doc-set-to
E.g., one can implement fvalue as follows:
: fvalue-to ( r xt -- ) >body f! ;
: fvalue ( r -- )
create f,
['] f@ set-does>
['] fvalue-to set-to ;
5e fvalue foo
: bar foo 1e f+ to foo ;
see bar
You can improve the generated code with set-optimizer:
: compile-fvalue-to ( xt-value-to -- )
drop ]] >body f! [[ ;
: fvalue-to ( r xt -- ) >body f! ;
' compile-fvalue-to set-optimizer
: fvalue ( r -- )
create f,
['] f@ set-does>
[: >body ]] literal f@ [[ ;] set-optimizer
['] fvalue-to set-to ;
5e fvalue foo
: bar foo 1e f+ to foo ;
see bar
In practice Gforth has a few additional twists to implement, e.g.,
+TO.
Set-defer@ allows to implement variants of the defer@
(see Deferred Words) method for defer-like words.
doc-set-defer
The >hmextra field is used for cases where additional data
needs to be stored in the header methods table. In particular, it
stores the xt passed to set-does> (and does> calls
set-does>) and the code address behind ;abi-code.
The methods above all consume an xt, not an nt, but the override words
work on the most recent definition. This means that if you use, e.g.,
set-optimizer on a synonym, the effect will probably not be
what you intended: When compile,ing the xt of the word, the
opt-compile, implementation of the original word will be used,
not the freshly-set one of the synonym.
The following methods consume an nt.
The name>interpret method is implemented as noop for most
words, except synonyms and similar words.
doc-set->int
The name>compile method produces the compilation semantics of
the nt. By changing it with set->comp, you can change the
compilation semantics, but it's not as simple as just pushing the xt
of the desired compilation semantics, because of the stack effect of
name>compile. Generally you should avoid changing the
compilation semantics, and if you do, use a higher-level word like
immediate or interpret/compile:, See Combined words.
immediate? ( nt – flag ) gforth-1.0 “immediate?”
true if the word nt has non-default compilation semantics (that's not quite according to the definition of immediacy, but many people mean that when they call a word “immediate”).
Name>string and Name>link are methods in order to make
it possible to eliminate the name, >f+c and link fields
from noname headers, but still produce meaningful results when using
these words. You will typically not change the implementations of
these methods except with noname, but we still have
doc-set-name>string doc-set-name>link