8th Tutorial

Lession 7: Words

Note: if you haven’t yet installed 8th, please do so right now and follow the installation instructions as presented in the manual!

Words

You’re aware that 8th provides a wide variety of “words” and that you can invoke them easily. You’re also aware that 8th documents all the words you can invoke, with “stack-effect diagrams”. Now you’ll learn how to create your own words.

To create a new word named “joe” which adds 10 to the number on TOS, you would do something like this:

\ joe adds 10 to TOS : joe \ n -- n’ 10 n:+ ;
Note that the initial comment is not required, nor is the stack-effect diagram, nor is the indentation. You could have simply entered:
: joe 10 n:+ ;
However, it is highly recommended that you document your words with a line or two of commentary before them, and a stack-effect diagram on the same line as the name. Inside your word definition, you should make additional comments as necessary to make the intended functioning of the word more clear.

Note that we used a qualified name for the “+” to ensure that 8th picked the correct plus word.

The word you just created can be invoked just like any of 8th’s built-in words — there is absolutely nothing special about 8th’s built-ins:

20 joe . cr
30
Please note: you can only invoke a word which exists, and which can be found. That means that you cannot invoke a word before it has been defined, and you cannot invoke it as an unqualified word if it is not in the “with list” or current namespace. See the manual for more details on what is mean by the “with list” as well as how words are found by 8th.

Anonymous and deferred words

One way to get around the restriction that a word must exist before being invoked is to create a deferred word. That is a word with the name you want, but whose action will be “filled in” at a later time:

defer: joe : jerry joe ;
At this point, you can invoke “joe” though it will do nothing. You can put it inside your other words as you see in “jerry” above. If you had not created “joe” prior to creating “jerry”, 8th would complain that it did not know what “joe” was.

Later on you can define an “anonymous word” and assign it as the action which “joe” should perform:

( 10 n:+ ) w:is joe
Note: an “anonymous word” is defined using an opening and a closing parenthesis (both followed by whitespace). Such a word does not have any name (hence “anonymous”) but nevertheless is quite useful.

You could also have assigned the deferred word “joe” the action of some other named word:

: joe2 10 n:+ ; ' joe2 w:is joe
In this case you use the word ' (also known as “tick”) to “get” the value of the word “joe2”. That value is then assigned using w:is to the deferred word “joe”.

Exercises

Try the following:

  • Create a new word called “hi” which prints “Hello, world!”.
  • Create a new deferred word called “hi2” and assign “hi” to it
  • Invoke the new word “hi2” and see if it does what you expect
  • Extra credit: type ' hi2 w:undo and then invoke “hi2”. What happens and why?

Conclusion

Now you can create your own words. We’re now going to return to the topic of data types…