ColorForth Commentary

NOTICE: This is a work in progress. Parts of my commentary are still very rough. However, I have it up on the web because even in this rough form it may be useful to ColorForth enthusiasts. Expect the contents of these files to change frequently.

Contents

• Introduction
• Conventions
• Overview [this will go away soon]
• Source code:
  • BOOT.ASM
  • GEN.ASM
  • COLOR.ASM:
    • First items
    • Tasks
    • Dictionary routines
    • Compiler routines
    • Wordlists
    • Utility routines
    • Screen routines
    • Editor

Introduction

Chuck Moore's ColorForth is one of the main inspirations for Karig. It provides an environment where a programmer can experiment with code as easily and quickly as possible. I want this kind of environment in Karig, so I decided that I needed to study ColorForth in detail. Unfortunately, while Chuck Moore has written a number of pages explaining the ColorForth concept in detail, his source code is very sparsely commented. Judging from discussions on the Web about ColorForth, I'm not the only one who is interested in ColorForth but has had trouble following the source code. So I started writing this commentary.

This special feature will explain the routines in the ColorForth source code (22 July 2001 edition). For each routine that I explain, I will provide a "called-by" list of routines that call the routine. I also repeat the source code here, except that I've changed most label references into links — a call to the unPAUSE routine appears as call unPAUSE — so that you can follow the code just by clicking links. I also provide links to other sites on the Web that explain bits and pieces of the source code. I hope in time to make this a useful and reasonably complete reference to Chuck Moore's code.

Please note that I have posted this before I've finished with it, because other people may find even my incomplete efforts to be informative and useful. As of this date (14 February 2004), it is very incomplete, although all the links between references and labels should be in place. There will be holes in my commentary for a while. I'll update this as I find time, and as I discover more about Chuck's code. In the meantime, if you find any gross errors or omissions, by all means let me know about them, and I'll fix them.

I should also mention that Chuck Moore has written all of this code and that I'm only commenting on it. He has also explicitly placed this code in the public domain, so I expect that there won't be any problems with me republishing his code with annotations.

Conventions

I've reprinted Chuck Moore's source code and made some changes:

• I've converted all of the text to lowercase.

• Each label is printed in bold.

• If a label is referenced in one of the two wordlists (see Wordlists), I've printed the label in red. If a label is spelled differently from the ColorForth word that invokes the code, the ColorForth word is listed in quotation marks after the label, like this:

  text1: ;"text"

• After each label is a list of "Refs." Each word in this list is a link to the label of a routine or table that includes a reference to the current label. Thus if spin calls cmd, then the list of refs under the cmd label will include a link to spin.

  Be aware, though, that if one routine "falls through" to the one below, the list of refs for the routine below will not include a link to the routine above.

• Sometimes a ref may be followed by "(R)", "(W)", or "(RW)." This may be the case if the current label is a variable and the routine referenced is known to read the variable, write to it, or both, respectively.

• Each reference to a label within the source code has been converted to a link to that label, so that you can follow a call by clicking a link, and you can return by clicking your browser's Back button.

• Sometimes a routine will fiddle with the return stack — it will push more than it pops or vice versa. Such a routine might not return to its caller, or it might call its caller and return to itself, or it might cause some other change in the program flow. An instruction that fiddles with the stack, such as a pop unaccompanied by a push, or a store to the return-stack pointer (ESP), is marked with [RST] ("return-stack trick").

Links

I'll add more links later. I want to limit this list mainly to sites that discuss either the source code itself or specifics about the design of ColorForth from a programmer or code reader's perspective.

Chuck Moore's colorForth site

• Short feature list: Optimization
• Pentium colorForth: Register use; implementation of some Forth words.
• Pre-parsed words: The meaning of each color, and of the bits in a pre-parsed word.
• 48 characters: The bit strings that stand in for characters in a pre-parsed word.

Other sites

• Coloring Forth: Implementation of ";" (return), "dup" (cdup), and "?dup" (qdup).

Check the archives for other entries.