ColorForth Programming Tutorial

Matrix Multiplication example ported to arrayForth

2010-03-30T19:31:00.000-07:00

I'm going to put up a better description later. Right now I just want to get this up on the web. It works! (Took a while). The source HTML was generated by the built in arrayForth HTML generator.

To run the code put the following at the top of block 1302:

0 node 200 load 1 node 204 load 2 node 206 node 3 node 210 load exit

Note that the multicore matrix example is in blocks 200 to 208 and uses nodes 0, 1 and 2. Block 210 does the same thing with a singlecore (node 3). The multicore example finishes in 1479 cycles and the singlecore example takes 3040 cycles. I verified that the multiplications are correct using the statistical language R. At some point I plan to make a video explaining how this all works, but again right now I just want to get the results up.

`multicore matrix multiplication examplecra` `2` `row by` `8` `col matrix is multiplied bycra` `2` `col by` `8` `row matrixcrresuting in vector r1c1 r1c2 r2c1 r2c2cr crr1out send vector r1 to right nodecrr2out send vector r2 to down nodecrrtdwn set port to right and downcrsynch dummy write to synchronize nodescrc1c2out send vectors c1 and c2 to rightindent` `and down nodescrgetres get results from right and down vectors`		200 list `0` `org` `r1out` `right b!` `7` `for @p !b unextcr1` `,` `2` `,` `3` `,` `4` `,` `5` `,` `6` `,` `7` `,` `8` `,crr2out` `down b!` `7` `for @p !b unextcr9` `,` `10` `,` `11` `,` `12` `,` `13` `,` `14` `,` `15` `,` `16` `,crrtdwn` `B5` `b!crsynch` `0` `!bcrc1c2out` `15` `for @p !b unextcr17` `,` `18` `,` `19` `,` `20` `,` `21` `,` `22` `,` `23` `,` `24` `,cr25` `,` `26` `,` `27` `,` `28` `,` `29` `,` `30` `,` `31` `,` `32` `,crgetresright b! @b @b down b! @b @b r---`
`invect` `a- read in vector and store at a` `ab-ab` `17` `bit multiply.proda-n read in vector and do dot product wi th vector stored at ar*c1,c2p- read r from port p then read c1 and c2 and do dot products with r. return results to port p`		202 list `invect` `a!` `7` `for @b !+ unext ;` `a! dup dup or` `17push . begin + unext drop drop a ;.prod` `a! dup dup or` `7for @b @+ a push * + pop a! next ;r*c1,c2` `b!` `60` `invectcrsynch` `@b dropcr60` `.prod` `60.prod !b !b ;`
		204 list `0` `org` `202` `load` `69` `orgright r*c1,c2 r---`
		206 list `0` `org` `202` `load` `69` `orgdown r*c1,c2 r---`
		208 list `0` `org` `a! dup dup or` `17push . begin + unext drop drop a ;cr69` `org` `3 3* r---`
`singlecore matrix multiplication examplecr` `ab-ab` `17` `bit multiplication*sum` `v2ofs-n vector v1 is stored in a andcrv2ofs is the offset to vector v2. sum thecrproducts of v1 and v2.`		210 list `0` `org` `a push a! dup dup or` `17push . begin + unex t drop drop a pop a! ;sum` `dup dup or` `7for over a + b! @+ @b + ne xt push drop pop ;` `69` `orgcr40` `a!` `10` `sum` `8` `sum` `40` `a!` `18` `sum` `10sum r-- -` `40` `orgcr1` `,` `2` `,` `3` `,` `4` `,` `5` `,` `6` `,` `7` `,` `8` `,cr9` `,` `10` `,` `11` `,` `12` `,` `13` `,` `14` `,` `15` `,` `16` `,cr17` `,` `18` `,` `19` `,` `20` `,` `21` `,` `22` `,` `23` `,` `24` `,cr25` `,` `26` `,` `27` `,` `28` `,` `29` `,` `30` `,` `31` `,` `32` `,cr`

Primary ColorForth Chapter 2

2009-06-14T04:36:00.000-07:00

First some housekeeping:

Since Starting Forth is based on traditional Forth, there are some examples that won't work out of the box on ColorForth. Most of the required words can be easily implemented such as spaces back in chapter 1. Some words already exist but are not available in interactive mode because they have only been defined in the macro wordlist. I will define definitions needed for the Starting Forth examples as we go along. Alternatively here are the new definitions together.

/mod ab-qr /mod ;
mod ab-r mod ;
swap ab-ba swap ;
over ab-aba over ;
rot abc-bca push swap pop swap ;
2swap abcd-cdab push rot rot pop rot rot ;
2dup ab-abab over over ;
2over abcd-abcdab push push 2dup pop pop 2swap ;
2drop ab- drop drop ;

Forth Arithmetic -- Calculator Style

Starting Forth identifies the four fundamental arithmetic instructions in traditional Forth are +, -, *, and /. ColorForth has +, * and /. You might be wondering what happened to -. It is a macro that returns the one's complement (the same as invert in ANS Forth). This corresponds to the way - is used in Charles Moore's MISC processors since MuP21. You can still subtract by adding the negative. For constants just use the negative value. For variables or calculated results you can get the negative using NEGATE.

Starting Forth then gives several examples of postfix math. Note as mentioned in chapter 2, in ColorForth you don't need to use . in interactive mode except as a shortcut for drop. You can also clear the entire stack using c. ColorForth continuously displays the parameter stack in the lower left of the screen. Try the following:

17 5 +
7 8 *
3 4 +
500 -300 +
5 6 *
20 4 /
c

An example of adding multiple numbers:

17 20 + 132 + 3 + 9 + .

Converting infix expressions to postfix (quizzie 2-a)

Here is a little trick I learned as a computer science undergraduate. Fully parenthesize your expression and move all operators to the end of the corresponding parenthesis. Examples:

c(a + b) => (c*(a+b)) => (c(a b)+)* => c a b + *

a*b/100 => ((a * b)/100) => ((a b)*100)/ => a b * 100 /

Try the following on your own:

(3a - b)/4 + c

(a + 1)/4

x(7x + 5)

Forth Arithmetic -- Definition Style

The next examples are for converting from yards or feet to inches. We know 1 yard = 36 inches and 1 foot = 12 inches. Here is the conversion code:

yards-inches 36 * ;
feet-inches 12 * ;

Usage example:

10 yards-inches
2 feet-inches

If we always want results to be in inches, we can define:

yards 36 * ;
feet 12 * ;
inches ;

to get the phrase

10 yards 2 feet + 9 inches +

Now perhaps you want to be able to use singular or plural words for better readability. Starting Forth used the following code:

: yard yards ;
: foot feet ;
: inch ;

That has the undesiable effect of adding an extra word call just for the sake of readability. ColorForth can do the same without the overhead using fall through factoring. The same definition can have multiple entry points. So in ColorForth you can define:

yard
yards 36 * ;
foot
feet 12 * ;
inch
inches ;

Note that yard and yards, foot and feet, inch and inches all point to the same memory location.

Now let's consider the earlier example of adding 5 numbers together.

17 20 + 132 + 3 + 9 +

The same thing could be accomplished by moving the +'s to the end.

17 20 132 3 9 + + + +

Changing this to a definition we get:

5sum + + + + ;

Now say if in the same program sometimes we needed to add 5 numbers together and sometimes we needed to add 3? We could use fall through factoring here.

