A.3.2.3.3 Return stack

The restrictions in section 3.2.3.3 Return stack are necessary if implementations are to be allowed to place loop parameters on the return stack.

A.3.2.6 Environmental queries

The size in address units of various data types may be determined by phrases such as 1 CHARS. Similarly, alignment may be determined by phrases such as 1 ALIGNED.

The environmental queries are divided into two groups: those that always produce the same value and those that might not. The former groups include entries such as MAX-N. This information is fixed by the hardware or by the design of the Forth system; a user is guaranteed that asking the question once is sufficient.

The other group of queries are for things that may legitimately change over time. For example an application might test for the presence of the Double Number word set using an environment query. If it is missing, the system could invoke a system-dependent process to load the word set. The system is permitted to change ENVIRONMENT?'s database so that subsequent queries about it indicate that it is present.

Note that a query that returns an unknown response could produce a known result on a subsequent query.

A.3.3 The Forth dictionary

A Standard Program may redefine a standard word with a non-standard definition. The program is still Standard (since it can be built on any Standard System), but the effect is to make the combined entity (Standard System plus Standard Program) a non-standard system.

A.3.3.1 Name space

A.3.3.1.2 Definition names

The language in this section is there to ensure the portability of Standard Programs. If a program uses something outside the Standard that it does not provide itself, there is no guarantee that another implementation will have what the program needs to run. There is no intent whatsoever to imply that all Forth programs will be somehow lacking or inferior because they are not standard; some of the finest jewels of the programmer's art will be non-standard. At the same time, the committee is trying to ensure that a program labeled Standard will meet certain expectations, particularly with regard to portability.

In many system environments the input source is unable to supply certain non-graphic characters due to external factors, such as the use of those characters for flow control or editing. In addition, when interpreting from a text file, the parsing function specifically treats non-graphic characters like spaces; thus words received by the text interpreter will not contain embedded non-graphic characters. To allow implementations in such environments to call themselves Standard, this minor restriction on Standard Programs is necessary.

A Standard System is allowed to permit the creation of definition names containing non-graphic characters. Historically, such names were used for keyboard editing functions and invisible words.

A.3.3.2 Code space

A.3.3.3 Data space

The words #TIB, >IN, BASE, BLK, SCR, SOURCE, SOURCE-ID, STATE, and TIB contain information used by the Forth system in its operation and may be of use to the application. Any assumption made by the application about data available in the Forth system it did not store other than the data just listed is an environmental dependency.

There is no point in specifying (in the Standard) both what is and what is not addressable.

A Standard Program may NOT address:

A.3.3.3.1 Address alignment

Many processors have restrictions on the addresses that can be used by memory access instructions. For example, on a Motorola 68000, 16-bit or 32-bit data can be accessed only at even addresses. Other examples include RISC architectures where 16-bit data can be loaded or stored only at even addresses and 32-bit data only at addresses that are multiples of four.

An implementor of ANS Forth can handle these alignment restrictions in one of two ways. Forth's memory access words (@, !, +!, etc.) could be implemented in terms of smaller-width access instructions which have no alignment restrictions. For example, on a 68000 Forth with 16-bit cells, @ could be implemented with two 68000 byte-fetch instructions and a reassembly of the bytes into a 16-bit cell. Although this conceals hardware restrictions from the programmer, it is inefficient, and may have unintended side effects in some hardware environments. An alternate implementation of ANS Forth could define each memory-access word using the native instructions that most closely match the word's function. On a 68000 Forth with 16-bit cells, @ would use the 68000's 16-bit move instruction. In this case, responsibility for giving @ a correctly-aligned address falls on the programmer. A portable ANS Forth program must assume that alignment may be required and follow the requirements of this section.

A.3.3.3.2 Contiguous regions

The data space of a Forth system comes in discontinuous regions! The location of some regions is provided by the system, some by the program. Data space is contiguous within regions, allowing address arithmetic to generate valid addresses only within a single region. A Standard Program cannot make any assumptions about the relative placement of multiple regions in memory.

Section 3.3.3.2 does prescribe conditions under which contiguous regions of data space may be obtained. For example:

	CREATE TABLE   1 C, 2 C, ALIGN 1000 , 2000 ,

makes a table whose address is returned by TABLE. In accessing this table,

