Forth Programmer’s Handbook

References Numeric input, Section 1.1.6

CMOVE, Section 2.3.3

ACCEPT, Section 3.3.1

PAD, Section 2.3.1

4.1.5 Character String Processing

Character strings may be received or transmitted by using words defined in Section 3.3. Such input or output is only possible, of course, where the terminal device is capable of supporting the required operation.

4.1.5.1 Scanning Characters to a Delimiter

WORD is the main work-horse of Forth’s text interpreter. It fetches characters from the input stream, starting at the offset given by the user variable >IN, until reaching a specified delimiter. WORD takes its input from the current input source; this is normally the terminal input buffer. During the time text is being interpreted from a source code file (either block or text file), the current input source is the designated file.

WORD expects the delimiter character in the low-order byte of the top item that is on the stack. WORD skips any leading occurrences of this character, searching for a non-delimiter character; if one is found, it is placed in a temporary storage area. Succeeding characters are then moved into this area until a delimiter character is encountered or until the specified end of the string is reached, which terminates the operation. The area where the characters are placed is not initialized, although WORD will insert one trailing blank after the string.

The maximum length of a string depends on the input source. If the source is the keyboard, the maximum length is set by the size of the terminal input buffer. If the source is a block, the maximum length is 1024. If the source is a file, the string expires at the end of the file.

WORD places on the stack the address of the string. The first byte of this string contains the number of input characters in the string, up to the occurrence of the delimiter—this is convenient for words that often follow it, such as >NUMBER.

The storage space used by WORD may be used by other Forth functions as well,

The Forth Interpreter and Compiler 127

Forth Programmer’s Handbook

such as output number conversion. As a result, when you use WORD to pick up a string from the input stream, you should finish working with it or promptly move it to another area (such as PAD) to avoid confusion.

As an example of WORD’s use, consider the following simple TEST example (COUNT is a standard word whose definition is shown here for convenience. Its principle use is to convert a counted string to a plain character string, returning address and count on the stack):

TEST would be used in the following way:

TEST ABC (carriage return) ABC ok

Because using a space for a delimiter is so common, the word BL (for blank) is defined, which returns the ASCII value for a space. Thus, phrases such as 32 WORD can be replaced by BL WORD, which is more readable.

COUNT may also be used with plain strings. Successive calls to COUNT will “walk” through the string, returning each character and incrementing the address.

In many systems, this is the name given to the text interpreter pointer. It returns a-addr, the address of a cell containing the offset in characters from the start of the input buffer to the start of the current parse area. “to-in”

Skip any leading occurrences of the delimiter char. Parse text delimited by char. Return c-addr, the address of a temporary location containing the parsed text as

128 The Forth Interpreter and Compiler

Forth Programmer’s Handbook

a counted string. If the parse area was empty or contained only delimiter(s), the resulting string length is zero.

References Fetching input characters to PAD, Section 3.3.1 >NUMBER, Section 4.1.4

Text interpreter, Section 1.1.5

Character string output (TYPE), Section 3.3.2

4.1.5.2 Compiling and Interpreting Strings

There are two cases in which it is desirable to have text messages compiled in programs: to issue error messages and to communicate information during normal operation. The words in the following list provide support for compiled strings. These words may be used only inside a definition (except S"). In all cases, a quote mark delimits the end of the string.

S" also may be executed interpretively, if you need the address and count of a string outside of a definition. For example, INCLUDED loads a file, given the address and count of a string on the stack containing the filename. The syntax would be:

… S" <filename>" INCLUDED …

On many implementations, however, an interpreted S" uses a single buffer to hold the string. Therefore, successive uses of S" may over-write the buffer from a previous use.

Each of these words has functions to be performed both at compile time and at

!execute time. At compile time the address of the execute-time function is compiled, along with the string. At execute time the behavior differs. For S", the address and length of the string must be pushed on the stack. For ABORT", the test must be performed. For both ." and ABORT", the string must be typed out. The stack notation for the words below refers to the execution-time behavior.

Compile the following string, terminated by ". At run time, the address and length of the string (two stack items) will be pushed on the stack. “S-quote”

The Forth Interpreter and Compiler 129

Forth Programmer’s Handbook

For example:

S" WARM " ELSE S" COOL "

THEN TYPE ;

This will display the message WARM if the temperature value on the stack is greater than 68, and will display COOL otherwise.

C" <string>" ( — c-addr )

Same as S", but compiles a counted string (length stored in first byte). As with S", the string is terminated by ". At run time, the address of the counted string (one stack item) will be pushed on the stack. “C-quote”

Compile text, to be typed as an error message if the value on the stack, flag, is true when the phrase containing ABORT" is executed. “abort-quote”

If ABORT" finds its argument to be true (any non-zero value), it will echo the command most recently interpreted, issue the message, clear both data and return stacks, and return control to the operator. For example:

ABORT" TOO BIG" ;

References Error handling, Section 2.6

Compiling strings, Section 4.3.7

130 The Forth Interpreter and Compiler