Forth lecture 14.

Forth high lighting.

Introduction

The syntax high lighting of other languages showing the ``type'' of a word is pretty useless in Forth because words have no type. To make color highlighting potentially valuable we have to rethink what information we want most. That information is of course the stack effect. Since there is an -- albeit experimental -- way to add the stack information to ciforth, a rather simple program can add color high lighting to the word ID. that displays a Forth word. ciforth, as an indirect threaded Forth, allows to retrofit a colored ID. onto a system. This is complemented by a few modifications to the decompilation system.

Start color high lighting by DO-COLOR.

Stop color high lighting by NO-COLOR.

View a colored decompilation by CRACK WORD.

You can download the system to experiment with it on Linux. Sorry, but this won't work on Windows

The example below is described in a way that if you don't run it, you still get the idea.

Design

The color high lighting has as main aspects

The first letter in a word is colored to indicate stack input.
The last letter of a word is colored to indicate stack output.
The body of the letter is printed white, which is also the color for no stack I/O.
The words is printed on a blue black ground if it has variable stack effect, or is otherwise disconcerting (to be decided upon.).
The order of the stack depth is white, aqua, green, yellow and red. Red is used for everything over 3. Pink is used for unknown or variable.

The bottom line: if the code is nice, it looks nice.

Download

To make it possible for everybody to assess the possibilities of color high lighting in Forth I have made a binary distribution that you can download here. It only runs on Intel Linux, and it runs best from the console. The black screen background is essential. In KDE you can run a shell into a so called ``Linux console'' that has the same color settings. It is a saved system from a prerelease snapshot of unstable version 4.1 of ciforth with an as yet experimental program, loaded. This program is an analyser that adds the information about stack effect to the headers.

The sole purpose of all this it to find out whether you like the color high lighting and to allow you to experiment with it.

If you get stuck experimenting, you may want to inspect the documentation of the official release. Most differences are enhancements, the remaining ones are minute. The library forth.lab is a source library. Just listing it and the well known INDEX and LOCATE words may show you interesting things you want to inspect. The source of the decompiler is there, and all utility words loaded onto the system have their stack effect documented. This excludes the analyser words and the assembler words.

Example

You may want to run through this step by step :

tar xfz lina-color.gz
lina-color
80386 ciforth beta $RCSfile: ci86.gnr,v $ $Revision: 4.1.0.3 $
INCLUDE color.frt

Type WORDS to have a comparison. Now type

DO-COLOR
OK
WORDS
...
CRACK COLOR-ID.

This doesn't look too good. All new words in the decompilation and a large part of the dictionary is pink, i.e. unknown.

Now try the following sequence of commands:

FILL-ALL-SE
OK
CRACK COLOR-ID.
OK
 ..

After FILL-ALL-SE all stack effects have been filled in. However the decompilation looks disconcerting, because of a word with variable stack effect SELECT-COLOR.

After inspection of the source it is clear that that word always takes one parameter, and this is filled in by !SE. The stack effect is 1-0 . The hex value 21 is passed, because since 0 indicates unknown, the values are offset by 1.

HEX 21 'SELECT-COLOR !SE
 OK
CRACK SELECT-COLOR
OK
 ..
CRACK COLOR-ID.
...

We are still not happy because COLOR-ID. is highlighted with a blue background as a severe offender, while in fact it has a regular stack behaviour. Now reset its stack effect byte and run FILL-ALL-SE again.

0 'COLOR-ID. !SE
CRACK COLOR-ID.
FILL-ALL-SE
 OK
CRACK COLOR-ID.
: COLOR-ID.
DUP  >FFA  @þ  1þ  AND  0BRANCH  [ 0000,0008þ , ] DROP  EXIT
DUP  SE  SWAP  SELECT-COLOR  >R  NAME@  OVER  C@  EMIT
    SWAP  1+  SWAP  1-  DUP
0BRANCH  [ 0000,0020þ , ] 1-  white  2DUP  TYPE  +þ  C@
BRANCH  [ 0000,0008þ , ] 2DROP  SHOWING-CHAR
R> SELECT-COLOR  EMIT  black  white  2þ  SPACES
;

Now it looks nice! Only the white-aqua-green colors are left. The strange character after one letter words are place holders (in the console it shows up as a small block).

Some more words over how to read this.
We can see here some pipes. A pipe is a sequence of words where each word consumes the outputs of the previous one.
A white-white pipe is very reassuring and, what is more, you can think it away. Examples are ``OVER C@ EMIT'' , ``2DUP TYPE '' and ``R> SELECT-COLOR''.

A slightly more advanced pattern is the start DUP ... 0BRANCH. This is the combination of two white-aqua pipes ``DUP >FFA @þ '' and ``1þ '' with a green white pipe ``AND 0BRANCH '' . There is no total stack effect.
On the second line ``DUP .. R'' features a white-green pipe ``DUP SE SWAP '' followed by two aqua-white pipes ``SELECT-COLOR '' and ``>R '' . This too has no net stack effect.
The result is that you almost can visually connect the input of the total to ``NAME@'', which goes to the heart of the matter.

Interesting is also the sequence ``SWAP 1+ SWAP 1- ''. They may have not good connections between the words, but all of them have a net stack effect of zero. They are working on the stack in place.

Another example may be more practical.

CRACK CRACK

: CRACK
(WORD)  FOUND  DUP  0=  0000,000Bþ ?ERROR  CRACKED
;

This is more indicative of the situation where you are inspecting somebody else's code. Four out of seven words are probably unknown to you. With color highlighting you can think away the ``DUP ... ?ERROR'' sequence, because of the now familiar white-aqua, white-aqua green-white pattern. What is left is an aqua-white chain. More over it is obvious (from the meaning) that (WORD) leaves a Forth string constant and FOUND passes an execution token (aka DEA) to CRACKED.

Other Forth lectures

Go to the home page of Albert van der Horst