Shadow words

[JimBoyd]

Here is a way to create temporary, or shadow, words in Forth. The temporary words can not be used in normal Forth words. They can be used to help build normal Forth words and data structures and removed when no longer needed because they are defined higher up in memory.
A helper word to exchange memory contents is needed.

Code: Select all

: EXCHANGE  ( ADR1 ADR2 -- )
   2DUP  @ >R @ SWAP! R> SWAP! ;

A variable to hold an alternate DP is needed as well as a new VOCABULARY .

Code: Select all

FORTH DEFINITIONS
VARIABLE SHADOWLANDS
FREE 2/ PAD + SHADOWLANDS !
VOCABULARY TEMPORARY

The word to start temporary definitions is written so it will only execute once before it is reset.

Code: Select all

: (TEMPS)  ( -- )
   ['] EXIT (IS) RECURSE
   DP SHADOWLANDS EXCHANGE ;

The word to stop creating temporary definitions is written so it will only execute if the word to start temporary definitions has been executed.

Code: Select all

: (NORMAL)  ( -- )
   ['] (TEMPS) >BODY @ ['] EXIT =
   0EXIT
   DP SHADOWLANDS EXCHANGE
   ['] LIT (IS) (TEMPS) ;

And finally the two wrapper words to make sure the temporary definitions are defined in the TEMPORARY vocabulary.

Code: Select all

: TEMPS  ( -- )
   (TEMPS) TEMPORARY DEFINITIONS ;
: NORMAL  ( -- )
   (NORMAL) FORTH DEFINITIONS ;

In case anyone was wondering, the functionality of (TEMPS) and (NORMAL) were factored out for use in something else I'm working on.

Here is a trivial example of using a temporary definition:

Code: Select all

// TEST RUN
TEMPS
: RAMP
   256 0
   DO
      255 I - C,
   LOOP ;
NORMAL
CREATE DESCEND
   TEMPORARY // INCLUDE TEMPORARY
             // IN SEARCH ORDER
   RAMP
: NOTHING ;
FORGET NOTHING

A nothing word is created at the end. When NOTHING is forgotten, all the words in the TEMPORARY vocabulary will be forgotten, without forgetting DESCEND , because they are all above HERE .

[JimBoyd]

There is a way to avoid placing the temporary words ( or shadow words) in a different vocabulary. The word PRUNE will unlink any words which are higher than HERE .

Code: Select all

: PRUNE  ( -- )
   CURRENT @
   BEGIN
      DUP HERE TRIM
      @ DUP [ HERE ] LITERAL U<
   UNTIL
   DROP ;

TRIM is a word in my Forth which trims the VOC-LINK and each vocabulary. It follows the chain of links at the supplied address until it finds one which is less than the supplied limit.

Code: Select all

: TRIM  ( ADR LIMIT -- )
   OVER
   BEGIN
      @ 2DUP SWAP U<
   UNTIL
   NIP SWAP! ;

PRUNE follows the link field chain in the CURRENT vocabulary until an address less than somewhere in itself is reached. The assumption is that no shadow words will be defined before PRUNE is defined. TRIM is used on each of these links to make sure each link points to an address less than HERE .
Shadow words can be defined in the same vocabulary as normal Forth words. Since a shadow word is defined entirely in higher memory, pruning them is just a matter of changing the necessary link fields.

Another change will make the shadow word lexicon more efficient and smaller.
EXCHANGE is overly general. It can be replaced with SWITCH .

Code: Select all

: SWITCH  ( -- )
   DP @ SHADOWLANDS @
   DP ! SHADOWLANDS ! ;

TEMPS and NORMAL are no longer needed so (TEMPS) and (NORMAL) can assume those names.

Code: Select all

: TEMPS  ( -- )
   ['] EXIT (IS) RECURSE
   SWITCH ;
: NORMAL  ( -- )
   [ ' TEMPS >BODY ] LITERAL
   @ ['] EXIT = 0EXIT
   SWITCH
   ['] LIT (IS) TEMPS ;

The trivial example becomes slightly simpler because the change in vocabulary is no longer needed.

Code: Select all

// TEST RUN
TEMPS
: RAMP
   256 0
   DO
      255 I - C,
   LOOP ;
NORMAL
CREATE DESCEND
   RAMP
PURGE

and a nothing word to FORGET is no longer needed to remove the shadow words.