The colorForth Editor

To invoke the editor from the interpreter, first enter a block number; let's say, 18. When you have done this, the number 18 will appear at the top of the Interpreter's stack display. Do not attempt to edit blocks 0 through 17; these contain binaries and listing binaries can cause the windows version to trap.

Now type edit .

You will see the source code to block 18 and the number 0018 will be displayed in a faint background watermark on the screen, indicating the block being viewed and edited. The editor control panel hint map is displayed in the lower right part of the screen.

Operating the Editor

The editor is operated by pressing buttons on a control panel. All control panels in colorForth are built from the same set of 27 keys; only the assignments differ. These keys are as follow:

colorForth keyboard

The editor control panel hint map, displayed in the lower right part of the screen, is as follows:

arrayForth colorForth editor keyboard map

colorForth editor commands

"s"  enter white comments all in the small font (Do not use, will go away!)
"c"  enter white comments with the first character in the small font and
    the rest in the big font (Do not use, will go away!)
"t" enter white comment text in lower case only.
"y" enter yellow text.
"r" enter red word, then switch to green text.
"g" enter green text.
"x" toggle odd/even source/shadow code/comment blocks
"c" cycle color white-yellow-green word before cursor
"d" Start find-function based on word before cursor.  If red or magenta, find reference.
If a number, edit that block. Otherwise, find definition. "f" repeat last 'find' "j" jump to last edited block "l" move cursor left "u" move cursor up (eight left) "d" move cursor down (eight right) "r" move cursor right "a" enter grey address word "b" enter blue word "k" copy (similar to "x" cut but does not delete the word) "-" decrement edited block number by two "m" enter magenta text (variables) "c" enter cyan text "+" increment edited block number by two "X" delete the current word (cut for paste) "." exit editor to Interpreter "i" insert word (paste from buffer)

Exiting and re-entering the Editor

To exit the Editor, returning control to the Interpreter, strike the space bar (. key). To return to the Editor, you may type e or enter a new block number and type edit. The editor may also be entered using the vocabulary for finding source, described later below.

Cursor Control

When the editor is started for the first time the cursor will appear in the upper left corner of the block. If there is text there it will appear on top of the first character. If the cursor is moved to the right it will be placed in the first space to the right of the first word.

colorForth cursor

The cursor resembles a pac-man character poised to munch the word to the left when the "X" (delete word) key is pressed. Strings of text can be cut by repeatedly pressing or holding the "X" key. The cursor can be moved to a different location on that block, or to a different block, and inserted with the "i" key.

Left, Up, Down, and Right keys under the fingers of the right hand move the cursor. The cursor cannot be moved above the top of the screen but it can be moved below the bottom of the screen. If the cursor is not visible hold down the Up key. It should always appear eventually.

"l" move cursor left
"u" move cursor up (eight left)
"d" move cursor down (eight right)
"r" move cursor right
Note that the Up and Down keys do not make precise up and down movements and only move eight words to the left or right respectively if possible.

Words that have been deleted with the "X" key can be re-inserted with the "i" key after the cursor has been moved.

Text Entry Modes

New text in any color can be inserted by pressing one of the Editor buttons that select color and enter text entry mode. To determine the current state of the keyboard, look in the hint area; if you see the editor control panel, buttons will be editor functions, whereas if you see text entry mode hints, you are entering text.

To return to the Editor from any text entry mode, use the method defined by the keyboard in use.

white comment entry

Comments will appear in white when editing and will be ignored by the compiler. Comments may contain any of the colorForth characters. Comments can be entered in three ways:
"s" In old systems, enter CAPITALIZED white comments.
   This feature has been deprecated, please do not use it.
"c" In old systems, enter Camelcase white comments.
   This feature has been deprecated, please do not use it.
"t" enter white comments in lower case.
In current colorForth systems, decimal and hex numbers may be entered as comments; this facilitates the commenting of most compiled or interpretive code if desired.

When source is compressed using save the deprecated tags for capitalized and Camelcase comments are converted to lower case comments.

yellow text and number entry

Yellow text are words that are interpreted in colorForth when blocks are loaded. Red words are the names of new defined words, they are like the names that follow ":" in traditional Forth. Green words are words being compiled. Magenta words are variables, and cyan words are like "postponed" words in ANS Forth (calls to macros).

Numbers can be entered in green or yellow mode. Numbers can be entered in decimal or hex mode. Hex numbers will appear in a darker green or darker yellow than decimal numbers, and may be italicized when the display medium permits.

If one intends to enter a number but enters a character string that resembles a number instead, it cannot be visually distinguished from a decimal number as it will be the same shade of yellow or green. But when you load the block unless you have actually defined a red word or magenta variable with a name that can be confused for a number, which is generally not a good idea in the first place, you will get a compiler error message that it did not recognize the string (that looked like a number) as a defined name.

There is a Forth wordlist and a macro wordlist in the colorForth compiler and the macro wordlist is searched first during compilation. Words in the macro wordlist act like "immediate" word in traditional Forth. Macros are executed at compile time when referenced in green. To compile a call to a macro, rather than to execute it at compile time, reference that macro with a cyan word.

green text and number entry

Green words like if are compiled, but because they are in the macro wordlist and act like immediate words, they are executed at compile time like words written explicitly in yellow.

A transition from green words to yellow words and back to green words is interpreted by the compiler as follows: The transition from green to yellow marks the transition from compilation mode to interpretation mode as would be indicated by the ANS Forth word "[" and the transition from yellow to green is interpreted by the compiler to mean a transition from interpretation mode to compile mode, and the compilation of a literal as would be indicated by the ANS Forth phrase "] LITERAL"