5sum + +
3sum + + ;

This time 5sum and 3sum point to different locations in memory. If you call 5sum it does the first 2 additions and then "falls through" to the remaining 2 additions in 3sum. If you call 3sum it just does the required 2 additions and returns.

An equation for another definition:

(a + b) * c

In postfix:

a b + c *

Alternatively we could say:

c * (a + b)

In postfix:

c a b + *

from which we can write the definition:

solution + * ;

It's a good time to point out that in Forth it's sometimes better to re-write an equation to make it easier to manipulate on the parameter stack. Here is the same code as a word problem:

If a jet plane flies at an average air speed of 600 mph and if it flies with a tail wind of 25 mph, how far will it travel in five hours?

If we define:

flight-dist + * ;

we could enter 5 600 25 flight-dist and get 3125 on the top of the stack.

Try it with different values, including head winds (negative values).

The Division Operators

The basic division in ColorForth (and traditional Forth as well) is /. This is an interger operator which discards the remainder.

22 5 /

This leaves 4 on the stack. There are two other division operators, mod and /mod. By default they are in the macro wordset and only available during compilation. However they can be compiled to the Forth wordset.

mod ab-r mod ; returns the remainder
/mod ab-qr /mod ; returns quotient and remainder

Testing /mod interactively: 22 4 /mod leaves 2 5 on the stack.

We can define a word quarters that takes a number of quarters and calculates the dollars and leftover quarters.

126 load q 0 quarters ones 0 ones
quarters 4 /mod . q .s . ones .s ;
go show blank text 22 quarters ;

Test mod interactively: 22 4 mod leaves 2 on the stack.

Stack Manipulation

Swap

As the name suggests, this word takes the top too numbers on the stack and swaps them. Again this word is only in the macro wordlist. To use it interactively:

swap swap ;

Testing this interactively: 1 2 swap leaves 2 1 on the stack.

Dup

Dup takes the top number on the stack and duplicates it. 2 dup leaves 2 2 on the stack.

You can use dup to square a number. 4 dup * leaves 16 on the stack.

Over

Over is defined only in the macro wordlist. To use it interactively define:

over over ;

Over takes the second item on the stack and copies it to the top of the stack.

Testing it interactively, 1 2 over leaves 1 2 1 on the stack.

Thus the expression

a * (a + b)

can be written as:

over * +

Rot

Rot is in traditional Forth but is not by default defined in ColorForth. However defining it is simple. It requires a the words push and pop. These words manipulate the second stack called the "return stack". Starting Forth doesn't cover this until another chapter. Basically push takes the top number from the parameter stack and moves it to the return stack. pop does the opposite. Using them rot is defined as:

rot push swap pop swap ;

Rot takes the 3rd item on the stack and rotates it to the top.

Testing it interactively: 1 2 3 rot leaves 2 3 1 on the stack.

Say if you wanted to evaluate the expression ab - bc. First factor out the b's.

b*(a - c)

Now starting with c b a on the stack we can use rot - *.

Drop

Drop, as its name suggests, drops the top item on the stack. Testing interactively: 1 2 drop leaves 1 on the stack.

Note: Look ma! No .s. Starting Forth mentions at this point that .s can be used to display the stack non destructively. But ColorForth shows the stack in interactive mode at the bottom left of the screen. Thus .s is not needed and not defined. Hence I can use .s is ColorForth for printing strings.

Stack Manipulation and Math Definitions (Quizzie 2-c)

1. Write a phrase which flips three items on the stack, leaving the middle number in the middle; that is:

a b c ==> c b a

Answer: swap rot

2. Write a phrase that does what over does, without using over.

Answer: swap dup rot rot

3. Write a definition called -rot, which rotates the top three stack items in the opposite direction from rot; that is:

a b c ==> c a b

Answer: -rot rot rot ;

Write definitions for the following:

4. (n+1) / n

Answer: 2c4 dup 1 + swap / ;

5. x(7x + 5)

Answer: 2c5 dup 7 * 5 + * ;

6. 9a² - ba

a(9a - b)

Answer: 2c6 over 9 * swap - * ;

Playing Doubles

Many early Forths ran on 16 bit computers. As such "double" words, which allowed 32 bit math, were very important. ColorForth was initially written for a 32 bit computer and thus does not implement double words. However double stack manipulation words are not difficult to write.

2swap abcd-cdab push rot rot pop rot rot ;
2dup ab-abab over over ;
2over abcd-abcdab push push 2dup pop pop 2swap ;
2drop ab- drop drop ;

Problems -- Chapter 2

1. What's the difference between DUP DUP and 2DUP?

2. Write a phrase which will reverse the order of the top four items on the stack; that is,

( 1 2 3 4 -- 4 3 2 1 )

Answer: reverse swap 2swap swap ;

3. Write a definition called 3DUP which will duplicate the top three numbers on the stack; for example,

Answer: 3dup abc-abcabc dup 2over rot ;

Write definitions for the following infix equations, given the stack effects shown:
4. a² + ab + c ( c a b -- result )

a(a + b) + c

Answer: prob4 over + * + ;

5. (a-b) / (a+b) ( a b -- result ) [answer]

Answer: prob5 2dup - -rot + / ;

6. Write a set of words to compute prison sentences for hardened criminals such that the judge can enter:

CONVICTED-OF ARSON HOMICIDE TAX-EVASION ok
WILL-SERVE 35 years ok

or any series of crime beginning with the word CONVICTED-OF and ending with WILL-SERVE. Use these sentences

HOMICIDE 20 years
ARSON 10 years
BOOKMAKING 2 years
TAX-EVASION 5 years

Answer:

126 load years 0 years
convicted-of 0 ;
homicide 20 + ;
arson 10 + ;
bookmaking 2 + ;
tax-evasion 5 + ;
will-serve . years .s ;
ok show blank text convicted-of homicide arson tax-evasion will-serve ;

7. You're the inventory programmer at Maria's Egg Ranch. Define a word called EGG.CARTONS which expects on the stack the total number of eggs laid by the chickens today and prints out the number of cartons that can be filled with a dozen each, as well as the number of left-over eggs.

126 load cartons 0 cartons eggs 0 eggs
egg.cartons e-cr 12 /mod . cartons .s . eggs .s ;
ok show blank text 55 egg.cartons ;

Fall through factoring

2009-06-14T01:46:00.000-07:00

The idea is that you can have multiple entry points to the same word. Here's an example. Say if you needed code for shifting right twice (4 *) and shifting right3 times (8 *). You could code that without factoring as:

4* 2* 2* ;
8* 2* 2* 2* ;

You could also code it using traditional factoring as:

4* 2* 2* ;
8* 2* 4* ;

Using fall through factoring that becomes:

8* 2*
4* 2* 2* ;

With fall through factoring 8* doesn't have the overhead of having to call 4*, but you still get the code density benefit of having 4* factored out. Fall through factoring can also be used to increase code readability without added overhead. Consider the example from Starting Forth chapter 2.

: YARDS 36 * ;
: FEET 12 * ;
: INCHES ;

: YARD YARDS ;
: FOOT FEET ;
: INCH INCHES ;

The only reason for yard, foot and inch is readability. Here is the same result using fall through factoring.

yard
yards 36 * ;
foot
feet 12 * ;
inch
inches ;

