Category : Forth Source Code
Archive   : TING.ZIP
Filename : STEPS.SEQ

\ STEPs.SEQ Skip words in a colon definition at runtime, 08jun88cht

comment:

This is based on Jay Malvin's talk at Maxtor Forth Seminar, June 7, 1988.
He implemented a function which allows a word in a colon definition to
exit, or skip the rest of the words in the colon definition, by a flag
generated at runtime. This method can be generalized to procide a powerful
mechanism to change the execution sequence in a colon definition.

The basic technique is to manipulate the top element on the return stack.
If it is droped, you exit from the colon definition. If you increment it
by two, you will skip the next word. If you decrement it by four, then you
will re-execute the previous word, creating an interesting loop structure.

STEPS ( n -- )

n=0 Continue executing next word, as if nothing happened.
n=1 Skip next word.
n=2 Skip next two words.
... etc.

n=-1 Skip the whole colon definition.
n=-2 Jump back to the previous word.
n=-3 Jump back to the second previous word.
... etc.

No range checking can be provided in SKIP. It is the responsibility
of the word prior to SKIP to put the right number on the stack. A number
causing STEPS to jump out of a colon definition will crash the system for
sure.

New code, 6-8-88, C. H. Ting

comment;

: steps ( n -- )
dup -1 =
if 2r> 3drop \ FPC has ES:IP on return stack
else
2* r> + >r \ Only IP on top is incremented
then
;

comment:

Same function can be achieved with code word. However, code word does
not have to deal with the return stack. Only IP needs to be changed.

code steps ( n -- ) \ code word manipulates ip instead rp
pop ax
cmp ax, # -1 \ exit. otherwise crash
0= if
jmp ' exit
then
shl ax, # 1
add ip, ax \ increment IP to skip words
next
end-code

comment;

\ Test example

: test0 0 ;
: test1 1 ;
: test2 2 ;
: test3 3 ;
: test4 4 ;
: test5 5 ;
: test6 6 ;
: test7 7 ;
: test8 8 ;
: test9 9 ;
: print-all 10 0 do . loop ;

: test ( n -- )
-1 max 10 min ( Range checking. Do not jump back. )
steps test0 test1 test2 test3 test4 test5 test6
test7 test8 test9
print-all ;

\ eof