Forth Programmer’s Handbook

tioning within a given source, not switching between sources).

Return the address and length of the input buffer.

References Text interpretation and >IN, Section 1.1.5

4.1.3 Dictionary Searches

It must be possible to look up words and their definitions in the dictionary. Forth provides several words to do this, each of which performs a search and returns information about a word, typically its execution token. These searches are used in the text interpreter and colon compiler.

The word ' (“tick”) performs a dictionary search for the word that immediately follows it in the current input stream.

The phrase:

' <name>

when typed at a terminal or executed interpretively in source text, pushes onto the stack the execution token of name if name can be found in the dictionary. If name cannot be found, an abort will occur with an error message such as:

<name> ?

Since the precise definition of the “execution token” returned from dictionary searches varies, depending upon the implementation, the word >BODY is provided. Given an execution token, it will always return the parameter field (content) address. On many systems >BODY is a no-op.

The most common uses of ' for dictionary searches are:

The Forth Interpreter and Compiler 123

Forth Programmer’s Handbook

!To learn whether a word has been defined.

!To find the location of a word, using >BODY (for example, to DUMP its contents).

!To obtain the location of a data object (again, using >BODY) whose run-time behavior is other than returning its address.

' is not immediate. That is, if you wish to compile a reference to an address, as

!in the third item listed above, you must use [']. The word ' always takes its operands from the current input stream at the time it is executed.

The following are dictionary search words:

124 The Forth Interpreter and Compiler

Forth Programmer’s Handbook

4.1.4 Input Number Conversion

Wherever possible, an application should be designed to take advantage of Forth’s interactive nature. Thus, a hypothetical word SCANS whose function is to perform some user-specified number of scans (an application function) should expect only its parameter on the stack. Then, to perform 100 scans, the user could type:

100 SCANS

Such usage is natural and convenient for the operator, and requires no special programming to handle the input parameter.

There are occasions in which normal Forth syntax is inadequate. Some examples include:

!Parsing a text string that comes from a source other than a terminal, such as magnetic tape.

!Entry of numbers that must be in double-precision but are not punctuated (i.e., zip codes).

!Entry of numbers that must follow, rather than precede, the command.

Forth provides several words to enable the user to handle input numbers in a variety of circumstances. This section describes these methods.

>NUMBER is the basic input number conversion routine. If it encounters any non-numeric digit during the conversion, it stops with a pointer to the digit, rather than aborting. For this reason, >NUMBER is often used when a number is input by a program directly, without using the text interpreter.

>NUMBER expects a double-precision integer, and the address and count of the input string. It leaves a double-precision integer (the result of the conversion), and an address and count. The initial address into >NUMBER must point to the first digit of the string of numerals. The initial double-precision number is usually set to zero.

After >NUMBER stops, the address in the second stack item is the address of the first non-numeric character >NUMBER encountered or, if the string was entirely converted, is the first character past the end of the string. The double-preci- sion integer will contain data from all digits converted thus far.

The Forth Interpreter and Compiler 125

Forth Programmer’s Handbook

An example of the use of >NUMBER is:

This definition initializes a region of PAD to blanks, and awaits up to five digits which will be stored there. 0. provides an initial double-precision value, and PAD R> provides the address and actual count for >NUMBER. The 2DROP DROP discards the address and count returned by >NUMBER and the high-order part of the converted number.

INPUT will not convert input strings with a leading minus sign, because a minus is not a digit. If negative input is necessary, the above definition can be extended to check the character upon which conversion stopped to see if it is a minus sign and, if it is, start >NUMBER again and negate the result.

>NUMBER returns the address of the string’s next byte, so >NUMBER may be called in a loop. The text interpreter’s number conversion routine calls >NUMBER in just this way. An application similar to this is parsing a packet of data received over a communications line, or from a tape record in which numeric fields are separated by an arbitrary delimiter such as //. To skip such items, or to skip fields that are not of interest, the appropriate count of bytes may simply be added to the address, which is carried on the stack.

In some cases, numbers may be in fields of known length but not separated by any delimiter. In such cases, the best solution may be to use CMOVE to move groups of digits to PAD, where they may be converted easily by >NUMBER.

Convert the characters in the string at c-addr1, whose length is u1, into digits, using the radix in BASE. The first digit is added to ud1. Subsequent digits are added to ud1 after multiplying ud1 by the number in BASE. Conversion continues until a non-convertible character (including an algebraic sign) is encountered or the string is entirely converted; the result is ud2. c-addr2 is the location of the first unconverted character or, if the entire string was converted, of the first character beyond the string. u2 is the number of unconverted characters in the string. “to-number”

126 The Forth Interpreter and Compiler