Note that there is now no overhead for yard, foot, or inch being their own separate words. Each word is a separate label for the same code address. In traditional Forth the words yard, foot and inch all have the overhead of making a call to their plural versions. Some traditional Forths have a word alias that can give a similar result as this last example, but that's not standard.

Typing ColorForth 4.1

2009-06-13T09:22:00.000-07:00

Well I thought I had done my last post on "typing ColorForth" at version 4.0. That version does everything I want. However it doesn't quite do it the way I wanted it to. I took code I found on the web that types comment text to the screen, modified it to use yellow "immediate" mode for accessing variables, and then factored the word ".s" (stype in the original version) using inline macros. At least I thought I was using inline macros. The reason is that I wanted to make it clear what .s does. Again the code from the original stype.

stype 1 + dup @ dup 15 and select stype ;

Anyone who understands ColorForth's tail recursion feature can tell what stype ; does. And select is explained in the shadow block comments. But what does 1 + dup @ dup 15 and do? Not obvious is it? 1 + dup @ dup increments then retrieves from the string address. 15 and gets the tag value. You can factor that out those two phrases as "nextw" and "tag", but that doesn't do anything for code density in this case because the words are only used once yet you still have the penalty (albeit small) of the extra call.

So I thought about trying to inline it using cyan words. My thought was that I could define the words inside the macro wordlist and then use them as cyan words in the normal forth wordlist and everything would be inlined. I'd get the readability improvement from factoring without the overhead.

On retrospect I believe my understanding of cyan words was not right. Cyan should be used inside macro wordlist and not the forth wordlist. I believe the result of using cyan for a word defined as a macro is that a call was inserted instead of inline code.

Now I'm not sure if this is right either. But there is a better way to get the results I want. One of the key features of ColorForth is fall through factoring. The idea is that you can have multiple entry points to the same word. Using fall through factoring I can rewrite .s as this:

select jump rest done done done done done done done done norm cap caps done done done done ;
.s
nextw 1 + dup @ dup
tag f and select .s ;

I can now document nextw and tag in the corresponding shadow block. Again, the entire code.

+first 0 +rest 0
type space fffffff0 and unpack +first @ + emit
rest unpack if +rest @ + emit rest ; then drop drop ;
done drop drop pop drop ;
norm 0 +first ! 0 +rest ! type ;
cap 48 +first ! 0 +rest ! type ;
caps 48 +first ! 48 +rest ! type ;
select jump rest done done done done done done done done norm cap caps done done done done ;
.S

nextw 1 + dup @ dup

tag f and select .s ;

And the shadow block:

type w display one 32-bit word of text
rest w finish typing a word
done aw drop addr and word and return from stype
norm normal text
cap text starts with a capital
caps all caps
select wt handle word according to tag

.s a display contiguous white text

nextw a get next word and increment address
tag n get tag field from word.  used by select.

The usage remains the same. "Hello World" in 2 lines of ColorForth.

126 load hello 0 Hello World, I speak ColorForth
ok show blank text hello .s ;

