Lesson 10 – Create your own words in 8th

A first step towards real programming in 8th

In every programming language there is something like a subroutine, procedure and/or function. I will call this lot “function” hereafter.

Such functions consist of a piece of code in that language. In many cases you can have local variables in such functions.

On entry such functions can get input arguments / parameters. Also in some cases some output can be returned and / or printed in one or another way.

Functions in 8th are called words

In 8th there is an equivalent to functions, called words.

Since, as we already know, 8th is built around the stack concept, almost all words fetch their input from the stack and push their result(s) back onto the stack.

Since 8th does not have local variables, we should use namespaces to create manageable subsets of words and variables.

Unspoken rules when defining words

When we define a word ourselves a set of “rules” should be followed:

1. define your own words in a separate namespace (previous lesson)
2. create documentation, at least in the form of a SED
3. keep your word short
4. your word should comprise a small, easy to understand, task
5. your word should be as readable as possible

How to define a word

In order to create a new 8th word, we need 2 more words:

• : (the colon) to start a word definition
• ; (the semi colon) to end a word definition

So a word definition in it’s bare form looks like this:
: <name> <code> ;

NOTE that every 8th word must be space delimited, including these 2 words!

A first example

We will create a word add3 that adds 3 to it’s input argument and prints the result.

The SED would be:
add3 \ n –

and the definition:
: add3 3 + . cr ;

The reason that add3 does not leave any output on the stack is because the . word consumes the result of the + word. If you are in doubt you should look up the SEDs of these words!

Have a look at the REPL output:

Check that stack is empty.




Define add3.


Execute add3 with input 5.

Output is 8.



Stack is empty again.

Check the unspoken rules

As far as I can tell this word adheres to rules # 2, 3, 4 and 5 but not to rule # 1.

We can check that it is defined in the default namespace user.

When we execute words/ G: we will discover that add3 has been defined in namespace G.

Second example – using our own namespace

In this example we will use our own namespace myspace.

Check that stack is empty.



Switch to namespace myspace.
Define add3 word.

Test add3 with input 7.
Result is 10.


Check that stack is empty.

List all words in myspace.



Only one word namely add3 found in namespace myspace.

Some remarks about namespaces

You can also switch to already existing namespaces (not only new ones) like G:
ns: G

When you are in some namespace you may need to qualify your word name with the namespace it has been defined in, like: myspace:add3

Conclusion

It is very easy to define one’s own words.

But try to remember the unspoken rules. Not only they guide you to good coding habits, but they also protect you from very nasty errors, which are almost impossible to debug.

In my examples I showed the stack before and after execution. That was for a good reason.

You should not be ashamed to have a pencil and paper next to you when writing and testing a program. You should write down the expected contents of the stack before and after executing each and every (intermediate) word.

More info about 8th

There is a central website for 8th here: http://8th-dev.com/
Corresponding YouTube videos here: https://goo.gl/6Ti2pI