red name entry

When the "r" key is pressed to enter a red word the text for the red name will be aligned on the left side of the screen. A red name is the name of the compiled code that follows it in green. The red name can then be used in green, yellow, cyan or white colors. A call or jump to the word can be compiled with green usage, the word can be interpreted with yellow usage, a defined macro can be postponed (compiled as a call, rather than executed at compile time) with cyan usage, and if written in white will always be a comment.

After entering a red word the editor will change the color of the text or numbers being entered into green because the red word is the name of the compiled, green code that follows.

magenta variable name entry

Magenta words are not used in F18 code. This section applies only to programming the host computer.

When selecting magenta, and a magenta variable name is added to a block, a green number with the value 0 will be added after the magenta name. The magenta word when executed places the address of the location of the green number on that block on the parameter stack. One interesting feature of colorForth is that this address is in fact the address of a cell in the source, specifically the cell from which the green zero is being displayed. The variable, and its value, are part of the source and when you save the source you also save the values of variables! Display a block containing a variable and change the variable using the interpreter. You will see the green number in the source display change immediately! Note: colorForth has historically required that references to variables must always be in yellow; the code compiled for a green variable reference is incorrect. We have not gotten around to fixing this yet.

cyan entry

Cyan words are not used in F18 code. This section applies only to programming the host computer.

Cyan words are like postponed words in ANS Forth. A macro is executed immediately by the compiler when encountered as a green word. When a macro is referenced as a cyan word, the compiler does not execute the macro but compiles a call to it.

blue entry

Blue words are words that are executed at edit time. They can format the display with cr br indent etc. or execute custom commands while viewing a screen. The word seeb on block 648 is "see blue" and when yellow will execute at boot time and make blue words visible in the editor. If seeb on block 648 is white then blue words will not be visible but will execute when a block is displayed. After the system has booted, you may execute seeb at any time to toggle the display of blue words on or off.

grey entry

Grey words display an address wherever desired in F18 code. Any short word (four characters or less) may be used; the word itself does not matter nor is it ever displayed in its own right.

Other Editor Functions and Related Tools

Cut, Copy and Paste

The Editor has a buffer of finite size (about a block's worth) for holding code that has been "cut" or "copied" for later "pasting". The buffer works like a stack. The buttons that control this are:
"k" copy (similar to "x" cut but does not delete the word)
"X" delete the current word (cut for paste)
"i" insert word (paste from buffer)
Each depression of the cut or copy button pushes a copy of the word or number to the left of the cursor into this stack buffer, leaving the cursor to the left of where the word or number is (or was before it was deleted.) Each depression of the paste button pops the top word or number from this stack buffer and inserts it at the cursor position, moving the cursor to the right.

Block Navigation

To begin editing some other arbitrary block, exit the editor and re-enter using edit as was described earlier. For local navigation the Editor supplies the following:
"x" toggle odd/even source/shadow code/comment blocks
"j" jump to last edited block
"-" decrement edited block number by two
"+" increment edited block number by two
The "j" key alternates between the last two blocks that you edited with the word edit . The traditional variable blk contains the number of the current block being edited, and is unchanged when you exit the editor. blk 1 + is the number of the block that was current the last time edit was used. In addition to alternating the displayed block, the "j" key alternates these two values in blk .

The "x" key toggles between odd and even blocks while editing. Even numbered blocks are intended for source code and odd numbered blocks, called shadows, are intended for documentation. Since odd numbered blocks are not normally compiled, red, yellow, green, cyan, or magenta words on those blocks are intended to be comments only and may be used as desired to enhance readability, with the understanding that shadow blocks are not normally loaded.

The "+" and "-" keys on the editor keyboard map move two blocks up or two blocks down. The editor will not decrement the block number to be edited below 18. More advanced navigation is supplied by the Search Utility; see below.

Copying Blocks

To copy a source block and its shadow, first display the source block that you want to copy using the editor, so that its number is in the variable blk . Then, exit the editor; put a destination source block number on the stack, and type copy . The first block, and its accompanying shadow, will be copied to the destination. If you want to edit the copied block just type e as blk will now be set to the number of the destination block.

Search Utility

A resident set of utility functions, integrated with the Editor, facilitates searching the source in several practical and useful ways. When in the Interpreter, there are four words for starting a search, and one for continuing it. The words for starting the search are find def from literal .

When a search is started, we begin at block 18 (except in the case of from ) and scan forward looking for the particular target. If it is not found, we remain silently in the Interpreter. If it is found, we enter the Editor with the cursor set at (immediately to the right of) the target.

Once a search has been started, it may be continued from the point of the last target found by using the "f" control panel key, if in the Editor, or by typing f in the Interpreter. In either case, a successful find will display a block, while a failure to find will be as though you had done nothing at all.

When continuation is begun using the word f in the Interpreter, searching resumes at the point of last find in that same search. When continuing using the "f" control panel button in the Editor, the search resumes at the current cursor position in the current block, so you have more control in this case.

The searches continue up to the end of your disk image as defined by the three variables at the start of block 18. Do not attempt to change these variables at this point in your study!

The searches automatically consider only blocks of the same sort (source or shadow) as the block in which the search was started or continued. Thus, searches normally start with source only; they will never consider shadows unless you force them to using the word from with an odd block number, or by using the Editor's "f" key while looking at a shadow. To search all shadows, start a search normally, then edit block 19 and use the Editor's "f" key to continue.

Interpreter Search Words

Editor Search Keys

All of the above work in both Native and Windows systems.

Written by Jeff Fox and friends.