Note: This will probably be the last version of Typing ColorForth (at least I hope so). It does (almost*) everything I want it to do as is as efficient and readable as I can make it. To the critics (well meaning I'm sure) who don't understand why I was doing this, please look at the rest of the Primary ColorForth tutorial. Doing all of the examples in Starting Forth by looking up codes and "emitting" them would be an unecessary pain in the butt. And yes, I could just type in "Hello World" on a blank screen, but that would not be flexible enough for what I'm doing.

(* There is one other thing I'd like to do. The current version sticks in an extra space before typing anything. Sometimes this throws the formatting off. But I'm going to quibble about that...for now.)

Primary ColorForth Chapter 1

2009-06-03T04:21:00.000-07:00

As mentioned in the intro, Primary ColorForth is loosely based on Starting Forth. You can follow along in it for this tutorial series either with a hardcopy version or online.

Starting Forth chapter 11 starts by describing a way of organizing work by defining useful tasks and giving them a name, then grouping tasks together into larger tasks and naming them.

It gives the example of an embedded washing machine program which we will explore.

Washing Machine Example

Here is the top level washing machine program in ColorForth.

washer wash spin rinse spin ;

In ColorForth red words signify the start of a new definition. So washer is the new procedure. The ";" represents the call return. Green words are ones that have already been defined and are compiled into the new definition. Note that unlike traditional Forth words cannot be defined from the command line. All words must be defined in the editor. Then the block containing the source text must be loaded. For example, to define new words in block 22 you would use 22 edit, then to compile then you would use 22 load.

Let's look at the definition of rinse.

rinse fill agitate drain ;

And now the definition of fill.

fill faucets open till-full faucets close ;

The definition includes "things" (faucets) and verbs (open and close). The word "till-full" represents a delay loop. After the faucets "open" the word waits "till-full" before they "close".

Every word must be defined before it can be compiled into a definition, so fill must be compiled before rinse and rinse must be compiled before washer.

fill faucets open till-full faucets close ;
rinse fill agitate drain ;
washer wash spin rinse spin ;

This system is just an example. For a real system the definitions for open, close, faucets, till-full, agitate, drain and spin would all have to be defined. At some point it would be direct machine code to activate stepper motors, read sensors etc.

Putting On a Show

Forth was originally designed around a TTY display model. But ColorForth uses a GUI display, albeit one that is MUCH simpler than MS Windows, X-Windows or MacIntosh. So getting things displayed on the screen is a bit tricker than traditional Forth, but simpler than raw programming of most GUI operating system. The ColorForth word show creates a display task using the words following it.

Consider this definition.

ok show text 93 emit keyboard ;

This creates a new definition ok that draws a "*" at the top left corner of the screen. The word text moves the cursor to the top left of the screen and sets the drawing color to white. The word emit takes a number off the stack and draws the corresponding charecter. It's the same as emit in traditional Forth. Note that the character set is different from ASCII. You can look up the characters in a code map, or you can use the command icons. The word keyboard redraws the keyboard and stack.

Chapter 1 of Starting Forth builds up an example on how to draw the letter "F" as a large character using "ASCII art". Here is a walkthrough of that example using colorForth.

First we need to define the word spaces which is built into traditional Forth.

spaces for space next ;

Note ColorForth uses for...next for its counted loop structure. Using spaces with what we learned earlier we can code the following:

spaces for space next ;
ok show text 15 spaces 93 emit ;

Notice when we run this, the word spaces doesn't erase the text already on the screen, but just moves the star over. That's another example of how graphical CF is different from TTY TF.

Now let's define star as it's own word.

spaces for space next ;
star 93 emit ;
go show text 15 spaces star ;

Moving sections of code into their own definitions is called factoring. Factoring is used to increase readability and/or code density.

The next words define the "F" using combinations of the above defined words. Note that "cr" stands for "carriage return". That simply moves the cursor to the next line.

side star spaces star ;
margin cr 30 spaces ;
blip margin star ;
bar margin 5 stars ;
f bar blip bar blip blip cr ;
ok show text f keyboard ;

After loading the block containing these words and typing ok from the command line a large "F" will be displayed on the screen.

Hello World from ColorForth

The next Starting Forth example is a variation on the venerable "Hello World" program. This particular program has cause some needless controvery and confusion over the years. Sure you emit each character one at a time, but that's not the most readable solution nor the most flexible. ColorForth can type blocks of text just like traditional Forth. And since ColorForth is extensible, just like traditional Forth is extensible, you extend it to where you can do a program like "Hello World" in just two lines.

First you have to understand how text is stored in the ColorForth editor. ColorForth doesn't store ASCII characters in bytes. Instead it packs several characters in one 32 bit word using Shannon encoding, eabling it to store 5 to 7 characters plus a color token in one word. ColorForth includes a word unpack for decompressing such words. We have already discussed red and green words. ColorForth uses white words for comments. Comments can be as all lowercase, all upper case, or mixed case. So one way to display a block of text is to store it as comments in a Forth block, put that address on the stack, and then unpack and properly display the words until a non comment word is reached. Here is the code to set this up:

+first 0 +rest 0
type space fffffff0 and unpack +first @ + emit
rest unpack if +rest @ + emit rest ; then drop drop ;
done drop drop pop drop ;
norm 0 +first ! 0 +rest ! type ;
cap 48 +first ! 0 +rest ! type ;
caps 48 +first ! 48 +rest ! type ;

select jump rest done done done done done done done done norm cap caps done done done done ;

.s

nextw 1 + dup @
tag dup 15 and select .s ;

That may look like a lot, but realize that you can load this block whenever you need it or you can even have it load automatically when ColorForth boots. Here is an example of its usage (assuming the code was stored in block 126).

126 load s 0 Hello world, I speak ColorForth
ok show text s .s ;

Note that magenta words like s define variables. Variables in ColorForth point to the blocks where they are defined as opposed to the dictionary. So s is being used here to point to the comment block of text we want to type.

Run-time Versus Compile-time Versus Edit Time

Starting Forth then goes into a discussion about "run time versus compile time". This is a good time (no pun intended) to go into the other color states in ColorForth. We've already gone over how red defines a new word and how green compiles a previously defined word into a new definition. Green words are executed at run time. There are also yellow words that are executed at compile time. Consider the "hello world" example given earlier.

126 load s 0 Hello world, I speak ColorForth
ok show text s .s ;

Note the phrase 126 load. This will load the text display code in block 126 as soon as the current block is loaded. You don't have to wait until ok is run. Also note that the acess to the variable s is in yellow too. A variable is really just a name for an address. Why wait until run time to look up the address? Why not look it up at compile time and compile the address directly into the code? Accessing variables as yellow words instead of green ones accomplishes that. In fact that is the preferred way.

Another way to use yellow words are with constants. When a constant is coded in yellow its value is compiled into the code on the yellow to green transition. This is also true for calculations that are done in yellow. Using the earlier "big F" exampe:

side star spaces star ;
margin cr 30 spaces ;
blip margin star ;
bar margin 5 stars ;
f bar blip bar blip blip cr ;
ok show text f keyboard ;

Yellow words can also be used to do calculations that can be determined at compile time such as calculations based on a constant.

Cyan words are used to create inline macros.

The Dictionary

ColorForth, like traditional Forth, stores definitions in a dictionary. One difference is the way ColorForth handles numbers. In traditional Forth the interpreter first looks in the dictionary find a word and if it's not found it checks to see if it is a number. The ColorForth editor handles numbers differently. So the compiler never has to check to see if something is really a number.

The Stack: Forth's Worksite for Arithmetic

If you are already familiar with Forth (or with HP scientific calculators) you know you to use the stack. If not here's a brief overview. Everytime a number is entered it is pushed on the stack. Forth arithmetic words will take numbers off the stack, do some operation with them, and return the results to the stack. To do 3 + 4 you must first push the 3 and the 4 to the stack then execute the "+" word.

3 4 +

Note that the current state of the stack is shown on the bottom left of the screen. If you use the dot command . by itself all you will notice is that one number drops off. In traditional Forth . displays the top number on the stack. If you use . inside of a show word you get the traditional result.

go show 3 4 + . ;

Problems

Problem 1-1: Define a word called gift that, when executed, will type out the name of some .gift, a word .giver that prints out a person's name, and a word .thanks that prints out something like this:

Dear Stephanie, Thanks for the bookends.

Solution:

gift 0 bookends. giver 0 Stephanie, dear 0 Dear thank 0 Thanks for the
.gift gift .s ;
.giver giver .s ;
.thank thank .s ;
.dear dear .s ;
thanks show black screen text .dear .giver .thank .gift ;

Alternatively:

gift 0 bookends. giver 0 Stephanie, dear 0 Dear thank 0 Thanks for the
thanks show black screen text dear .s giver .s thank .s gift .s ;

Problem 1-2: Define a word tenless that takes a number on the stack, substracts 10, and returns the answer on the stack. (Hint: You can use +.) Be sure to include stack effects.

Solution

tenless n-n' -10 + ;

Problem 1-3: After entering the words in Problems 1-1, enter a new definition for .giver to print someone else's name, then without redefining thanks, execute thanks again. Can you explain why thanks still prints out the first giver's name?

Solution

gift 0 bookends. giver 0 Stephanie, dear 0 Dear thank 0 Thanks for the
.gift gift .s ;
.giver giver .s ;
.thank thank .s ;
.dear dear .s ;
thanks .dear .giver .thank .gift ; giver 0 Jill
.giver giver .s ;
go show black screen text thanks .giver ;

Alternatively:

gift 0 bookends. giver 0 Stephanie, dear 0 Dear thank 0 Thanks for the
thanks dear .s giver .s thank .s .gift .s ; giver 0 Jill
go show black screen text thanks giver .s ;

Whenever a new word is compiled it is appended to the end of the dictionary. The old definition isn't overwritten, but the interpreter starts at the newest definition and searches backwards so it doesn't find the older definition. However words that were defined using the old definition still work the same.

Typing ColorForth...versions 3.1 and 4.0

2009-05-26T07:41:00.000-07:00

Hello again. Here's yet another update to my experiments with unpacking and displaying packed ColorForth text. I know have it to the place where doing the examples from Starting Forth should be easy. First a fix from version 3.0 based on the fact that ColorForth 2.0 enforces Chuck's admonition for yellow variable calls.


s 0 hello , i speak forth
type fffffff0 and unpack if emit type ; then drop drop ;
print dup @ f and -9 + drop if drop then ; dup @ type space 1 + print ;
greet show text s 1 + print ;

However I found a much better version. This version actually handles caps and mixed case. But it also requires the yellow variable call fix.


+first 0 +rest 0
type space fffffff0 and unpack +first @ + emit
rest unpack if +rest @ + emit rest ; then drop drop ;

done drop drop pop drop ;
norm 0 +first ! 0 +rest ! type ;
cap 48 +first ! 0 +rest ! type ;
caps 48 +first ! 48 +rest ! type ;

select jump rest done done done done done done done done norm cap caps done done done done ;
stype 1 + dup @ dup 15 and select stype ;

Here's a slightly different version that uses macros to (IMO) improve readability and includes an example of usage.

+first 0 +rest 0
type space fffffff0 and unpack +first @ + emit
rest unpack if +rest @ + emit rest ; then drop drop ;

done drop drop pop drop ;
norm 0 +first ! 0 +rest ! type ;
cap 48 +first ! 0 +rest ! type ;
caps 48 +first ! 48 +rest ! type ;

select jump rest done done done done done done done done norm cap caps done done done done ; macro
tag 15 and ;
nextw 1 + dup @ dup ; forth
stype nextw tag select stype ;

Here's what this does and why I think it's better. The words "nextw" and "tag" are put in the "macro" dictionary and then inlined because they as "cyan" words. Cyan words allow you to inline. Normally in ColorForth words are factored to save space. Here no space is saved because "nextw" and "tag" are only used once. But "stype" is more readable because it says exactly what it does. Here's the documentation "shadow block".


String Display
type w display one 32-bit word of text
rest w finish typing a word
done aw drop addr and word and return from stype
norm normal text
cap text starts with a capital
caps all caps
select wt handle word according to tag
nextw a get next word and increment address
stype a display contiguous white text

Using the above, here's the solution to problem 1-1 from Starting Forth.


162 load salute 0 Dear friend 0 Stephanie, thank 0 thanks for the gift 0 bookends.
thanks salute stype friend stype thank stype gift stype ;
ok show text blank white thanks keyboard ;

Note that "162 load" assumes that the "String Display" library is in block 162.

A ColorForth 2.0 "gotcha".(Windows version anyway)

2009-05-26T05:48:00.000-07:00

Hello all.

I pretty much use a Windows version of ColorForth all the time these days. (Usually ColorForth 2.0 from Chuck Moore in Windows mode, but some Roman Pavlyuk's version.). The reason I'm prefacing my remarks is because I have never used the native version of ColorForth 2.0 and I don't know if this "gotcha" only happens under Windows. There is an easily fixable bug that only happens in Roman's Windows version of ColorForth. It uses absolute addressing from blocks as opposed to indirect addressing. So the code:


0 block @

causes it to crash. The fix is easy. Assume the following code in block 162.


ofs 0
foo block ofs 162 block negate + -1 + + ;
block foo ;

Thankfully ColorForth 2.0 for Windows doesn't have that problem. It uses an offset to calculate blocks out of the box. However there is another "gotcha" when using variables. If you try to address a variable using a green word it doesn't work. You may simply not get the results you want or it might crash. Consider the following example taken from Starting Forth chapter 2.


date 0 month 0 year 0
!date date ! month ! year ! ;

5 26 2009 !date

That doesn't get the expected results. But there's a reason I call this a "gotcha" instead of a bug. Long ago Chuck documented that variables really should be used as yellow words (evaluated at compile time) instead of green words (evaluated at run time). When you think about it, this makes sense. A variable is really just an address and for the most part address are constants. So why wait until run time to find the address of a variable? Just find it at compile time and compile the address constant directly into the word. With that in mind the above code becomes:


date 0 month 0 year 0
!date date ! month ! year ! ;

5 26 2009 !date

So if you have old ColorForth code that uses variables as green words you need to change them to yellow words. Your code will be (slightly) faster and it will work on ColorForth 2.0 for Windows (again, I don't know if the native version even has this "gotcha").

SEAForth Matrix Multiplication Example update 1

2009-01-25T17:25:00.000-08:00

It's been about 1 year since I posted my initial SEAForth matrix multiplication example. A lot has happened since then including changes to the VentureForth IDE/simulator as well as the commercial release of actual SEAForth chips. That's the good news. The bad news (for me at least) was that the changes were such that it broke my old code. That wouldn't have been so bad if there had been "this has been deprecated" section in the docs, but then I suppose that would have made the transition too easy. ;) Seriously though, some of the changes actually make the code much cleaner. Also I've made the code much more modular thanks to the judicious use of include files.

First I'll go through the changes that I've noticed in the new system and then an overview the new matrix multiplication code.

Change 1 : Node specification

In the original VentureForth you specified the node you were compiling to this way:


12 node !

Now the compiling node is specified this way:


12 {node
...
.../ some VentureForth code
...
node}

It's a lot clearer where compiling to a node begins and ends. This can also lead to a clean modular code pattern that will be discussed later.

Change 2 : Stream Specification

Section 2.3.1 of the VentureForth manual explains streams. Basically it's a way for code and data to be initially distributed to the correct nodes. If you are just learning the SEAForth system as I am you probably aren't ready to create your own custom stream nodepath. But you do need to make sure all of the nodes are initialized. The following code will do that.


19stream

reset

Change 3 : Literal Specification

The original VentureForth compiler would compile literals automatically. Now a "#" is required after every literal. Note that port selection constants are really literals and require a "#" after them also. So:


'r--- b!
7 for @p+ !b unext

becomes:


'r--- # b!
7 # for @p+ !b unext

Toward More Modular Programs

I saw the following code pattern in the "blinktest" sample project:


\ Main program.vf
.
.
19 {node 0 org here =p include module.vf node}
.
.

So I've followed a similar pattern for my code, breaking what was a single monolithic module into 6 smaller (and in my opinion easier to read) modules.

Main module : matrixmult.vf


( $Id: matrixmult.vf,v 1.0 2006-11-2 $ )
\ Matrix multiplication example
\ Parrallel multiplication of a 2 row matrix by a 2 column matrix
\ 1) Data initially is in node 12
\ 2) Row1 is passed to node 18
\ 3) Row2 is passed to node 13
\ 4) Column1 is passed to nodes 18 and 13 simultaneously
\ 5) Multiplications R1*C1 and R2*C1 done simultaneously
\ 6) Column2 is passed to nodes 18 and 13 simultaneously
\ 7) Multiplications R1*C2 and R2*C2 done simultaneously
\ 8) Results R1*C1, R1*C2, R2*C1, R2*C2 are returned to node 12

