Win32Forth

Chains and how to use them

Chains are used to perform a number of words sequentially. Unlike a normal colon definition you can add tasks, either to the end, or the beginning, thus making them suitable for things like initialization or de-initialization, where you want to add extra words to the chain, depending on which files a particular application needs.

Two words are provided to extend chains,CHAIN-ADD and CHAIN-ADD-BEFORE. The former is for forward chains, like initialization chains, where the word is added to the end of the chain, while the latter is for backward chains such as de-initialization chains, where the word is added to the beginning of the chain, so that things are undone in reverse order.

Glossary

.CHAIN chain-addr --                          FORTH         SYSTEM

Print out the words that have been added to chain, in the order that they will be executed by DO-CHAIN. The output is printed using tabbing and capitalization to make the lines stand out.

.CHAINS                                       FORTH         SYSTEM

Print out all the chains in the application area and their contents. Each chain name is printed in capitals on a new line and then the contents are printed as per .CHAIN

?SYS-CHAIN chain_addr xt -- chain_addr xt     FORTH         APPLICATION

Issue a warning if xt is in system space and is being added to a chain that is in application space, and we are not transienting. Warnings are suppressed if sys-warning? is off.

CHAIN-ADD chain_addr -<word-to-add>-          FORTH         APPLICATION

Add xt of <word-to-add> to the end of chain whose address is chain_addr so that it is executed after previously added words in the chain.

CHAIN-ADD-BEFORE chain_addr -<word-to-add>-   FORTH         APPLICATION

Add xt of <word-to-add> to the start of chain whose address is chain_addr so that it is executed before previously added words in the chain. This is mainly used for de-initializing, so that initialization that is done last is de-initialized first.

CHAIN-LINK                                    FORTH         APPLICATION

Variable pointing to the link of the first chain in the list of chains in the application area (or containing Null if no chains exist). Used by .CHAINS and for forgetting.

DO-CHAIN  i*x chain_addr -- j*x               FORTH         APPLICATION

Execute sequentially all the words of the chain whose address is on the stack, passing i*x to the first word and any output down the chain, returning j*x from the last word.

NEW-CHAIN -<name>-                            FORTH         APPLICATION

Create a new chain <name> in the application area.If currently compiling in the system area throw an abort. The chain is linked into the list of chains printed out by .CHAINS and any words added to the chain are trimmed when they are in a forgotten part of the dictionary.

NOOP-CHAIN-ADD   chain_addr -- addr           FORTH         APPLICATION

Add xt of NOOP to the end of chain whose address is chain_addr and return the address of the cell containing it.

TRANSIENT-PTR -- f                            FORTH         APPLICATION

Value containing true if transienting

SYS-NEW-CHAIN -<name>-                        FORTH         APPLICATION

Create a new chain <name> in the system area.If currently compiling in the application area throw an abort. The chain is not linked into the list of chains printed out by .CHAINS and any words added to the chain are not trimmed when they are in a forgotten part of the dictionary.

Obsolete words

XDO-CHAIN (in the FORTH vocabulary ) and EXIT-DO-CHAIN ( in the HIDDEN vocabulary ) were in ealier versions of WIN32FORTH and have since been depreciated. Use DO-CHAIN instead.

Predefined chains in Win32Forth

Win32Forth is using the following predefined chains:

System chains (defined in Primutil.f):

Name	Description	Called by
initialization-chain	chain of things to initialize	HELLO DEFAULT-HELLO
unload-chain	chain of things to de-initialize	UNLOAD-FORTH
forget-chain	chain of types of things to forget	FORGET
post-forget-chain	chain of types of things to forget	FORGET
mouse-chain	chain of things to do on mouse down	MOUSE-CLICK
semicolon-chain	chain of things to do at end of definition	; ;M EXIT-ASSEMBLER DO-;CHAIN
forth-io-chain	chain of things to to to restore forth-io	FORTH-IO
number?-chain	chain of number conversion options	NUMBER
ledit-chain	line editor function key chain	LINEEDITOR
msg-chain	chain of forth key messages	HandleMessages
forth-msg-chain	chain of forth window message	HandleWindowsMessages
reset-stack-chain	chain for resetting the stack	RESET-STACKS

Chains used by the debugger (defined in Debug.f):

Name	Description	Called by
dbg-next-cell		DBG-NEXT
dbg-nest-chain		_DBG-NEST
.word-type-chain		.WORDTYPE

Chains used by See (defined in See.f):

Name	Description	Called by
.execution-class-chain		.EXECUTION-CLASS
.other-class-chain		.OTHER
.word-chain		.WORD

Document $Id: p-chains.htm,v 1.1 2004/12/21 00:18:55 alex_mcdonald Exp $