herkforth Run Time Tutorial
In this tutorial you will learn to define new words in the source code which can (after being compiled) be executed by name, or be part of the definition of other words.
First you will need to build herkforth.
Then run herkforth.
You will now see the herkforth editor.
We'll want our own "block" to program in, so if you see a bunch of source code
(red, green, and/or yellow words) type new-block and press enter.
Now we should have an empty (except for a yellow zero) block to program in.
In this tutorial we will create a word that will demonstrate the interesting mathematical property that any number squared, will be 1 higher than if you multiply one less than the number by one more than the number. eg 5 squared (25) is one more than 4 times 6 (24) and 100 squared (10000) is one more than 99 times 101 (9999).
First we create a word squared. To do that type squared:. : puts
the word you typed into the source in red. All definitions start with a red
word. This identifies the name of the definition.
Now we follow this by the contents of the definition. Type dup * ; (be
sure to type a space after ; not enter.) Notice that when you press space
the words are inserted into the source in green. herkforth automatically
switches to green after red words.
Note: * means multiply, and ; means return to caller (end).
Save your progress by pressing SHIFT-S.
Now let's get rid of that yellow zero. press SHIFT-H until the cursor reaches it, press backslash to delete it, and SHIFT-N to move back to the end. Your code should look like this:
: squared dup * ;
Save your progress by pressing SHIFT-S.
Time for testing.
Press SHIFT-B. (This tells herkforth to compile/run the current block.)
Put a number on the stack (type 5 and press enter).
Square it: type squared and press enter. Check the stack, and make sure it
produced the correct square. then type drop and press enter to clean up the
stack.
Now lets make a word called +-* which multiplies one less than the number
by one more than the number.
Type +-*: to put +-* in the source in red (red words automatically
start their own line.)
Then type 1- dup 2+ * ; (be sure to do spaces after each word including
the last) Now our we should have this in the source after the squared
definition:
: +-* 1- dup 2+ * ;
Note: 1- is shorthand for 1 - (subtract 1 from the number on top of the
stack). Likewise 2+ adds 2 to the number on top of the stack.
Save your progress by pressing SHIFT-S.
Note: when you save, herkforth forgets definitions that you have previously compiled with SHIFT-B. (they stay in the source, but you'll have to compile them again with SHIFT-B before you can run them again.
If the definition of +-* is confusing, I recommend executing each word from it's
definition and watching the stack as it goes. eg you could do the following
(except use enter instead of space) 5 1- dup 2+ * or even 5 1 - dup 2 + *
Time for testing again.
Compile our definitions by pressing SHIFT-B
Put a number on the stack (type 5 and press enter.) Then execute +-* (type
+-* and press enter.) One less (4) times one more (6) is 24. Check the
stack to be sure we got the correct answer up there. Then drop it (type
drop and press enter.)
Note: when testing, it's important to check how many numbers are left on the stack in addition to checking that the number is correct. It is quite common to accidentally write words that take one more number off the stack than they are supposed to or leave more than they are supposed to. This generally causes serious problems down the road, so it's good to find these bugs right away.
Now we have a word that calculates a square, and one to calculate one less times one more. We could test a numbers by putting them on the stack and executing these words, but it would still be a bit tedious. Let's make a word that calls both of these words, and prints out the results.
Type +-test dup squared . +-* . ; to add our final definition
Note: . (dot) removes the top number from the stack and prints it near the
bottom of the screen.
Save your progress by pressing SHIFT-S.
Compile our definitions by pressing SHIFT-B
Add a number to the stack (type 5 and press enter.)
Run our new word (type +-test and press enter.)
Near the bottom of the screen you should see the two results printed out.
Try out different numbers, like 0, -30 or 443.