v.VF +include" c7Dr03/romconfig.f"

12 {node include node12.vf node}
13 {node include node13.vf node}
18 {node include node18.vf node}

19stream

reset

cr

Node 12 code : node12.vf
Note: This is the taskmaster node. It passes the data to nodes 13 and 18 to be processed and the collates the results.


\ ******* node 12 ***************************************
\ Pass row1 to node 13, row2 to node 18
\ and columns 1 and 2 to nodes 13 and 18 simultaneously

0 org here =p

\ Stream R1 to node 13
'r--- # b! \ point reg b to right node. (I/O node 13)
7 # for @p+ !b unext
1 , 2 , 3 , 4 , 5 , 6 , 7 , 8 ,

\ Stream R2 to node 18
| '-d-- # b! . . \ point reg b to down node. (I/O node 18)
7 # for @p+ !b . unext
9 , 10 , 11 , 12 , 13 , 14 , 15 , 16 ,

\ Stream C1 to nodes 13 and 18 simultaneously
'rd-- # b! . . \ point reg b to right and down nodes. (I/O nodes 13 and 18)
0 # !b . . \ dummy write for synch purposes
15 # for @p+ !b . unext
17 , 18 , 19 , 20 , 21 , 22 , 23 , 24 ,
25 , 26 , 27 , 28 , 29 , 30 , 31 , 32 ,

59 # a! . . \ point A register to address 59
'r--- # b! . . \ point reg b to right node. (I/O node 13)
@b !a+ . . \ Get result R1*C1
@b !a+ . . \ Get result R1*C2
'-d-- # b! . . \ point reg b to down node. (I/O node 18)
@b !a+ . . \ Get result R2*c1
@b !a+ . . \ Get result R2*c2

Nodes 13 and 18 basically do the same thing. Get a row of data from node 12, then use that row to calculate a dot product of two columns of data.

Node 13 code : node13.vf


\ ******* node 13 *********************************************
\ Receive row1 then multiply it by columns 1 and 2
\ and return results.

