Edit "herkforth_run_time

edit "herkforth_run_time_tutorial" below.

Tips:

The first line is the page title.
Separate your paragraphs by at least one blank line.
To have a < in your text, enter <<.
To make a link put <l and <> around the wiki page name or web address. Like this: <lmy page<> NOTE: that's a lowercase ELL
To learn about other things you can do please see wiki syntax

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 <lbuild herkforth<>.

Then <lrun 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 <cnew-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 <csquared<>. To do that type <csquared:<>. <c:<> 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 <cdup * ; <> (be
sure to type a space after <c;<> not enter.) Notice that when you press space
the words are inserted into the source in green. <lherkforth<> automatically
switches to green after red words.

Note: <c*<> means multiply, and <c;<> 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 <lherkforth<> to compile/run the current block.)

Put a number on the stack (type <c5<> and press enter).

Square it: type <csquared<> and press enter. Check the stack, and make sure it
produced the correct square. then type <cdrop<> and press enter to clean up the
stack.

Now lets make a word called <c+-*<> which multiplies one less than the number
by one more than the number.

Type <c+-*:<> to put <c+-*<> in the source in red (red words automatically
start their own line.)

Then type <c1- dup 2+ * ; <> (be sure to do spaces after each word including
the last) Now our we should have this in the source after the <csquared<>
definition:

<: +-* <><] 1- dup 2+ * ; <>

Note: <c1-<> is shorthand for <c1 -<> (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, <lherkforth<> 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) <c5 1- dup 2+ *<> or even <c5 1 - dup 2 + *<>

Time for testing again.

Compile our definitions by pressing SHIFT-B

Put a number on the stack (type <c5<> and press enter.) Then execute <c+-*<> (type
<c+-*<> 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
<cdrop<> 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 <c+-test dup squared . +-* . ; <> to add our final definition

Note: <c.<> (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 <c5<> and press enter.)

Run our new word (type <c+-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.

<lherkforth<>

<lforth<>

Anti-Robot: Please enter your favorite four digit number here: