Source: dxforth -------THE FORTH-77 GLOSSARY--------------FST780314------------- T h i s d e s c r i p t i o n o f t h e F O R T H s t a n d a r d a n d e x t e n d e d v o c a b u l a r i e s w a s e d i t e d b y t h e S t a n d a r d s T e a m o f t h e F O R T H U S E R S G R O U P . (Subject to amendments and approval planned for September 1978.) Each glossary entry is annotated in its top right corner, to indicate its level of standardization (no mark implying it is standard) as follows: T Tape systems only. X Part of an extension to FORTH-77 The words are presented in the order of their numerically sorted identifier codes. The first line of each entry shows a symbolic description of the action of the words: Symbols indicating which parameters are to be placed on the stack before executing the word, 3 dashes (---) indicating execution, the any parameters left on the stack by the word. In this notation, the top of the stack is to the right. If the place of the word in the input string is not completely obvious, it is shown explicitly. If no dashes are shown the word does not affect the stack. Symbols are used as follows: b Block number c 7-bit ASCII character code. f Flag : 0=False, non-zero=True. All words which return a flag return 0=False or 1=True. m n p q r 16-bit integers. nnnn pppp The name of a word. ssss A string of characters. Immediately following the name of a word, certain characters may appear within parentheses. These denote some special action or characteristics: C The word may be used only within a colon-definition A following digit (C0 or C2) indicates the number of memory cells uses when the word is compiled if other than one. A following + or - sign indicates that the word either pushes a value onto the stack or removes one from the stack during compilation. (This action is not related to its action during execution and may be implementation dependent.) E The word may not normally be compiled within a colon-definition. P The word has its precedence bit set ; it is executed directly, even when encountered during compile mode. U The word applies to a user variable (one for which in multi-user systems each user has his own copy.) Unless stated otherwise, all references to numbers apply to 16- bit integers, with the most significant bit as the sign bit and the negative in two's complement form. Similarly, all arithmetic will be assumed to be 16-bit signed integer arithmetic with er- ror conditions and overflow indication unspecified. FORTH-77 AND 77X The 1977 Standard definitions and Extensions. ! m p --- Store m at address p. ' (P) ' nnnn --- p Leave the address of the parameter field of nnnn . A com- piler directive, ' is executed when encountered in a colon definition: the address of the following word's parameter field is found immediately (at compilation) and stored in the dictionary (after the address of LIT) as a literal to be placed on the stack at execution time. Within a colon definition, ' nnnn is identical to: LIT [ ' nnnn , ] ( (P) ( ssss) Ignore a comment that will be delimited by a right paren- thesis. * m n --- p 16-bit signed integer multiply. p=m*n */ m n p --- q Leave q=m*n/p . Retention of an intermediate 31-bit pro- duct permits greater accuracy than the otherwise equiva- lent sequence: m n * p / + n m --- q 16-bit integer addition. q=m+n +! m p --- Add integer m to value at address p. +BLOCK m --- b X Leave the sum of m plus the number of the block currently being interpreted. +LOOP (C) m --- Add m to the loop index. Exit from the loop is made when the resultant index reaches or passes the limit, if m is greater than zero; or when the index is less than (passes) the limit, if m is less than zero. m may be a variable. , m --- Store m into the next available dictionary cell, advancing the dictionary pointer. - m n --- q 16-bit integer subtraction q=m-n --> (P) (Pronounced "nextblock") Continue interpretation with the next block (Equivalent to 1 +BLOCK CONTINUED). . m --- Print the value on the stack as an integer, converted according to the current number base. ." (P) ." ssss" X Transmit a message delimited by " to the selected output device. The maximum number of characters may be an instal- lation dependent value. / m n --- q 16-bit signed integer divide, m/n. The quotient is trunca- ted ; any remainder is lost. /MOD m n --- r q 16-bit integer divide, m/n. The quotient is left on top of the stack, the remainder beneath. The remainder has the sign of the dividend, m. 0< m --- f Leave a true flag if m is negative 0= m --- f True if m is zero. 0> m --- f True if m positive and non-zero. 1+ m --- q q=q+1 1+! p --- X Add 1 to the contents of location p. 1- m --- q q=m-1 X 1-! p --- X Subtract 1 from the contents of location p. 2* m --- q q=m*2 X 2/ m --- q q=m/2 X 2DROP m n --- X Drop the top two values from the stack ( to drop a double- precision number for example ). 2DUP m n --- m n m n X Duplicate the top two values on the stack. 2SWAP m n p q --- p q m n X Swap two pairs of values (e.g. double-precision numbers). : : nnnn Create a dictionary entry defining nnnn as equivalent to the following sequence of Forth Words. Set compilation mode. (Extension: Set the context vocabulary equivalent to the current vocabulary.) ; (C,P) Terminate a colon-definition and stop compilation. ;: (C,P) Terminate a defining word nnnn, which can be subsequently executed to define a new word pppp. Subsequent use of pppp will cause the words between ;: and ; to be executed with the contents of the first parameter of pppp on the stack. ;CODE (C,P) Stop compilation and terminate a new defining word nnnn. (Extension: Set the content vocabulary to Assembler.) When nnnn is executed to define a new word pppp , the execution address of pppp will point to the assembler sequence follo wing the ;CODE of nnnn. Subsequent use of pppp will cause this machine-code sequence to be executed. A previously defined defining word must be included in the sequence of Forth Words preceding ;CODE. ;S (E) Stop interpretation of a symbolic block. < m n --- f True if m m n --- f True if m unequal to n X > m n --- f True if m>n >= m n --- f True if m>n or m=n X >R (C) m --- Push m onto the top of the return stack. See R> . ? p --- Print the value contained at address p in free format, according to the current base. @ p --- q Leave the contents q of memory location p. ABORT Enter the abort sequence, clear the stacks and return con- trol to the terminal, possibly printing an abort message. ABS m --- q Leave the absolute value of a number. AND m n --- q Bitwise logical AND of m and n. ARRAY m ARRAY nnnn --- X Define an array named nnnn and allocate m+1 uninitialed locations onto the dictionary. The sequence i nnnn will leave the address of the i-th cell on the stack. The in- dex should be in the range 0 <= i <= m, but no check is made for values exceeding this range. ASSEMBLER (P) X Switch the context pointer so that dictionary searches will begin at the Assembler Vocabulary. The Assembler Vo- cabulary is always chained to the current vocabulary. B! m p --- Store the least significant 8 bits of m at byte-address p B@ p --- q Return the 8-bit byte q found at byte-address p. BASE (U) --- p A variable containing the current number conversion base. BEGIN (CO+,P) BEGIN ... WHILE ... REPEAT or BEGIN ... END Mark the start of a sequence of words to be executed repe- titively. If ... WHILE ... REPEAT is used the loop will be repeated as long as the top stack value encountered by WHILE is TRUE (REPEAT merely effects an unconditional jump back to BEGIN); when WHILE sees a FALSE value (0) on the stack it causes an immediate exit out of the loop. In case the sequence can be written such that the test for comple- tion is at the end ... END can be used conveniently to end the loop on a TRUE value or to go back to BEGIN on FALSE. Both WHILE and END drop the value they test. BELL X Activate terminal bell or noisemaker as appropriate to de- vice. BLK (U) --- p A variable containing the number of the block being listed or edited. BLOCK b --- p Leave the first address of Block b. If the block is not already in memory, it is transferred from disk or tape into whichever core buffer has been least recently acces- sed. If the block occupying that buffer has been updated, it is rewritten on disk or tape before Block b is read into the buffer. BMOVE p q n --- Move the n bytes starting at byte-address p into the n byte-cells starting at byte-address q. The contents of p is moved first ( OCTAL 40 2001 ! 2001 2002 100 BMOVE would put blanks into byte locations 2001 through 2100 ). BUFFER b --- p X Obtain a core buffer for Block b, leaving the first buffer cell address. The block is not read from disk, and is automatically marked as updated. BYTE p --- q Return the byte address of the first byte in memory cell p CASE (C2+,P) m n --- (m) X m n CASE (action for m=n) ELSE (drop) THEN If m equals n, drop both m and n and execute the words di- rectly following CASE until the next ELSE or THEN ; other- wise, drop n but leave m and execute the words after ELSE (or THEN if no ELSE is used). The selection of one of many cases can be done by: m n1 CASE (action for m=n1) ELSE n2 CASE (action for m=n2) ELSE n3 CASE (action for m=n3) ELSE (otherwise action) THEN THEN THEN CELL p --- q Return the word address of the memory cell holding byte p. CHAIN CHAIN vvvv X Connect the current vocabulary to all definitions that might be entered into vocabulary vvvv in the future. The current vocabulary may not be FORTH or ASSEMBLER. Any given vocabulary may only be chained once, but may be the object of any number of chainings. For example, every user-defined vocabulary may include the sequence, CHAIN FORTH. CODE CODE nnnn Create a dictionary entry defining nnnn as equivalent to the following sequence of assembler code. (Extension: set the context vocabulary to Assembler.) COM m --- q X Complement each bit of m (Leave one's complement). CONSTANT m CONSTANT nnnn --- Create a word which when executed pushes m onto the stack Since the "constant" m may be modified by the sequence: q ' nnnn ! it is oftentimes advantageous to define a var- iable as a constant, particularly if it is accessed more often than it is modified. CONTEXT (U) --- p X A variable containing a pointer to the vocabulary in which dictonary searches are to begin. See CURRENT . CONTINUED (E) b --- X Continue interpretation at Block b. (The preferred imple- mentation in multi-buffer systems is such that the block buffer currently being accessed will be used for storage of block b, leaving other buffers unaffected.) COUNT p --- m n Leave byte-address m and byte-count n of a message string string beginning at word address p. It is presumed that the first byte at p contains the byte-count and that the actual message starts with the second byte in location p. Typically, COUNT is followed by WRITE or TYPE. CR Transmit carriage return/line feed codes to the selected output device. CUR --- p T A variable containing the physical record number before which the tape is currently positioned. REWIND sets CUR=1. CURRENT (U) --- p X A variable containing a pointer to the vocabulary into which new words are to be entered. CURRENT @ @ leaves the link address of the next entry to be defined. DECIMAL Set the numeric conversion base to decimal mode. DEFINITIONS (vvvv) DEFINITIONS X Set the current vocabulary (into which new definitions are placed) to vocabulary vvvv (the context vocabulary). vvvv need not be specified explicitly DISCARD X A null-definition intended for use as a standard REMEMBER word, as some version of DISCARD can always be found in the dictionary. DLIST (E) m --- X List the dictionary, starting at the entry beginning at location m. DO (C) m n --- Begin a loop, to be terminated by LOOP or +LOOP. The loop index begins at n, and may be modified at the end of the loop by any positive or negative value. The loop is ter- minated when an incremented index reaches or exceeds m, or when a decremented index becomes less than m. Within a loop, the word I will place the current index value on the stack. Within nested loops, the word I always returns the index of the innermost loop that is being executed, while J returns the index of the next outer loop, and K returns the index of the second outer loop. DP+! n --- Add the signed value n to the dictionary pointer (DP). As DP may be an internal register rather than a VARIABLE, it is accessible only through HERE and DP+! . DPL (U) --- p A variable containing a value indicating the number of di- gits following the fractional point in number output. A negative value of DPL indicates that no dot is to appear. DROP m --- Drop the top value from the stack. DUMP m n --- Dump the contents of n memory cells starting at address m. Normally, both addresses and contents are shown in the current base. DUP m --- m m Duplicate the top value on the stack. EDIT b --- X The Editor vocabulary is loaded, if not already in the dictionary, becoming the context vocabulary. Block b is listed. EDITOR (P) X The name of the Editor Vocabulary. If that vocabulary is loaded, EDITOR establishes it as the context vocabulary, thereby making its definitions accessible. EDOC X End of code ; terminate a code definition. Restore the context vocabulary pointer back to the current vocabulary. ELSE (C2,P) Procede the false part of an IF..ELSE..THEN conditional. It may be ommitted if the false part is empty. END (C2-,P) f --- Mark the end of a BEGIN-END loop. If f is true the loop is terminated. If f is false, control returns to the first word after the corresponding BEGIN. ERASE-CORE Mark all block buffers as empty. Updated blocks are not flushed. Contents of buffers are subsequently undefined. FIND FIND nnnn --- p Return the compilation address of nnnn (i.e. the address that would normally be compiled when nnnn is encountered in a colon-definition) if that name can be found in the dictionary ; zero otherwise. FLD --- p A variable containing the field length reserved for a num- ber during output conversion. FLUSH Write all blocks that have been flagged as "updated" to disk or tape. Return when output is completed. FORGET FORGET nnnn Delete nnnn and all dictionary entries following it. (Extension: Though nnnn must be in the context vocabulary to be found, the words that follow it are deleted no mat- ter what vocabulary they belong to. FORTH (P) The name of the primary vocabulary. Execution makes FORTH the context vocabulary. Since FORTH cannot be chained to anything, it becomes the only vocabulary that is searched for dictionary entries. Unless additional user vocabularies are defined, new user definitions normally become part of the Forth Vocabulary. HERE (U) --- p Return the address of the next available dictionary loca- tion. HEX Switch the numeric conversion base to hexadecimal. I (C) --- m Return the index of an innermost DO-loop. IF (C2+,P) f IF (true part) ELSE (false part) THEN --- f IF (true part) THEN --- IF is the first word of a conditional. If f is true, the words following IF are executed and the words following ELSE are not executed. The ELSE part of the conditional is optional. If f is false, words between IF and ELSE, or between IF and THEN when no ELSE is used, are skipped. IF- ELSE-THEN conditionals may be nested. IFEND (E) X Terminate a conditional interpretation sequence begun by IFTRUE. IFTRUE (E) f IFTRUE...OTHERWISE...IFEND --- X Unlike IF-ELSE-THEN, these conditionals may be employed during interpretation. In conjunction with the words [ and ] they may be used within a colon-definition to control compilation, although they are not to be compiled. These words cannot be nested. IMMEDIATE Mark the most recently made dictionary entry such that when encountered at compile time it will be executed rather than compiled. J (C) --- m X Within a nested DO-loop, return the index of the next outer loop. K (C) --- m X Within a nested DO-loop, return the index of the second outer loop. LAST --- p A variable containing the compilation address of the most recently made dictionary entry, which may not yet be a complete or valid entry. LEAVE (C) X Force termination of a DO-loop at the next opportunity by setting the loop limit equal to the current value of the index. The index itself remains unchanged, and execution proceeds normally until LOOP or +LOOP is encountered. LINE m --- p Leave the word address of the beginning of line m for the block whose number is contained at BLK. (For editing pur- poses a block is divided in 16 lines, numbered 0-15, of 64 characters.) LINELOAD m b --- X Begin interpreting at line m of Block b. (0 =< m =< 15) LIST b --- List the ASCII symbolic contents of Block b on the selec- ted output device. LIT (C) LIT m Automatically compiled before each literal encountered in a colon-definition. Execution of LIT causes the contents of the next dictionary cell to be pushed onto the stack. NOTE: On the CDC 6400, LIT is implemented so as to access the next 15-bit parcel of a 60-bit word. This implementa- tion is recommended for other machines of large word size LOAD b --- Begin interpretation of Block b. The block must terminate its own interpretation with ;S , --> (nextblock) or CON- TINUED LOOP (C) Increment the DO-loop index by one, terminating the loop if the new index is equal to or greater than the limit. MAP0 --- p T Return the address of the first location in the tape map. MAX m n --- q Leave the greater of two numbers. MIN m n --- q Leave the lesser of two numbers. MINUS m --- -m Negate a number by taking its two's complement. MOD m n --- r Leave the remainder of m/n, with the same sign as m. MOVE p q n --- Move the contents of n memory cells beginning at address p into n cells beginning at address q. The contents of p is moved first ; overlapping of data can occur. ( 0 10 ! 10 11 4 MOVE clears locations 10 through 15 ). MS n --- X Delay for approximately n milliseconds. NAND m n --- q X Logical AND followed by COMplement. NOR m n --- q X Logical OR followed by COMplement. NOT m --- f X Equivalent to 0= NUMBER Convert a character string left in the dictionary buffer by WORD as a number, returning the result in regis 6nn internal temporary locations, or on the stack. The appea- rance of characters that cannot be properly interpreted will cause an error exit appropriate to the installation. O. m --- Convert and output in octal mode, unsigned, and preceded by a blank. BASE is unchanged. Format specifications are observed. OCTAL Set the number-conversion base to octal. OR m n --- q Bitwise logical inclusive OR of m and n. OTHERWISE (C) X An interpreter-level conditional word . See IFTRUE. OVER m n --- m n m Push the second stack value. PAGE X Clears the terminal screen or performs an action suitable to the output device currently active. PICK n --- q X Return the nth value on the stack, not counting n itself. (2 PICK is equivalent to OVER) R> (C) --- n X Pop the top value from the return stack and push it onto the user stack. See >R. READ-MAP T Read to the next file mark on tape, constructing a table in memory (the map) relating physical block positions to logical block numbers. The tape should normally be rewound to its load point before executing READ-MAP. REMEMBER REMEMBER nnnn X Define a word nnnn which, when executed, will cause nnnn and all subsequently defined words to be deleted from the dictionary. The word nnnn may be compiled into and execu- ted from a colon-definition. The sequence DISCARD REMEMBER DISCARD provides a standardized preface to any group of transient blocks. REPEAT (C2-,P) Effect an unconditional jump back to the beginning of a BEGIN ... WHILE ... REPEAT loop. See BEGIN. REWIND T Rewind the tape to its load point, setting CUR=1. ROLL u(n) u(n-1)...u(1) n --- u(n-1)...u(1) u(n) X Extract the nth value from the stack, leaving it on top and moving the remaining values into the vacated position (3 ROLL is equivalent to ROT ; 1 ROLL is a null operation 0 ROLL is undefined.) ROT m n p --- n p m Rotate the top three values on the stack, bringing the deepest to the top. SET m p SET nnnn --- X Define a word nnnn which, when executed, will cause the value m to be stored at address p. SP@ --- p Return the address of the top of the stack. (E.g. 1 2 SP@ @ . . . would type 2 2 1). SPACE Output a space character to the selected output device. SPACES n --- Output n spaces to the selected output device. No action taken for n < 1. SWAP m n --- n m Exchange the top two stack values. THEN (CO-,P) Terminate an ..IF...ELSE...THEN conditional sequence. TYPE m n --- Send a string of n characters starting at byte address m, to the terminal. U< m n --- f X U<= X U> Unsigned comparisons, in which the entire (16-bit) X U>= values are regarded as positive integers and compared. X UPDATE Flag the most-recently referenced block as updated. The block will subsequently be transferred automatically to disk or tape should its buffer be required for storage of a different block. See FLUSH. VARIABLE m VARIABLE nnnn --- Create a word nnnn which, when executed, will push the ad- dress of a variable (initialized to m) onto the stack. VOCABULARY (E) VOCABULARY vvvv X Define a vocabulary. Subsequent use of vvvv will make vvvv the context vocabulary. The sequence vvvv DEFINITIONS will make vvvv the current vocabulary, into which definitions are placed. WHILE (C2+,P) f WHILE --- Test the value on the stack and, if FALSE, exit out of a BEGIN ... WHILE ... REPEAT loop. See BEGIN. WRITE m n --- X Output the n characters starting at byte address m to the selected output device. WHERE X Output information about the status of Forth (E.g. after an error abort). Indicate at least the last word compiled and the last block accessed. WORD c WORD pppp --- Read the next word from the input string being interpreted until a delimiter c is found, storing the packed character string beginning at the next available dictionary location (HERE) with the character count in the first byte. XOR m n --- q X Bitwise logical exclusive OR of m and n. [ (P) X Stop compilation. The words following the left bracket in a colon-definition are executed, not compiled. ] X Resume compilation. Following words are compiled into the dictionary ^ n p --- q X Compute q as n to the power p. All are signed integers. ---------------end of THE FORTH-77 GLOSSARY---------------------