0 org

include 8bitmult.vf

here =p
'r--- # b! . . \ point reg b to right node

include vectormult.vf

Node 18 code : node18.vf


\ ******* node 18 *********************************************
\ Receive row2 then multiply it by columns 1 and 2
\ and return results.

0 org

include 8bitmult.vf

here =p
'-d-- # b! . . \ point reg b to down node

include vectormult.vf

8 bit multiply : 8bitmult.vf


: 8*8 ( n1 n2 -- n1*n2 ) \ 16 bit output
push 2* 2* . \ left shift n1 8 times
2* 2* 2* .
2* 2* 2* .
pop +* +* +*
+* +* +* +*
+* push drop .
pop ;

Vector multiply : vectormult.vf


\ ******* vector multiply *******************************
\ Receive a row then multiply it by columns 1 and 2
\ and return results.

$20 # dup a! push \ point reg a to buffer - leave adr on return stack

7 # for @b !a+ unext

@b drop \ dummy read for synchronization purposes

pop dup a! push \ reset a to start of buffer
dup xor \ initilize TOS to 0
7 # for
@b @a+ 8*8
+ next

dup dup xor \ preserve result from vector mult - initialize TOS to 0

pop a!
7 # for
@b @a+ 8*8
+ next

!b !b \ Send results back to right node

SEAForth matrix multiplication example

2008-01-28T08:01:00.000-08:00

Disclaimer: I don't work for IntellaSys and I consider myself a novice in NOSC programming in general and the SEAForth architecture in particular. But, by using documentation publicly at the IntellaSys website I have figured out how to write working programs for it.

I'm going to diverge from ColorForth for this particular blog entry to talk about SEAForth. Hopefully the ColorForth version of the SEAForth compiler will be released soon, but for now the public SEAForth programming environment, VentureForth, is closer IMO to MachineForth. (No color tokens. You have to keep up with code slots etc.) Still VentureForth does have a strong "fun factor" when it comes to programming. Personally I think that when programming, rather than thinking about ALGOL like "algorithms" you should think about the hardware and how to directly map your problem across it. Programming comes later.

SEAForth Architecture

The SEAForth architecture is the latest hardware design from Forth creator Chuck Moore. Like previous designs it is a NOSC or "no operand stack computer". The history and documentation of Mr. Moore's early NOSC work is documented at Jeff Fox's Ultratechnology website. This means that all operations take their operands from the stack. SEAForth goes a step further and has multiple cores (24 in the first implementation) on one chip.

Here is a diagram of a SEAForth chip.

  

U 

















U



 

18 R 19 L 20 R 21 L 22 R 23
 

D 

D 

D 

D 

D 

D 

 

12 R 13 L 14 R 15 L 16 R 17
 

U 

U 

U 

U 

U 

U 

 

06 R 07 L 08 R 09 L 10 R 23
 

D 

D 

D 

D 

D 

D 

 L 00 R 01 L 02 R 03 L 04 R 05
 

U

The numbers 0..23 represent the individual cores. The letters U, D, L and R represent the ports. Mr. Fox explained that these ports can point to other cores on chip or to off chip devices. For example communication between ports 18 and 19 always use the "R" port regardless of whether its 18 sending the data or receiving it. Also the U port for cores 18 and 23 goes to the A/D and D/A pins in some configurations. Knowing how port communication works is essential for understanding the "crawler" application walkthrough that IntellaSys has provided with their development kit.

Sample Application

In trying to come up with a test program to explore SEAForth, I settled on an obvious parallel processing application that's easy to understand, matrix multiplication. First lets look at the mathematical definition of matrix multiplication. The product of two matrices A and B results in a new matrix C where each element of C is the sum of the products of the rows in A and the columns in B. Let's take the case of a 2 row matrix by a 2 column matrix.

Matrix A:

1	2	3	4	5	6	7	9
9	10	11	12	13	14	15	16

Matrix B:

17	25
18	26
19	27
20	28
21	29
22	30
23	31
24	32

If we label the matrix A rows R1 and R2 and the matrix B columns C1 and C2 then the resulting matrix is:

R1*C1	R1*C2
R2*C1	R2*C2

Mapping of problem to SEAForth chip

So this is how I mapped the problem to the SEAForth chip.

Data is initially in node 12
Row 1 is passed to node 18
Row 2 is passed to node 13
Column 1 is passed to nodes 18 and 13 simultaneously
Multiplications R1*C1 and R2*C1 are done simultaneously
Column 2 is passed to nodes 18 and 13 simultaneously
Multiplications R1*C2 and R2*C2 are done simultaneously
Results R1*C1, R1*C2 from node 18 are returned to node 12
Results R2*C1, R2*C2 from node 13 are returned to node 12

Data streaming

As you may have noticed, in this program node 12 is responsible for streaming data to other nodes and then collecting the results. For this test program the data is stored in node 12's core memory. For larger applications this could be streamed in from external memory. Consider the following code snippet.


\ Stream R1 to node 13
'r--- b! . .   \ point reg b to right node.  (I/O node 13)
7 for @p+ !b . unext
[ 1 ,  2 , 3 , 4 , 5 ,  6 ,  7 ,  8 , ]

This is a microloop. The first line configures the b register to communicate with the "right" node to node 12. The next line is a microloop. The entire loop fits in one SEAForth word of memory. The data (values 1...8) are stored in the words immediately following the loop. The instruction @p+ copies a word from the program counter to the stack and the increments the program counter. The instruction !b takes the word on the top of the stack and sends it to the node(s) pointed to by the b register. You can write to more than one node at once as shown by this code.


\ Stream C1 to nodes 13 and 18 simultaneously
'rd-- b! . .    \ point reg b to right and down nodes.  (I/O nodes 13 and 18)
0 !b . .        \ dummy write for synch purposes
15 for @p+ !b . unext
[ 17 , 18 , 19 , 20 , 21 , 22 , 23 , 24 ,
25 , 26 , 27 , 28 , 29 , 30 , 31 , 32 , ]

The a register is used to write to internal core memory. The last part of the code for node 12 reads 4 results (2 from node 13 and 2 from node 18) and stores them sequentially starting at hex address 32.


$32 a! . .    \ point A register to address 32
'r--- b! . . \ point reg b to right node.  (I/O node 13)
@b !a+ . .   \ Get result R1*C1
@b !a+ . .   \ Get result R1*C2
'-d-- b! . . \ point reg b to down node.  (I/O node 18)
@b !a+ . .   \ Get result R2*c1
@b !a+ . .   \ Get result R2*c2

Multiplication on SEAForth

The SEAForth chip does not have a direct multiplication instruction. Instead it has a multiply step. All you really need to know is that if you want to multiply two n-bit numbers n1 and n2, put both on the stack, shift 1 number left n times, then execute the multiply step n times. For 8 bit multiplication you can use the following code.


: 8*8 ( n1 n2 -- n1*n2 )  \ 16 bit output
push 2* 2* .  \ left shift n1 8 times
2* 2* 2* .
2* 2* 2* .
pop +* +* +*
+* +* +* +*
+* push drop .
pop ;

This creates a subroutine 8*8 which is used to do 8 bit multiplies. That's all I need for this particular example. Here is the rest of the code for node 13. Node 18 uses the same code.


-d--  b! . .       \ point reg b to down node (I/O node 12)
$20 dup a! push   \ point reg a to buffer - leave adr on return stack