TABLE C@                        will return 1
TABLE CHAR+ C@                  will return 2
TABLE 2 CHARS + ALIGNED @       will return 1000
TABLE 2 CHARS + ALIGNED CELL+ @ will return 2000.

Similarly,

	CREATE DATA   1000 ALLOT

makes an array 1000 address units in size. A more portable strategy would define the array in application units, such as:

	500 CONSTANT NCELLS
	CREATE CELL-DATA  NCELLS CELLS ALLOT

This array can be indexed like this:

	: LOOK   NCELLS 0 DO  CELL-DATA I CELLS + ? LOOP ;

A.3.3.3.6 Other transient regions

In many existing Forth systems, these areas are at HERE or just beyond it, hence the many restrictions.

(2*n)+2 is the size of a character string containing the unpunctuated binary representation of the maximum double number with a leading minus sign and a trailing space.

Implementation note: Since the minimum value of n is 16, the absolute minimum size of the pictured numeric output string is 34 characters. But if your implementation has a larger n, you must also increase the size of the pictured numeric output string.

A.3.4 The Forth text interpreter

A.3.4.3 Semantics

The initiation semantics correspond to the code that is executed upon entering a definition, analogous to the code executed by EXIT upon leaving a definition. The run-time semantics correspond to code fragments, such as literals or branches, that are compiled inside colon definitions by words with explicit compilation semantics.

In a Forth cross-compiler, the execution semantics may be specified to occur in the host system only, the target system only, or in both systems. For example, it may be appropriate for words such as CELLS to execute on the host system returning a value describing the target, for colon definitions to execute only on the target, and for CONSTANT and VARIABLE to have execution behaviors on both systems. Details of cross-compiler behavior are beyond the scope of this Standard.

A.3.4.3.2 Interpretation semantics

For a variety of reasons, this Standard does not define interpretation semantics for every word. Examples of these words are >R, .", DO, and IF. Nothing in this Standard precludes an implementation from providing interpretation semantics for these words, such as interactive control-flow words. However, a Standard Program may not use them in interpretation state.

A.3.4.5 Compilation

Compiler recursion at the definition level consumes excessive resources, especially to support locals. The Technical Committee does not believe that the benefits justify the costs. Nesting definitions is also not common practice and won't work on many systems.

A.4 Documentation requirements

A.4.1 System documentation

A.4.2 Program documentation

A.5 Compliance and labeling

A.5.1 ANS Forth systems

Section 5.1 defines the criteria that a system must meet in order to justify the label ANS Forth System. Briefly, the minimum requirement is that the system must implement the Core word set. There are several ways in which this requirement may be met. The most obvious is that all Core words may be in a pre-compiled kernel. This is not the only way of satisfying the requirement, however. For example, some words may be provided in source blocks or files with instructions explaining how to add them to the system if they are needed. So long as the words are provided in such a way that the user can obtain access to them with a clear and straightforward procedure, they may be considered to be present.

A Forth cross-compiler has many characteristics in common with an ANS Forth System, in that both use similar compiling tools to process a program. However, in order to fully specify an ANS Forth cross compiler it would be necessary to address complex issues dealing with compilation and execution semantics in both host and target environments as well as ROMability issues. The level of effort to do this properly has proved to be impractical at this time. As a result, although it may be possible for a Forth cross-compiler to correctly prepare an ANS Forth program for execution in a target environment, it is inappropriate for a cross-compiler to be labeled an ANS Forth System.

A.5.2 ANS Forth programs

A.5.2.2 Program labeling

Declaring an environmental dependency should not be considered undesirable, merely an acknowledgment that the author has taken advantage of some assumed architecture. For example, most computers in common use are based on two's complement binary arithmetic. By acknowledging an environmental dependency on this architecture, a programmer becomes entitled to use the number -1 to represent all bits set without significantly restricting the portability of the program.

Because all programs require space for data and instructions, and time to execute those instructions, they depend on the presence of an environment providing those resources. It is impossible to predict how little of some of these resources (e.g. stack space) might be necessary to perform some task, so this Standard does not do so.

On the other hand, as a program requires increasing levels of resources, there will probably be sucessively fewer systems on which it will execute sucessfully. An algorithm requiring an array of 109 cells might run on fewer computers than one requiring only 103.

