Forth Programmer’s Handbook

ences to them in code easy and readable. Because most Forth code routines can do what they need by using the designated scratch registers, there is less need to save and restore registers than in conventional programming.

References Principles of Forth assemblers, Section 5

The product documentation for a specific Forth system

1.4 DOCUMENTATION AND PROGRAMMER AIDS

In Forth, as in all other languages, the primary responsibility for producing readable code lies with the programmer. Forth does, however, support the programmer’s efforts to produce easily managed code by providing aids to internal documentation. In addition to these, we recommend that each Forth programming group adopt uniform editorial and naming standards and conventions. Sample standards adopted by some groups are offered in Section 6. Although readability is an aesthetic and rather personal value, a set of standards that all members of a group adhere to will significantly improve the ability of members of the group to share code and to support one another.

1.4.1 Comments

Comments embedded in Forth source are enclosed in parentheses. For example:

( This is a comment)

The word ( must have a space after it, so that it can be recognized and executed as a command (to begin the comment). A space is not needed before the closing right parenthesis delimiter. On most systems, the \ (backslash) character is also defined, indicating that the entire remainder of the current line of source code is a comment.

The word .( (note the preceding dot) is like (, but begins a comment that will be displayed when it is encountered. If it occurs inside a definition, the text will be displayed when the definition is compiled, not when it is executed. It is commonly used in source code to indicate progress in compilation, e.g.:

.( Begin application compilation)

22 Introduction

Forth Programmer’s Handbook

Forth comments are most often used to give a picture of a word’s stack arguments and results; for example, a high-level definition of the Forth word = is:

The dashes in the comment separate a word’s arguments (on the left) from its results. By convention, certain letters have specific, common meanings:

Table 4: Common stack notation

Word Description

n A single-cell signed integer.

u A single-cell unsigned integer.

t A single-cell Boolean value (zero is false, non-zero is true).

addr An arbitrary single-cell byte address.

d A double-cell signed integer.

Thus, in the example above, the word = expects two single-cell integers and returns a truth flag.

Words that have separate interpretive and run-time behaviors should have comments for both sections:

References Stack notation, Section 2.1.1

Data types in stack notation, Section B.3

Glossary

Like (, but begin a comment that will be sent to the display device when it is encountered. Terminated by a right parenthesis ).

Introduction 23

Begin a comment which includes the entire remainder of the current line of source code. No closing delimiter is needed.

1.4.2 Locating Command Source

After code has been compiled from source files, the LOCATE command can call up the source code for a command, given the command name. For example, the command:

LOCATE /STRING

starts the editor, opens the correct source block or file, and positions the cursor at the start of the definition of /STRING:

: /STRING ( c-addr1 len1 u -- c-addr2 len2) OVER MIN >R SWAP R@ + SWAP R> - ;

Similarly, if the compiler encounters an error and aborts, you may go directly to the block (or file) and line at which the error occurred by typing L. This is particularly convenient if you have a linked editor, as you can immediately repair the error and recompile.

Glossary

LOCATE <name> ( — )

If name is the name of a definition that has been compiled from source code, display the source code for name. On some systems, the phrase VIEW name performs a similar function.

L ( — ) common usage

Show the current source code file or block and the current cursor position in it. If used after a compiling error, point to the source code that caused the error.

1.4.3 Cross-references

This tool finds all the places a word is used. The syntax is:

24 Introduction

Forth Programmer’s Handbook

WHERE <name>

It gives the first line of the definition of the word name, followed by each line of source code in the currently compiled program that contains name.

If the same name has been redefined, WHERE gives the references for each definition separately. The shortcut:

WH <name>

does the same thing.

This command is not the same as a source search, since it is based on the code you have currently compiled and are debugging. This means you will be spared instances of name in files you aren’t using.

Glossary

Short synonym for WHERE, defined for typing convenience.

WHERE <name> ( — )

Display all the places in the currently compiled program where name has been used, showing any re-definitions separately.

1.4.4 Decompiler and Disassembler

The disassembler/decompiler is used to reconstruct readable source code from CODE and : (colon) definitions. This is useful as a cross-check, whenever a new definition fails to work as expected.

The command SEE name disassembles both CODE commands and colon definitions. For example, the source definition for /STRING is:

: /STRING ( c-addr1 len1 u -- c-addr2 len2) OVER MIN >R SWAP R@ + SWAP R> - ;

but if you decompile it (on a FORTH, Inc. 68000 cross-compiler, for example), you get:

Introduction 25

Forth Programmer’s Handbook

This example clearly shows the combination of in-line code and subroutine calls in this subroutine-threaded implementation.

An alternative approach is to start disassembly or decompilation at some address. This is useful for decompiling headless code, such as code preceded only by a LABEL. The command to disassemble a CODE definition, given an address addr, is:

<addr> DASM

The word .' is becoming increasingly popular in this debugging context, though it is not in Standard Forth nor in all systems. It attempts to identify the definition in which an address occurs. For example, given /STRING above, you could type:

HEX 9BE .'

and get:

/STRING +08 ok(T)

Glossary

SEE <name> ( — ) Tools

Reconstruct the source code for name, using as necessary a decompiler for high-level definitions or a disassembler for code definitions.

26 Introduction