7 for  @b !a+ . unext \ read row R1 from node 12 and store in buffer

@b drop . .       \ dummy read for synchronization purposes

pop dup a! push    \ reset a to start of buffer
dup xor          \ initialize TOS to 0
7 for             \ Loop to multiply elements from R1 and C1
@b @a+ 8*8 .      \ Get next R1 element from buffer and next C1 element from node 12
+ next . .

dup dup xor .     \ preserve result from vector multiply - initialize TOS to 0

pop a! . .

\ reset a to start of buffer
7 for \ Loop to multiply elements from R1 and C2
@b @a+ 8*8 . \ Get next R1 element from buffer and next C2 element from node 12

  + next . .

!b !b . .                \ Send results back to node 12

Performance

First I need to point out that the goal isn't to show how fast I can do multiplication but rather how efficient the SEAForth architecture can be for exploiting parallelism. On the simulator I have it was able to complete a single 8 bit multiplication in 50 cycles. Considering that there are a total of 32 multiplications that 1,600 cycles for multiplication alone. Using 3 cores the operation is completed in 945 cycles which represents a 41% speed up. It should be intuitively obvious that even great speed ups can be achieved by mapping the problem over more cores. I have a couple of ideas on that to test but I'll save that for another day.

Typing ColorForth...version 3.0

2006-12-27T20:32:00.000-08:00

Cliche of the day: The third time's a charm

I've now extended my ColorForth text display library to the place where it's as "non-tedious" to use as possible. The first step was to be able to unpack and "type" a word rather than having to look up ColorForth charecter codes and emit them one at a time. The second step was to be able to print multiple words at one shot. That was in version 2.0. But the problem there was that I either had to put the number of words on the stack, or store them in the string variable itself. Now, after some brainstorming on the c4th IRC channel, I've come up with working code that figures out for itself how many words to type. Here it is.

s 0 hello , i speak forth
type fffffff0 and unpack if emit type ; then drop drop ;
nextw dup @ type space 1 + ;
tag f and ;
?ncom tag -9 + drop ;
print 1 +
ploop dup @ ?ncom if drop ; then nextw ploop ;
greet show text s print ;

A few notes here. Due to the way "print" works I couldn't use the old "nxtw" definition. So I modified it and changed the name. Also note, for those obsessing over lines of code (despite the fact that just about everyone knows that's no longer a good measure of program size, complexity or "tediousness") the above can be "compressed" into less lines, though IMO at the cost of readability.

s 0 hello , i speak forth
type fffffff0 and unpack if emit type ; then drop drop ;
print dup @ f and -9 + drop if drop then ; dup @ type space 1 + print ;
greet show text s 1 + print ;

There you have it. Four lines of ColorForth. (Or 3 lines depending upon where you put your variable.)

type fffffff0 and unpack if emit type ; then drop drop ; s 0 hello , i speak forth
print dup @ f and -9 + drop if drop then ; dup @ type space 1 + print ;
greet show text s 1 + print ;

And for the "ultra minimalist" (who doesn't want to bother with the tedium of looking up ColorForth charecter codes) you can do a simple "hello world" in 2 lines.

type fffffff0 and unpack if emit type ; then drop drop ; s 0 hello world
ok show text s dup push 1 + @ type 0 emit pop 2 + @ type ;

But that code isn't very robust. What happens when the string you want to type grows from 2 words to 6 as in "hello world, what a lovely day"? Still, that beats the pants off of emitting each charecter one at a time.

Anyway, this is the last I'm do anything with "hello world" programs for a while. I've got enough now to finish all of the examples in Starting Forth (chapter 1 anyway) with a minimum of tedium. This does remind me of how Chuck Moore answered the question of "hello world" programs on the ColorForth mailing list.

I've noticed the interest people have in getting colorForth to say "Hello
World".

The facility for doing that is extremely simple. Find an empty block. Edit
"Hello World" at the top.

I know that's not quite what they have in mind. But it's the way I'd
generate any sort of display. Format a block with the editor. Fill in
whatever numbers or graphics are required.

Gotta love it! "Hello world" in a single line and no need for tedious charecter code look ups and emits! Honestly though, that's what got me (and others) thinking about the "unpack" method of displaying text. The ColorForth to my understanding works by unpacking and displaying all of the 32 bit words in a block of code. But it's smart enough to understand compile words, macros, comments, numbers ect and choose the correct color and font. Right now the method I'm using only recognizes comments from non comments so it can't properly handle capitalization. But it should be intuitively obvious to the casual observer how to fix that. Perhaps I'll leave that as a "student exercise". :)

Typing ColorForth...ver 2.0

2006-12-27T11:45:00.000-08:00

Hello folks. Back fresh from the forever flamewars at comp.lang.forth. :) It's funny how some people want to nitpick ColorForth while posting code that the ANS standard calls "dangerous".

Anyway the current "nitpick" is over my stype code. Small confession. I'm not omniscient. ;) When I posted at c.l.f. I was replying to the usual nonsense while thinking about where I was going with PrimaryForth tutorial as opposed to just answering what's possible now. Once I get finished you will be able to do the following code:

s 0 hello , i speak forth
ok show text s stype ;

And get:

hello, i speak forth

as output. Right now you get:

hello

as output. If you want to get the entire phrase you have to put the number of words you want to type on the stack use the "words" word. For example:

ok show text s 5 words ;

I really don't see that as a big deal. You still don't have to do:

hw show blue screen text 230 350 at red 2a 10 c 1 3 3f 0 2e 3 c c 4 44 13 for 2emit next ; hw

But don't tell the "haters*" that. :) They still want to believe what they want to believe. Still, I've found a way around this. By storing the number of words in the ColorForth string variable (the same as the way ANS Forth stores the number of charecters in the first byte of an ANS Forth string variable) the computer can put the number of words on the stack for you. For example:

s 5 hello , i speak forth
phrase dup @
words for ntxtw next ;

Now with just one small line of ColorForth:

ok show text s phrase ;

You get:

hello , i speak forth

The next step will be to incorporate testing the token color. Comments use the "white" color. So phrase could be programmed to typing words until it hits a word that's not a comment. (Thanks to "tathi" on the c4th IRC channel for kicking this idea around.)

* Note: By "haters" I don't mean the person who actually wrote the ColorForth code I referenced. I mean those who want to insist on using that as "proof" that it's difficult to do something as simple as "hello world" in ColorForth rather than seeing the obvious. ColorForth, like any other Forth, is extensible.

Typing ColorForth

2006-12-27T08:03:00.000-08:00

I made the following extensions to ColorForth.

s 0 hello , i speak forth
stype 1 + @
type fffffff0 and unpack if emit type ; then drop drop ;

The word "type" takes a packed word and displays it on the screen. Right now it ignores all color tags and just emits charecters using the current foreground color. Note that s is a string variable. Actually it's just a regular variable, but I'm treating it like a string variable. Variables in ColorForth really point directly to block memory. So by adding 1 to the address of s I can get the address of the text for "hello". The word "stype" adds 1 to the address on the stack and then returns data which is treated by "type" as a packed string. So the code:

greet show text s stype ;

Will display "hello" on the screen. Of course that's only part of the phrase. I added a definition to get a word, display it, and add the address for the next word.

nxtw 1 + dup @ type space ;