Since there is also no way of knowing what minimum level of resources will be implemented in a system useful for at least some tasks, any program performing real work labeled simply an ANS Forth Program is unlikely to be labeled correctly.

A.6 Glossary

In this and following sections we present rationales for the handling of specific words: why we included them, why we placed them in certain word sets, or why we specified their names or meaning as we did.

Words in this section are organized by word set, retaining their index numbers for easy cross-referencing to the glossary.

Historically, many Forth systems have been written in Forth. Many of the words in Forth originally had as their primary purpose support of the Forth system itself. For example, WORD and FIND are often used as the principle instruments of the Forth text interpreter, and CREATE in many systems is the primitive for building dictionary entries. In defining words such as these in a standard way, we have endeavored not to do so in such a way as to preclude their use by implementors. One of the features of Forth that has endeared it to its users is that the same tools that are used to implement the system are available to the application programmer - a result of this approach is the compactness and efficiency that characterizes most Forth implementations.

A.6.1 Core words

A.6.1.0070 '

Typical use: ... ' name .

Many Forth systems use a state-smart tick. Many do not. ANS Forth follows the usage of Forth-83.

See: A.3.4.3..2 Interpretation semantics, A.6.1.1550 FIND.

A.6.1.0080 (

Typical use: ... ( ccc) ...

A.6.1.0140 +LOOP

Typical use: : X ... limit first DO ... step +LOOP ;

A.6.1.0150 ,

The use of , (comma) for compiling execution tokens is not portable.

See: 6.2.0945 COMPILE,.

A.6.1.0190 ."

Typical use: : X ... ." ccc" ... ;

An implementation may define interpretation semantics for ." if desired. In one plausible implementation, interpreting ." would display the delimited message. In another plausible implementation, interpreting ." would compile code to display the message later. In still another plausible implementation, interpreting ." would be treated as an exception. Given this variation a Standard Program may not use ." while interpreting. Similarly, a Standard Program may not compile POSTPONE ." inside a new word, and then use that word while interpreting.

A.6.1.0320 2*>

Historically, 2* has been implemented on two's-complement machines as a logical left-shift instruction. Multiplication by two is an efficient side-effect on these machines. However, shifting implies a knowledge of the significance and position of bits in a cell. While the name implies multiplication, most implementors have used a hardware left shift to implement 2*.

A.6.1.0330 2/

This word has the same common usage and misnaming implications as 2*. It is often implemented on two's-complement machines with a hardware right shift that propagates the sign bit.

A.6.1.0350 2@

With 2@ the storage order is specified by the Standard.

A.6.1.0450 :

Typical use: : name ... ;

In Forth-83, this word was specified to alter the search order. This specification is explicitly removed in this Standard. We believe that in most cases this has no effect; however, systems that allow many search orders found the Forth-83 behavior of colon very undesirable.

Note that colon does not itself invoke the compiler. Colon sets compilation state so that later words in the parse area are compiled.

A.6.1.0460 ;

Typical use: : name ... ;

One function performed by both ; and ;CODE is to allow the current definition to be found in the dictionary. If the current definition was created by :NONAME the current definition has no definition name and thus cannot be found in the dictionary. If :NONAME is implemented the Forth compiler must maintain enough information about the current definition to allow ; and ;CODE to determine whether or not any action must be taken to allow it to be found.

A.6.1.0550 >BODY

a-addr is the address that HERE would have returned had it been executed immediately after the execution of the CREATE that defined xt.

A.6.1.0680 ABORT"

Typical use: : X ... test ABORT" ccc" ... ;

A.6.1.0695 ACCEPT

Previous standards specified that collection of the input string terminates when either a return is received or when +n1 characters have been received. Terminating when +n1 characters have been received is difficult, expensive, or impossible to implement in some system environments. Consequently, a number of existing implementations do not comply with this requirement. Since line-editing and collection functions are often implemented by system components beyond the control of the Forth implementation, this Standard imposes no such requirement. A Standard Program may only assume that it can receive an input string with ACCEPT or EXPECT. The detailed sequence of user actions necessary to prepare and transmit that line are beyond the scope of this Standard.

Specification of a non-zero, positive integer count (+n1) for ACCEPT allows some implementors to continue their practice of using a zero or negative value as a flag to trigger special behavior. Insofar as such behavior is outside the Standard, Standard Programs cannot depend upon it, but the Technical Committee doesn't wish to preclude it unnecessarily. Since actual values are almost always small integers, no functionality is impaired by this restriction.

ACCEPT and EXPECT perform similar functions. ACCEPT is recommended for new programs, and future use of EXPECT is discouraged.

It is recommended that all non-graphic characters be reserved for editing or control functions and not be stored in the input string.

Commonly, when the user is preparing an input string to be transmitted to a program, the system allows the user to edit that string and correct mistakes before transmitting the final version of the string. The editing function is supplied sometimes by the Forth system itself, and sometimes by external system software or hardware. Thus, control characters and functions may not be available on all systems. In the usual case, the end of the editing process and final transmission of the string is signified by the user pressing a Return or Enter key.

As in previous standards, EXPECT returns the input string immediately after the requested number of characters are entered, as well as when a line terminator is received. The automatic termination after specified count of characters have been entered behavior is widely considered undesirable because the user loses control of the input editing process at a potentially unknown time (the user does not necessarily know how many characters were requested from EXPECT). Thus EXPECT and SPAN have been made obsolescent and exist in the Standard only as a concession to existing implementations. If EXPECT exists in a Standard System it must have the automatic termination behavior.

ACCEPT does not have the automatic termination behavior of EXPECT. However, because external system hardware and software may perform the ACCEPT function, when a line terminator is received the action of the cursor, and therefore the display, is implementation-defined. It is recommended that the cursor remain immediately following the entered text after a line terminator is received.

A.6.1.0705 ALIGN

In this Standard we have attempted to provide transportability across various CPU architectures. One of the frequent causes of transportability problems is the requirement of cell-aligned addresses on some CPUs. On these systems, ALIGN and ALIGNED may be required to build and traverse data structures built with C,. Implementors may define these words as no-ops on systems for which they aren't functional.

A.6.1.0706 ALIGNED

See: A.6.1.0705 ALIGN

A.6.1.0760 BEGIN

Typical use:

	: X ... BEGIN ... test UNTIL ;

or

	: X ... BEGIN ... test WHILE ... REPEAT ;

A.6.1.0770 BL

Because space is used throughout Forth as the standard delimiter, this word is the only way a program has to find and use the system value of space. The value of a space character can not be obtained with CHAR, for instance.

A.6.1.0880 CELL+

As with ALIGN and ALIGNED, the words CELL and CELL+ were added to aid in transportability across systems with different cell sizes. They are intended to be used in manipulating indexes and addresses in integral numbers of cell-widths.

Example:

2VARIABLE DATA

0 100 DATA 2!
DATA @ . 100

DATA CELL+ @ .  0

A.6.1.0890 CELLS

See: A.6.1.0880 CELL+.

Example: CREATE NUMBERS 100 CELLS ALLOT

(Allots space in the array NUMBERS for 100 cells of data.)

A.6.1.0895 CHAR

Typical use: ... CHAR A CONSTANT "A" ...

A.6.1.0950 CONSTANT

Typical use: ... DECIMAL 10 CONSTANT TEN ...

A.6.1.1000 CREATE

The data-field address of a word defined by CREATE is given by the data-space pointer immediately following the execution of CREATE

Reservation of data field space is typically done with ALLOT.

Typical use: ... CREATE SOMETHING ...

A.6.1.1240 DO

Typical use:

	: X ... limit first DO ... LOOP ;

or

	: X ... limit first DO ... step +LOOP ;

A.6.1.1250 DOES>

Typical use: : X ... DOES> ... ;

Following DOES>, a Standard Program may not make any assumptions regarding the ability to find either the name of the definition containing the DOES> or any previous definition whose name may be concealed by it. DOES> effectively ends one definition and begins another as far as local variables and control-flow structures are concerned. The compilation behavior makes it clear that the user is not entitled to place DOES> inside any control-flow structures.

A.6.1.1310 ELSE

Typical use: : X ... test IF ... ELSE ... THEN ;

A.6.1.1345 ENVIRONMENT?

In a Standard System that contains only the Core word set, effective use of ENVIRONMENT? requires either its use within a definition, or the use of user-supplied auxiliary definitions. The Core word set lacks both a direct method for collecting a string in interpretation state (11.6.1.2165 S" is in an optional word set) and also a means to test the returned flag in interpretation state (e.g. the optional 15.6.2.2532 [IF]).

The combination of 6.1.1345 ENVIRONMENT?, 11.6.1.2165 S", 15.6.2.2532 [IF], 15.6.2.2531 [ELSE], and 15.6.2.2533 [THEN] constitutes an effective suite of words for conditional compilation that works in interpretation state.

A.6.1.1360 EVALUATE

The Technical Committee is aware that this function is commonly spelled EVAL. However, there exist implementations that could suffer by defining the word as is done here. We also find EVALUATE to be more readable and explicit. There was some sentiment for calling this INTERPRET, but that too would have undesirable effects on existing code. The longer spelling was not deemed significant since this is not a word that should be used frequently in source code.

A.6.1.1380 EXIT

Typical use: : X ... test IF ... EXIT THEN ... ;

A.6.1.1550 FIND

One of the more difficult issues which the Committee took on was the problem of divorcing the specification of implementation mechanisms from the specification of the Forth language. Three basic implementation approaches can be quickly enumerated:

1) Threaded code mechanisms. These are the traditional approaches to implementing Forth, but other techniques may be used.

2) Subroutine threading with macro-expansion (code copying). Short routines, like the code for DUP, are copied into a definition rather than compiling a JSR reference.

