OpenBoot provides the ability to change the definition of a previously compiled Forth word using high-level Forth language. While the changes will typically be made in the appropriate source code, the patch facility provides a means of quickly correcting errors uncovered during debugging.
patch reads the input stream for the following information:
The name of the new code to be inserted.
The name of the old code to be replaced.
The name of the word containing the old code.
ok : patch-me test 0 do i . cr loop ; ok patch 555 test patch-me ok see patch-me : patch-me h# 555 0 do i . cr loop ;
When using patch, some care must be taken to select the right word to replace. This is especially true if the word you are replacing is used several times within the target word and the occurrence of the word that you want to replace is not the first occurrence within the target word. In such a case, some subterfuge is required.
ok : patch-me2 dup dup dup ( This third dup should be drop) ; ok : xx dup ; ok patch xx dup patch-me2 ok patch xx dup patch-me2 ok patch drop dup patch-me2 ok see patch-me2 : patch-me2 xx xx drop ;
Another use for patch is the case where the word to be patched contains some functionality that needs to be completely discarded. In this case, the word exit should be patched over the first word whose functionality is to be eliminated. For example, consider a word whose definition is:
ok : foo good bad unneeded ;
ok : right this that exit ; ok patch right bad foo
on the expectation that the use of exit in the word right would prevent the execution of unneeded. Unfortunately, exit terminates the execution of the word which contains it, in this case right. The correct way to patch foo is:
ok : right this that ; ok patch right bad foo ok patch exit unneeded foo
(patch) is similar to patch except that (patch) obtains its arguments from the stack. The stack diagram for (patch) is:
( new-n1 num1? old-n2 num2? xt -- )
new-n1 and old-n2 can be either execution tokens or literal numbers.
num1? and num2? are flags indicating whether new-n1 or old-n2, respectively, are numbers.
xt is the execution token of the word to be patched.
ok see patch-me : patch-me h# 555 0 do i . cr loop ; ok ['] test false 555 true ['] patch-me (patch) ok see patch-me : patch-me test 0 do i . cr loop ;