The word "space" was defined in a previous posting. I then added a word to unpack and display several words of text.

words for nxtw next ;

So the code:

greet show text s 5 words ;

Will display:

hello , i speak forth

I'm looking for better ways to do this. All comments welcome.

Starting Forth chapter 1 examples.

2006-12-21T12:04:00.000-08:00

Intro to PrimaryColorForth

The goal here is to simply reproduce all of the examples from chapter 1 of Starting Forth in ColorForth.

Washing Machine Example

washer wash spin rinse spin ;

In ColorForth red words signify the start of a new definition. So "washer" is the new procedure. The ";" represents the call return. The green words are procedures that have already been defined. Let's look at the definition of rinse.

rinse faucets open till-full faucets close ;

The definition includes "things" (faucets) and verbs (open and close). The word "till-full" represents a delay loop. After the faucets "open" the word waits "till-full" before they "close".

Note. Unlike traditional Forth words cannot be defined from the command line. All words must be defined in the editor. Then the block containing the source text must be loaded. For example if you defined some new words in block 22 you would type:

22 load

Putting on a show

Forth was originally designed around a TTY display model. But ColorForth uses a GUI display, albeit one that is MUCH simpler than MS Windows, X-Windows or MacIntosh. So getting things displayed on the screen is a bit tricker than traditional Forth, but simpler than raw programming of most GUI operating system. The ColorForth word "show" creates a display task using the words following it.

Consider this definition.

ok show text 45 emit keyboard ;

This creates a new definition "ok" that draws a "*" at the top left corner of the screen. The word "text" moves the cursor to the top left of the screen and sets the drawing color to white. The word "emit" takes a number off the stack and draws the corresponding charecter. It's the same as "emit" in traditional Forth. Note that the charecter set is different from ASCII. The word "keyboard" redraws the keyboard and stack.

Chapter 1 of Starting Forth builds up an example on how to draw the letter "F" as a large charecter using "ASCII art". Here is a walkthrough of that example using colorForth.

The first word "space" draws a blank space on the screen.

space 0 emit ;

The next word "spaces" draws a certain number of spaces. For instance "5 spaces" would draw 5 spaces. Note that the "for..next" loop will be covered in detail later.

spaces for space next ;

The word "star" is similar to "space" but draws a star.

star 45 emit ;

The word "stars is similar to "spaces" but draws a number of stars.

stars for star next ;

The next words define the "F" using combinations of the above defined words. Note that "cr" stands for "carriage return". That simply moves the cursor to the next line.

side star spaces star ;
margin cr 30 spaces ;
blip margin star ;
bar margin 5 stars ;
f bar blip bar blip blip cr ;
ok show text f keyboard ;

After loading the block containing these words and typing "ok" from the command line a large "F" will be displayed on the screen.

Re-starting "Primary Colorforth"

2006-12-21T11:35:00.000-08:00

Hello all. Some months ago I announced that I was working on a tutorial for ColorForth called Primary ColorForth. It is a play on words for the Leo Brodie classic Starting Forth. The plan was (and still is) to build a tutorial that follows the "spirit" of Starting Forth while departing from it when necessary to better fit the ColorForth model. I made a little progress. (Actually Jeff Fox made a bigger contribution than I did with his "Editor" chapter.)

However the project got stalled. Part of the problem is that I got waylaid by other projects. But another bigger problem was the classic "chicken and egg" problem. Some of the examples I wanted to do in the first chapter required advanced concepts that I didn't want to cover until other chapters. I was really stuck. Then, in a discussion with Jeff Fox in the USENET group comp.lang.forth about learning VentureForth I got an idea. Jeff suggested that someone learning VentureForth should try to do the examples from Staring Forth in it. I found then (and still find) that a daunting prospect. But I knew I could many of them in ColorForth so I decided to try. Then while reading the first chapter I noticed that Brodie put some advance code in an example and simply said we'll explain how it works in a later chapter. Now why did I think of that?

So I'm restarting my efforts. Things that I need to explain later, I'll just note and explain later. It's good to be back!

I'm going to use the blog to track my progress. While the tutorial will be built here, this won't be the final "polished" version. That will be put at the ColorForth Wiki. I don't want to be slowed down by trying to be "perfect" the first time.

`multicore matrix multiplication examplecra` `2` `row by` `8` `col matrix is multiplied bycra` `2` `col by` `8` `row matrixcrresuting in vector r1c1 r1c2 r2c1 r2c2cr crr1out send vector r1 to right nodecrr2out send vector r2 to down nodecrrtdwn set port to right and downcrsynch dummy write to synchronize nodescrc1c2out send vectors c1 and c2 to rightindent` `and down nodescrgetres get results from right and down vectors`		200 list `0` `org` `r1out` `right b!` `7` `for @p !b unextcr1` `,` `2` `,` `3` `,` `4` `,` `5` `,` `6` `,` `7` `,` `8` `,crr2out` `down b!` `7` `for @p !b unextcr9` `,` `10` `,` `11` `,` `12` `,` `13` `,` `14` `,` `15` `,` `16` `,crrtdwn` `B5` `b!crsynch` `0` `!bcrc1c2out` `15` `for @p !b unextcr17` `,` `18` `,` `19` `,` `20` `,` `21` `,` `22` `,` `23` `,` `24` `,cr25` `,` `26` `,` `27` `,` `28` `,` `29` `,` `30` `,` `31` `,` `32` `,crgetresright b! @b @b down b! @b @b r---`
`invect` `a- read in vector and store at a` `ab-ab` `17` `bit multiply.proda-n read in vector and do dot product wi th vector stored at ar*c1,c2p- read r from port p then read c1 and c2 and do dot products with r. return results to port p`		202 list `invect` `a!` `7` `for @b !+ unext ;` `a! dup dup or` `17push . begin + unext drop drop a ;.prod` `a! dup dup or` `7for @b @+ a push * + pop a! next ;r*c1,c2` `b!` `60` `invectcrsynch` `@b dropcr60` `.prod` `60.prod !b !b ;`
		204 list `0` `org` `202` `load` `69` `orgright r*c1,c2 r---`
		206 list `0` `org` `202` `load` `69` `orgdown r*c1,c2 r---`
		208 list `0` `org` `a! dup dup or` `17push . begin + unext drop drop a ;cr69` `org` `3 3* r---`
`singlecore matrix multiplication examplecr` `ab-ab` `17` `bit multiplication*sum` `v2ofs-n vector v1 is stored in a andcrv2ofs is the offset to vector v2. sum thecrproducts of v1 and v2.`		210 list `0` `org` `a push a! dup dup or` `17push . begin + unex t drop drop a pop a! ;sum` `dup dup or` `7for over a + b! @+ @b + ne xt push drop pop ;` `69` `orgcr40` `a!` `10` `sum` `8` `sum` `40` `a!` `18` `sum` `10sum r-- -` `40` `orgcr1` `,` `2` `,` `3` `,` `4` `,` `5` `,` `6` `,` `7` `,` `8` `,cr9` `,` `10` `,` `11` `,` `12` `,` `13` `,` `14` `,` `15` `,` `16` `,cr17` `,` `18` `,` `19` `,` `20` `,` `21` `,` `22` `,` `23` `,` `24` `,cr25` `,` `26` `,` `27` `,` `28` `,` `29` `,` `30` `,` `31` `,` `32` `,cr`