3) Native coding with optimization. This may include stack optimization (replacing such phrases as SWAP ROT + with one or two machine instructions, for example), parallelization (the trend in the newer RISC chips is to have several functional subunits which can execute in parallel), and so on.

The initial requirement (inherited from Forth-83) that compilation addresses be compiled into the dictionary disallowed type 2 and type 3 implementations.

Type 3 mechanisms and optimizations of type 2 implementations were hampered by the explicit specification of immediacy or non-immediacy of all standard words. POSTPONE allowed de-specification of immediacy or non-immediacy for all but a few Forth words whose behavior must be STATE-independent.

One type 3 implementation, Charles Moore's cmForth, has both compiling and interpreting versions of many Forth words. At the present, this appears to be a common approach for type 3 implementations. The Committee felt that this implementation approach must be allowed. Consequently, it is possible that words without interpretation semantics can be found only during compilation, and other words may exist in two versions: a compiling version and an interpreting version. Hence the values returned by FIND may depend on STATE, and ' and ['] may be unable to find words without interpretation semantics.

A.6.1.1561 FM/MOD

By introducing the requirement for floored division, Forth-83 produced much controversy and concern on the part of those who preferred the more common practice followed in other languages of implementing division according to the behavior of the host CPU, which is most often symmetric (rounded toward zero). In attempting to find a compromise position, this Standard provides primitives for both common varieties, floored and symmetric (see SM/REM). FM/MOD is the floored version.

The Technical Committee considered providing two complete sets of explicitly named division operators, and declined to do so on the grounds that this would unduly enlarge and complicate the Standard. Instead, implementors may define the normal division words in terms of either FM/MOD or SM/REM providing they document their choice. People wishing to have explicitly named sets of operators are encouraged to do so. FM/MOD may be used, for example, to define:

: /_MOD ( n1 n2 -- n3 n4) >R S>D R> FM/MOD ;

: /_  ( n1 n2 -- n3)  /_MOD SWAP DROP ;

: _MOD ( n1 n2 -- n3)   /_MOD DROP ;

: */_MOD ( n1 n2 n3 -- n4 n5)  >R M* R> FM/MOD ;

: */_  ( n1 n2 n3 -- n4 )   */_MOD SWAP DROP ;

A.6.1.1700 IF

Typical use:

	: X ... test IF ... THEN ... ;

or

	: X ... test IF ... ELSE ... THEN ... ;

A.6.1.1710 IMMEDIATE

Typical use: : X ... ; IMMEDIATE

A.6.1.1720 INVERT

The word NOT was originally provided in Forth as a flag operator to make control structures readable. Under its intended usage the following two definitions would produce identical results:

: ONE  ( flag -- )
    IF ." true" ELSE ." false" THEN ;

: TWO ( flag -- )
    NOT IF ." false" ELSE ." true" THEN ;

This was common usage prior to the Forth-83 Standard which redefined NOT as a cell-wide one's-complement operation, functionally equivalent to the phrase -1 XOR. At the same time, the data type manipulated by this word was changed from a flag to a cell-wide collection of bits and the standard value for true was changed from 1 (rightmost bit only set) to -1 (all bits set). As these definitions of TRUE and NOT were incompatible with their previous definitions, many Forth users continue to rely on the old definitions. Hence both versions are in common use.

Therefore, usage of NOT cannot be standardized at this time. The two traditional meanings of NOT - that of negating the sense of a flag and that of doing a one's complement operation - are made available by 0= and INVERT, respectively.

A.6.1.1730 J

J may only be used with a nested DO...LOOP, DO...+LOOP, ?DO...LOOP, or ?DO...+LOOP, for example, in the form:

	: X ... DO ... DO ... J ... LOOP ... +LOOP ... ;

A.6.1.1760 LEAVE

Note that LEAVE immediately exits the loop. No words following LEAVE within the loop will be executed. Typical use:

	: X ... DO ... IF ... LEAVE THEN ... LOOP ... ;

A.6.1.1780 LITERAL

Typical use: : X ... [ x ] LITERAL ... ;

A.6.1.1800 LOOP

Typical use:

	: X ... limit first DO ... LOOP ... ;

or

	: X ... limit first ?DO ... LOOP ... ;

A.6.1.1810 M*

This word is a useful early step in calculation, going to extra precision conveniently. It has been in use since the Forth systems of the early 1970's.

A.6.1.1900 MOVE

CMOVE and CMOVE> are the primary move operators in Forth-83. They specify a behavior for moving that implies propagation if the move is suitably invoked. In some hardware, this specific behavior cannot be achieved using the best move instruction. Further, CMOVE and CMOVE> move characters; ANS Forth needs a move instruction capable of dealing with address units. Thus MOVE has been defined and added to the Core word set, and CMOVE and CMOVE> have been moved to the String word set.

A.6.1.2033 POSTPONE

Typical use:

: ENDIF  POSTPONE THEN ;  IMMEDIATE

: X  ... IF ... ENDIF ... ;

POSTPONE replaces most of the functionality of COMPILE and [COMPILE]. COMPILE and [COMPILE] are used for the same purpose: postpone the compilation behavior of the next word in the parse area. COMPILE was designed to be applied to non-immediate words and [COMPILE] to immediate words. This burdens the programmer with needing to know which words in a system are immediate. Consequently, Forth standards have had to specify the immediacy or non-immediacy of all words covered by the Standard. This unnecessarily constrains implementors.

A second problem with COMPILE is that some programmers have come to expect and exploit a particular implementation, namely:

	:  COMPILE  R>  DUP  @  ,  CELL+  >R  ;

This implementation will not work on native code Forth systems. In a native code Forth using inline code expansion and peephole optimization, the size of the object code produced varies; this information is difficult to communicate to a dumb COMPILE. A smart (i.e., immediate) COMPILE would not have this problem, but this was forbidden in previous standards.

For these reasons, COMPILE has not been included in the Standard and [COMPILE] has been moved in favor of POSTPONE. Additional discussion can be found in Hayes, J.R., Postpone, Proceedings of the 1989 Rochester Forth Conference.

A.6.1.2120 RECURSE

Typical use: : X ... RECURSE ... ;

This is Forth's recursion operator; in some implementations it is called MYSELF. The usual example is the coding of the factorial function.

: FACTORIAL ( +n1 -- +n2)
    DUP 2 < IF  DROP 1 EXIT  THEN
    DUP 1-  RECURSE *
;

n2 = n1(n1-1)(n1-2)...(2)(1), the product of n1 with all positive integers less than itself (as a special case, zero factorial equals one). While beloved of computer scientists, recursion makes unusually heavy use of both stacks and should therefore be used with caution. See alternate definition in A.6.1.2140 REPEAT.

A.6.1.2140 REPEAT

Typical use:

: FACTORIAL ( +n1 -- +n2)
    DUP 2 < IF  DROP 1 EXIT  THEN
    DUP
    BEGIN DUP 2 > WHILE
        1-  SWAP OVER *  SWAP
    REPEAT  DROP
;

A.6.1.2165 S"

Typical use: : X ... S" ccc" ... ;

This word is found in many systems under the name " (quote). However, current practice is almost evenly divided on the use of ", with many systems using the execution semantics given here, while others return the address of a counted string. We attempt here to satisfy both camps by providing two words, S" and the Core Extension word C" so that users may have whichever behavior they expect with a simple renaming operation.

A.6.1.2214 SM/REM

See the previous discussion of division under FM/MOD. SM/REM is the symmetric-division primitive, which allows programs to define the following symmetric-division operators:

: /-REM  ( n1 n2 -- n3 n4 )  >R  S>D  R> SM/REM ;

: /-  (  n1 n2 -- n3 )  /-REM SWAP DROP ;

: -REM  ( n1 n2 -- n3 )  /-REM DROP ;

: */-REM  (  n1 n2 n3 -- n4 n5 )  >R  M*  R> SM/REM ;

: */-  ( n1 n2 n3 -- n4 )  */-REM SWAP DROP ;

A.6.1.2216 SOURCE

SOURCE simplifies the process of directly accessing the input buffer by hiding the differences between its location for different input sources. This also gives implementors more flexibility in their implementation of buffering mechanisms for different input sources. The committee moved away from an input buffer specification consisting of a collection of individual variables, declaring TIB and #TIB obsolescent.

SOURCE in this form exists in F83, POLYFORTH, LMI's Forths and others. In conventional systems it is equivalent to the phrase

	BLK @  IF BLK @ BLOCK 1024  ELSE TIB #TIB @ THEN

A.6.1.2250 STATE

Although EVALUATE, LOAD, INCLUDE-FILE, and INCLUDED are not listed as words which alter STATE, the text interpreted by any one of these words could include one or more words which explicitly alter STATE. EVALUATE, LOAD, INCLUDE-FILE, and INCLUDED do not in themselves alter STATE.

STATE does not nest with text interpreter nesting. For example, the code sequence:

	: FOO  S" ]" EVALUATE ;       FOO

will leave the system in compilation state. Similarly, after LOADing a block containing ], the system will be in compilation state.

Note that ] does not affect the parse area and that the only effect that : has on the parse area is to parse a word. This entitles a program to use these words to set the state with known side-effects on the parse area. For example:

: NOP  : POSTPONE ; IMMEDIATE ;

NOP ALIGN    NOP ALIGNED

Some non-ANS Forth compliant systems have ] invoke a compiler loop in addition to setting STATE. Such a system would inappropriately attempt to compile the second use of NOP.

Also note that nothing in the Standard prevents a program from finding the execution tokens of ] or [ and using these to affect STATE. These facts suggest that implementations of ] will do nothing but set STATE and a single interpreter/compiler loop will monitor STATE.

A.6.1.2270 THEN

Typical use:

	: X ... test IF ... THEN ... ;

or

	: X ... test IF ... ELSE ... THEN ... ;

A.6.1.2380 UNLOOP

Typical use:

: X  ...

   limit first DO

       ... test IF ... UNLOOP EXIT THEN ...

   LOOP
   ...
;

UNLOOP allows the use of EXIT within the context of DO ... LOOP and related do-loop constructs. UNLOOP as a function has been called UNDO. UNLOOP is more indicative of the action: nothing gets undone -- we simply stop doing it.

A.6.1.2390 UNTIL

Typical use: : X ... BEGIN ... test UNTIL ... ;

A.6.1.2410 VARIABLE

Typical use: ... VARIABLE XYZ ...

A.6.1.2430 WHILE

Typical use: : X ... BEGIN ... test WHILE ... REPEAT ... ;

A.6.1.2450 WORD

Typical use: char WORD ccc<char>

A.6.1.2500 [

Typical use: : X ... [ 4321 ] LITERAL ... ;

A.6.1.2510 [']

Typical use: : X ... ['] name ... ;

See: A.6.1.1550 FIND.

A.6.1.2520 [CHAR]

Typical use: : X ... [CHAR] ccc ... ;

A.6.1.2540 ]

Typical use: : X ... [ 1234 ] LITERAL ... ;

Table of Contents
Next Section