CP/M

home *** CD-ROM | disk | FTP | other *** search

/ CP/M / CPM_CDROM.iso / beehive / cpmforth / forthdoc.arc / FORTH-83.TXT < prev next >

Wrap

Text File | 1980-01-01 | 62KB | 1,410 lines

+-----------------------------------------------------+ | The following glossary has been extracted from the | | Forth-83 Standard. It gives the description and | | operation of words required in a Forth-83 Standard | | System. Though all care has been taken, it is | | possible that errors may have resulted during | | transcription. Full copies of the Forth-83 Standard | | may be obtained from the Forth Interest Group, P.O. | | Box 8231, San Jose, CA 95155 USA. | +-----------------------------------------------------+ FORTH-83 STANDARD A PUBLICATION OF THE FORTH STANDARDS TEAM AUGUST 1983 COPYRIGHT (c) 1983 FORTH STANDARDS TEAM Permission is hereby granted to reproduce this document in whole or in part provided that such reproductions refer to the fact that the copied material is subject to copyright by the FORTH Standards Team. No changes or modifications may be made to the copied material unless it is clearly indicated that such changes were not incorporated in the original copyrighted work. The existence of a FORTH Standard does not in any respect preclude anyone, whether the individual has approved this Standard or not, from implementing, marketing, purchasing or using products, processes, or procedures not conforming to the Standard. FORTH Standards are subject to periodic review and users are cautioned to obtain the latest editions. FORTH STANDARDS TEAM P.O. BOX 4545 MOUNTAIN VIEW, CA 94040 USA 1. FOREWORD FORTH is an integrated programming approach and computer language. FORTH was invented by Mr. Charles Moore specifically to increase programmer productivity in the development of computer related applications without sacrificing machine efficiency. FORTH is a layered environment containing the elements of a computer language as well as those of an operating system and a machine monitor. This extensible, layered environment provides for highly interactive program development and testing. In the interests of transportability of application software written in FORTH, standardization efforts began in the mid-1970's by the European FORTH User's Group (EFUG). This effort resulted in the FORTH-77 Standard. As the language continued to evolve, an interim FORTH-78 Standard was published by the FORTH Standards Team. Following FORTH Standards Team meetings in 1979 the FORTH-79 Standard was published in 1980. FORTH's extensibility allows the language to be expanded and adapted to special needs and different hardware systems. A programmer or vendor may choose to strictly adhere with the standard, but the choice to deviate is acknowledged as beneficial and sometimes necessary. 2. PURPOSE The purpose of the standard is to allow transportability of FORTH- 83 Standard Programs in source form among FORTH-83 Standard Systems. A standard program shall execute equivalently on all standard systems. 3. SCOPE This standard shall apply to any FORTH-83 Standard Program executing on any FORTH-83 Standard System, providing sufficient computer resources (memory, mass storage) are available. 9. USAGE 9.1 Word Names and Word Definitions A Standard Program may reference only the definitions of the Required Word Set and Standard Extensions and definitions which are subsequently defined in terms of these words. Furthermore, a Standard Program must use the standard words as required by any conventions of this Standard. Equivalent execution must result from Standard Programs. The implementation of a Standard System may use words and techniques outside the scope of the Standard, provided that no program running on that system is required to use words outside the Standard for normal operation. If a Standard System or Standard Program redefines Standard definitions within the FORTH vocabulary, these definitions must comply with the Standard. 9.5 Terminal Input and Output 9.5.1 KEY A Standard System must receive all valid ASCII characters. Each KEY receives one valid ASCII character, with more-significant bits environmentally dependent and might not be zero. KEY must receive as many bits as are obtainable. A Standard Program without environmental dependencies may only use the least significant 7-bit ASCII character received by KEY. For example: KEY 127 AND 9.5.2 EXPECT Control characters may be processed to allow system dependent editing of the characters prior to receipt. Therefore, a Standard Program may not anticipate that control characters can be received. 9.5.3 EMIT Because of the potential non-transportable action by terminal devices of control characters, the use of ASCII control characters is an environmental dependency. Each EMIT deals with only one ASCII character. The ASCII character occupies the least- significant 7 bits; the more-significant bits may be environmentally dependent. Using the more-significant bits when other than zero is an environmentally dependent usage. EMIT must display as many bits as can be sent. 9.5.4 TYPE Because of the potential non-transportable action by terminal devices of control characters, the use of ASCII control characters is an environmental dependency. 11. GLOSSARY NOTATION 11.1 Order The glossary definitions are listed in ASCII alphabetical order. 11.2 Capitalization Word names are capitalized throughout this Standard. 11.3 Stack Notation The stack parameters input to and output from a definition are described using the notation: before -- after before stack parameters before execution after stack parameters after execution In this notation, the top of the stack is to the right. Words may also be shown in context when appropriate. Unless otherwise noted, all stack notation describes execution time. If it applies at compile time, the line is followed by (compiling). 11.4 Attributes Capitalized symbols indicate attributes of the defined words: C The word may only be used during compilation of a colon definition. I Indicates that the word is IMMEDIATE and will execute during compilation, unless special action is taken. M This word has potential multiprogramming impact. U A user variable. 11.5 Serial Numbers When a substantive alteration to a word's definition is made or when a new word is added, the serial number will be the last two digits of the year of the Standard in which such change was made (i.e., "83"). When such change is made within a Working Draft, the number will be suffixed with the character identifying the draft (i.e., "83A"). 11.6 Pronunciation The natural language pronunciation of word names is given in double quotes (") where it differs from English pronunciation. 11.7 Stack Parameters Unless otherwise stated, all reference to numbers apply to 16- bit signed integers. The implied range of values is shown as (from..to). The content of an address is shown by double parentheses, particularly for the contents of variables, i.e., BASE ((2..72)). The following are the stack parameter abbreviations and types of numbers used throughout the glossary. These abbreviations may be suffixed with a digit to differentiate multiple parameters of the same type. Stack Number Type Range in Decimal Minimum Abbrv. Field flag boolean 0=false, else=true 16 true boolean -1 (as a result) 16 false boolean 0 b bit (0..1) 1 char character (0..127) 7 8b 8 arbitrary bits (byte) not applicable 8 16b 16 arbitrary bits not applicable 16 n number (weighted bits) (-32768..32767) 16 +n positive number (0..32767) 16 u unsigned number (0..65535) 16 w unspecified weighted (-32767..65535) 16 number (n or u) addr address (same as u) (0..65535) 16 32b 32 arbitrary bits not applicable 32 d double number (-2147,483,648..2147,483,647) 32 +d positive double number (0..2147,483,647) 32 ud unsigned double number (0..4294,967,295) 32 wd unspecified weighted (-2147,483,648..4294,967,295) 32 double number (d or ud) sys 0, 1, or more system not applicable na dependent stack entries Any other symbol refers to an arbitrary signed 16-bit integer in the range (-32,768..32,767), unless otherwise noted. Because of the use of two's complement arithmetic, the signed 16-bit number (n) -1 has the same bit representation as the unsigned number (u) 65,535. Both of these numbers are within the set of unspecified weighted numbers (w). 11.8 Input Text <name> An arbitrary FORTH word accepted from the input stream. This notation refers to text from the input stream, not to values on the data stack. ccc A sequence of arbitrary characters accepted from the input stream until the first occurrence of the specified delimiting character. The delimiter is accepted from the input stream, but is not one of the characters ccc and is therefore not otherwise processed. This notation refers to text from the input stream, not to values on the data stack. Unless noted otherwise, the number of characters accepted may be from 0 to 255. 12. REQUIRED WORD SET 12.2 The Required Word Set Glossary ! 16b addr -- 79 "store" 16b is stored at addr. # +d1 -- +d2 79 "sharp" The remainder of +d1 divided by the value of BASE is converted to an ASCII character and appended to the output string toward lower memory addresses. +d2 is the quotient and is maintained for further processing. Typically used between <# and #> . #> 32b -- addr +n 79 "sharp-greater" Pictured numeric output conversion is ended dropping 32b. addr is the address of the resulting output string. +n is the number of characters in the output string. addr and +n together are suitable for TYPE . #S +d -- 0 0 79 "sharp-s" +d is converted appending each resultant character into the pictured numeric output string until the quotient (see: # ) is zero. A single zero is added to the output string if the number was initially zero. Typically used between <# and #>. #TIB -- addr U,83 "number-t-i-b" The address of a variable containing the number of bytes in the text input buffer. #TIB is accessed by WORD when BLK is zero. ((0..capacity of TIB)) ' -- addr M,83 "tick" Used in the form: ' <name> addr is the compilation address of <name>. An error condition exists if <name> is not found in the currently active search order. ( -- I,M,83 "paren" Used in the form: ( ccc) The characters ccc, delimited by ) (closing parenthesis), are considered comments. Comments are not otherwise processed. The blank following ( is not part of the ccc. ( may be freely used while interpreting or compiling. The number of characters in ccc may be from zero to the number of characters remaining in the input stream up to the closing parenthesis. * w1 w2 -- w3 79 "times" w3 is the least significant 16 bits of the arithmetic product of w1 times w2. */ n1 n2 n3 -- n4 83 "times-divide" n1 is first multiplied by n2 producing an intermediate 32-bit result. n4 is the floor of the quotient of the intermediate 32-bit result divided by the divisor n3. The product of n1 times n2 is maintained as an intermediate 32-bit result for greater precision than the otherwise equivalent sequence: n1 n2 * n3 / . An error condition results if the divisor is zero or if the quotient falls outside of the range (-32768 ..32767). */MOD n1 n2 n3 -- n4 n5 83 "times-divide-mod" n1 is first multiplied by n2 producing an intermediate 32-bit result. n4 is the remainder and n5 is the floor of the quotient of the intermediate 32-bit result divided by the divisor n3. A 32-bit intermediate product is used as for */ . n4 has the same sign as n3 or is zero. An error condition results if the divisor is zero or if the quotient falls out- side of the range (-32768..32767). + w1 w2 -- w3 79 "plus" w3 is the arithmetic sum of w1 plus w2. +! w1 addr -- 79 "plus-store" w1 is added to the w value at addr using the convention for +. This sum replaces the original value at addr. +LOOP n -- C,I,83 "plus-loop" sys -- (compiling) n is added to the loop index. If the new index was incremented across the boundary between limit-1 and limit then the loop is terminated and loop control parameters are discarded. When the loop is not terminated, execution continues to just after the corresponding DO . sys is balanced with its corresponding DO. See: DO , 16b -- 79 "comma" Allot space for 16b then store 16b at HERE 2- - w1 w2 -- w3 79 "minus" w3 is the result of subtracting w2 from w1. -TRAILING addr +n1 -- addr +n2 79 "dash-trailing" The character count +n1 of a text string beginning at addr is adjusted to exclude trailing spaces. If +n1 is zero, then +n2 is also zero. If the entire string consists of spaces, then +n2 is zero. . n -- M,79 "dot" The absolute value of n is displayed in a free field format with a leading minus sign if n is negative. ." -- C,I,83 "dot-quote" -- (compiling) Used in the form: ." ccc" Later execution will display the characters ccc up to but not including the delimiting " (close-quote). The blank following ." is not part of ccc. .( -- I,M,83 "dot-paren" -- (compiling) Used in the form: .( ccc) The characters ccc up to but not including the delimiting ) (closing parenthesis) are displayed. The blank following .( is not part of ccc. / n1 n2 -- n3 83 "divide" n3 is the floor of the quotient of n1 divided by the divisor n2. An error condition results if the divisor is zero or if the quotient falls outside of the range (-32768..32767). /MOD n1 n2 -- n3 n4 83 "divide-mod" n3 is the remainder and n4 the floor of the quotient of n1 divided by the divisor n2. n3 has the same sign as n2 or is zero. An error condition results if the divisor is zero or if the quotient falls outside of the range (-32768..32767). 0< n -- flag 83 "zero-less" flag is true if n is less than zero (negative) 0= w -- flag 83 "zero-equals" flag is true if w is zero. 0> n -- flag 83 "zero-greater" flag is true if n is greater than zero. 1+ w1 -- w2 79 "one-plus" w2 is the result of adding one to w1 according to the operation of + . 1- w1 -- w2 79 "one-minus" w2 is the result of subtracting one from w1 according to the operation of - . 2+ w1 -- w2 79 "two-plus" w2 is the result of adding two to w1 according to the operation of + . 2- w1 -- w2 79 "two-minus" w2 is the result of subtracting two from w1 according to the operation of - . 2/ n1 -- n2 83 "two-divide" n2 is the result of arithmetically shifting n1 right one bit. The sign is included in the shift and remains unchanged. : -- sys M,79 "colon" A defining word executed in the form: : <name> ... ; Create a word definition for <name> in the compilation vocabulary and set compilation state. The search order is changed so that the first vocabulary in the search order is replaced by the compilation vocabulary. The compilation vocabulary is unchanged. The text from the input stream is subsequently compiled. <name> is called a "colon definition". The newly created word definition for <name> cannot be found in the dictionary until the corresponding ; or ;code is successfully processed. An error condition exists if a word is not found and cannot be converted to a number or if, during compilation from mass storage, the input stream is exhausted before encountering ; or ;CODE . sys is balanced with its corresponding ; . ; -- C,I,79 "semi-colon" sys -- (compiling) Stops compilation of a colon definition, allows the <name> of this colon definition to be found in the dictionary, sets interpret state and compiles EXIT (or a system dependent word which performs an equivalent function). sys is balanced with its corresponding : . See: EXIT < n1 n2 -- flag 83 "less-than" flag is true if n1 is less than n2. -32768 32767 < must return true. -32768 0 < must return true. <# -- 79 "less-sharp" Initialize pictured numeric output conversion. The words # #> #S <# HOLD SIGN can be used to specify the conversion of a double number into an ASCII text string stored in right-to-left order. = w1 w2 -- flag 83 "equals" flag is true if w1 is equal to w2. > n1 n2 -- flag 83 "greater-than" flag is true if n1 is greater than n2. -32768 32767 > must return false -32768 0 > must return false >BODY addr1 -- addr2 83 "to-body" addr2 is the parameter field address corresponding to the compilation address addr1. >IN -- addr U,79 "to-in" The address of a variable which contains the present character offset within the input stream ((0..the number of characters in the input stream)). See: WORD >R 16b -- C,79 "to-r" Transfers 16b to the return stack. ?DUP 16b -- 16b 16b 79 "question-dupe" or 0 -- 0 Duplicate 16b if it is non-zero. @ addr -- 16b 79 "fetch" 16b is the value at addr. ABORT 79 Clears the data stack and performs the function of QUIT . No message is displayed. ABORT" flag -- C,I,83 "abort-quote" -- (compiling) Used in the form: flag ABORT" ccc" When later executed, if flag is true the characters ccc, delimited by " (close-quote), are displayed and then a system dependent error abort sequence, including the function of ABORT, is performed. If flag is false, the flag is dropped and execution continues. The blank following ABORT" is not part of ccc. ABS n -- u 79 "absolute" u is the absolute value of n. If n is -32,768 then u is the same value. ALLOT w -- 79 Allocates w bytes in the dictionary. The address of the next available dictionary location is updated accordingly. AND 16b1 16b2 -- 16b3 79 16b3 is the bit-by-bit logical 'and' of 16b1 with 16b2. BASE -- addr U,83 The address of a variable containing the current numeric conversion radix. ((2..72)) BEGIN -- C,I,79 -- sys (compiling) Used in the form: BEGIN ... flag UNTIL or BEGIN ... flag WHILE ... REPEAT BEGIN marks the start of a word sequence for repetitive execution. A BEGIN-UNTIL loop will be repeated until flag is true. A BEGIN-WHILE-REPEAT loop will be repeated until flag is false. The words after UNTIL or REPEAT will be executed when either loop is finished. sys is balanced with its corresponding UNTIL or WHILE . BLK -- addr U,79 "b-l-k" The address of a variable containing the number of the mass storage block being interpreted as the input stream. If the value of BLK is zero the input stream is taken from the text input buffer. ((0..the number of blocks available -1)) See: TIB BLOCK u -- addr M,83 addr is the address of the assigned buffer of the first byte of block u. If the block occupying that buffer is not block u and has been UPDATEed it is transferred to mass storage before assigning that buffer. If block u is not already in memory, it is transferred from mass storage into an assigned block buffer. A block may not be assigned to more than one buffer. If u is not an available block number, an error condition exists. Only data within the last buffer referenced by BLOCK or BUFFER is valid. The contents of a block buffer must not be changed unless the change may be transferred to mass storage. BUFFER u -- addr M,83 Assigns a block buffer to block u. addr is the address of the first byte of the block within its buffer. This function is fully specified by the definition for BLOCK except that if the block is not already in memory it might not be transferred from mass storage. The contents of the block buffer assigned to block u by BUFFER are unspecified. C! 16b addr -- 79 "c-store" The least-significant 8 bits of 16b are stored into the byte at addr. C@ addr -- 8b 79 "c-fetch" 8b is the contents of the byte at addr. CMOVE addr1 addr2 u -- 83 "c-move" Move u bytes beginning at address addr1 to addr2. The byte at addr1 is moved first, proceeding toward high memory. If u is zero nothing is moved. CMOVE> addr1 addr2 u -- 83 "c-move-up" Move u bytes at address addr1 to addr2. The move begins by moving the byte at (addr1 plus u minus 1) to (addr2 plus u minus 1) and proceeds to successively lower addresses for u bytes. If u is zero nothing is moved. (Useful for sliding a string towards higher addresses). COMPILE -- C,83 Typically used in the form: : <name> ... COMPILE <namex> ... ; When <name> is executed, the compilation address compiled for <name> is compiled and not executed. <name> is typically immediate and <namex> is typically not immediate. CONSTANT 16b -- M,83 A defining word used in the form: 16b CONSTANT <name> Creates a dictionary entry for <name> so that when <name> is later executed, 16b will be left on the stack. CONVERT +d1 addr1 -- +d2 addr2 79 +d2 is the result of converting the characters within the text beginning at addr1+1 into digits, using the value of BASE, and accumulating each into +d1 after multiplying +d1 by the value of BASE . Conversion continues until an unconvertible character is encountered. addr2 is the location of the first unconvertible character. COUNT addr1 -- addr2 +n 79 addr2 is addr1 and +n is the length of the counted string at addr1. The byte at addr1 contains the byte count +n. Range of +n is (0..255). CR -- M,79 "c-r" Displays a carriage-return and line-feed or equivalent operation. CREATE -- M,79 A defining word executed in the form: CREATE <name> Creates a dictionary entry for <name>. After <name> is created, the next available dictionary location is the first byte of <name>'s parameter field. When <name> is subsequently executed, the address of the first byte of <name>'s parameter field is left on the stack. CREATE does not allocate space in <name>'s parameter field. D+ wd1 wd2 -- wd3 79 "d-plus" wd3 is the arithmetic sum of wd1 plus wd2. D< d1 d2 -- flag 83 "d-less-than" flag is true if d1 is less than d2 according to the operation of < except extended to 32 bits. DECIMAL -- 79 Set the input-output conversion base to ten. DEFINITIONS -- 79 The compilation vocabulary is changed to be the same as the first vocabulary in the search order. DEPTH -- +n 79 +n is the number of 16-bit values contained in the data stack before +n was placed on the stack. DNEGATE d1 -- d2 79 "d-negate" d2 is the two's complement of d1. DO w1 w2 -- C,I,83 -- sys (compiling) Used in the form: DO ... LOOP or DO ... +LOOP Begins a loop which terminates based on control parameters. The loop index begins at w2, and terminates based on the limit w1. See LOOP and +LOOP for details on how the loop is terminated. The loop is always executed at least once. For example: w DUP DO ... LOOP executes 65536 times. sys is balanced with its corresponding LOOP or +LOOP . An error condition exists if insufficient space is available for at least three nesting levels. DOES> -- addr C,I,83 "does" -- (compiling) Defines the execution-time action of a word created by a high- level defining word. Used in the form: : <namex> ... <create> ... DOES> ... ; and then <namex> <name> where <create> is CREATE or any user defined word which executes CREATE . Marks the termination of the defining part of the defining word <namex> and then begins the definition of the execution- time action for words that will later be defined by <namex>. When <name> is later executed, the address of <name>'s parameter field is placed on the stack and then the sequence of words between DOES> and ; are executed. DROP 16b -- 79 16b is removed from the stack. DUP 16b -- 16b 16b 79 "dupe" Duplicate 16b. ELSE -- C,I,79 sys1 -- sys2 (compiling) Used in the form: flag IF ... ELSE ... THEN ELSE executes after the true part following IF . ELSE forces execution to continue at just after THEN . sys1 is balanced with its corresponding IF . sys2 is balanced with its corresponding THEN . See: IF THEN EMIT 16b -- M,83 The least-significant 7-bit ASCII character is displayed. See: "9.5.3 EMIT" EXECUTE addr -- 79 The word definition indicated by addr is executed. An error condition exists if addr is not a compilation address. EXIT -- C,79 Compiled within a colon definition such that when executed, that colon definition returns control to the definition that passed control to it by returning control to the return point on the top of the return stack. An error condition exists if the top of the return stack does not contain a valid return point. May not be used within a do-loop. See: ; EXPECT addr +n -- M,83 Receive characters and store each in memory. The transfer begins at addr proceeding towards higher addresses one byte per character until either a "return" is received or until +n characters have been transferred. No more than +n characters will be stored. The "return" is not stored into memory. No characters are received or transferred if +n is zero. All characters actually received and stored into memory will be displayed, with the "return" displaying as a space. See: SPAN "9.5.2 EXPECT" FILL addr u 8b -- 83 u bytes of memory beginning at addr are set to 8b. No action is taken if u is zero. FIND addr1 -- addr2 n 83 addr1 is the address of a counted string. The string contains a word name to be located in the currently active search order. If the word is not found, addr2 is the string address addr1, and n is zero. If the word is found, addr2 is the compilation address and n is set to one of two non-zero values. If the word found has an immediate attribute, n is set to one. If the word is non-immediate, n is set to minus one (true). FLUSH -- M,83 Performs the function of SAVE-BUFFERS then unassigns all block buffers. (This may be useful for mounting or changing mass storage media). FORGET -- M,83 Used in the form: FORGET <name> If <name> is found in the compilation vocabulary, delete <name> from the dictionary and all words added to the dictionary after <name> regardless of their vocabulary. Failure to find <name> is an error condition. An error condition also exists if the compilation vocabulary is deleted. FORTH -- 83 The name of the primary vocabulary. Execution replaces the first vocabulary in the search order with FORTH . FORTH is initially the compilation vocabulary and the first vocabulary in the search order. New definitions become part of the FORTH vocabulary until a different compilation vocabulary is established. See: VOCABULARY FORTH-83 -- 83 Assures that a FORTH-83 Standard System is available, otherwise an error condition exists. HERE -- addr 79 The address of the next available dictionary location. HOLD char -- 79 char is inserted into a pictured numeric output string. Typically used between <# and #> . I -- w C,79 w is a copy of the loop index. May only be used in the form: DO ... I ... LOOP or DO ... I ... +LOOP IF flag -- C,I,79 -- sys (compiling) Used in the form: flag IF ... ELSE ... THEN or flag IF ... THEN If flag is true, the words following IF are executed and the words following ELSE until just after THEN are skipped. The ELSE part is optional. If flag is false, words from IF through ELSE, or from IF through THEN (when no ELSE is used), are skipped. sys is balanced its corresponding ELSE or THEN . IMMEDIATE -- 79 Marks the most recently created dictionary entry as a word which will be executed when encountered during compilation rather than compiled. J -- w C,79 w is a copy of the index of the next outer loop. May only be used within a nested DO-LOOP or DO-+LOOP in the form, for example: DO ... DO ... J ... LOOP ... +LOOP KEY -- 16b M,83 The least-significant 7 bits of 16b is the next ASCII character received. All valid ASCII characters can be received. Control characters are not processed by the system for any editing purpose. Characters received by KEY will not be displayed. See: "9.5.1 KEY" LEAVE -- C,I,83 -- (compiling) Transfers execution to just beyond the next LOOP or +LOOP . The loop is terminated and loop control parameters are discarded. May only be used in the form: DO ... LEAVE ... LOOP or DO ... LEAVE ... +LOOP LEAVE may appear within other control structures which are nested within the do-loop structure. More than one LEAVE may appear within a do-loop. LITERAL -- 16b C,I,79 16b -- (compiling) Typically used in the form: [ 16b ] LITERAL Compiles a system dependent operation so that when later executed, 16b will be left on the stack. LOAD u -- M,79 The contents of >IN and BLK, which locate the current input stream, are saved. The input stream is then redirected to the beginning of screen u by setting >IN to zero and BLK to u. The screen is then interpreted. If interpretation from screen u is not terminated explicitly it will be terminated when the input stream is exhausted and then the contents of >IN and BLK will be restored. An error condition exists if u is zero. See: >IN BLK BLOCK LOOP -- C,I,83 sys -- (compiling) Increments the DO-LOOP index by one. If the new index was incremented across the boundary between limit-1 and limit the loop is terminated and loop control parameters are discarded. When the loop is not terminated, execution continues to just after the corresponding DO . sys is balanced with its corre- sponding DO . See: DO MAX n1 n2 -- n3 79 "max" n3 is the greater of n1 and n2 according to the operation of >. MIN n1 n2 -- n3 79 "min" n3 is the lesser of n1 and n2 according to the operation of <. MOD n1 n2 -- n3 83 n3 is the remainder after dividing n1 by the divisor n2. n3 has the same sign as n2 or is zero. An error condition results if the divisor is zero or if the quotient falls outside of the range (-32768..32767). NEGATE n1 -- n2 79 n2 is the two's complement of n1, i.e., the difference of zero less n1. NOT 16b1 -- 16b2 83 16b2 is the one's complement of 16b1. OR 16b1 16b2 -- 16b3 79 16b3 is the bit-by-bit inclusive-or of 16b1 with 16b2. OVER 16b1 16b2 -- 16b1 16b2 16b3 79 16b3 is a copy of 16b1. PAD -- addr 83 The lower address of a scratch area used to hold data for intermediate processing. The address or contents of PAD may change and the data lost if the address of the next available dictionary location is changed. The minimum capacity of PAD is 84 characters. PICK +n -- 16b 83 16b is a copy of the +nth stack value, not counting +n itself. (0..the number of elements on stack-1) 0 PICK is equivalent to DUP 1 PICK is equivalent to OVER QUIT -- 79 Clears the return stack, sets the interpret state, accepts new input from the current input device, and begins text interpretation. No message is displayed. R> -- 16b C,79 "r-from" 16b is removed from the return stack and transferred to the data stack. R@ -- 16b C,79 "r-fetch" 16b is a copy of the top of the return stack. REPEAT -- C,I,79 sys -- (compiling) Used in the form: BEGIN ... flag WHILE ... REPEAT At execution time, REPEAT continues execution to just after the corresponding BEGIN. sys is balanced with its corre- sponding WHILE . See: BEGIN ROLL +n -- 83 The +nth stack value, not counting +n itself is first removed and then transferred to the top of the stack, moving the remaining values into the vacant position. (0..the number of elements on the stack-1) 2 ROLL is equivalent to ROT 0 ROLL is a null operation ROT 16b1 16b2 16b3 -- 16b2 16b3 16b1 79 "rote" The top three stack entries are rotated, bringing the deepest to the top. SAVE-BUFFERS -- M,79 "save-buffers" The contents of all block buffers marked as UPDATEed are written to their corresponding mass storage blocks. All buffers are marked as no longer being modified, but may remain assigned. SIGN n -- 83 If n is negative, an ASCII "-" (minus sign) is appended to the pictured numeric output string. Typically used between <# and #> . SPACE -- M,79 Displays an ASCII space. SPACES +n -- M,79 Displays +n ASCII spaces. Nothing is displayed if +n is zero. SPAN -- addr U,83 The address of a variable containing the count of characters actually received and stored by the last execution of EXPECT. See: EXPECT STATE -- addr U,79 The address of a variable containing the compilation state. A non-zero content indicates compilation is occurring, but the value itself is system dependent. A Standard Program may not modify this variable. SWAP 16b1 16b2 -- 16b2 16b1 79 The top two stack entries are exchanged. THEN -- C,I,79 sys -- (compiling) Used in the form: flag IF ... ELSE ... THEN or flag IF ... THEN THEN is the point where execution continues after ELSE, or IF when no ELSE is present. sys is balanced with its corresponding IF or ELSE . See: IF ELSE TIB -- addr 83 "t-i-b" The address of the text input buffer. This buffer is used to hold characters when the input stream is coming from the current input device. The minimum capacity of TIB is 80 characters. TYPE addr +n -- M,79 +n characters are displayed from memory beginning with the character at addr and continuing through consecutive addresses. Nothing is displayed if +n is zero. See: "9.5.4 TYPE" U. u -- M,79 "u-dot" u is displayed as an unsigned number in free-field format. U< u1 u2 -- flag 83 "u-less-than" flag is true if u1 is less than u2. UM* u1 u2 -- ud 83 "u-m-times" ud is the unsigned product of u1 times u2. All values and arithmetic are unsigned. UM/MOD ud u1 -- u2 u3 83 "u-m-divide-mod" u2 is the remainder and u3 is the floor of the quotient after dividing ud by the divisor u1. All values and arithmetic are unsigned. An error condition results if the divisor is zero or if the quotient lies outside the range (0..65535). UNTIL flag -- C,I,79 sys -- (compiling Used in the form: BEGIN ... flag UNTIL Marks the end of a BEGIN-UNTIL loop which will terminate based on flag. If flag is true, the loop is terminated. If flag is false, execution continues to just after the corresponding BEGIN. sys is balanced with its corresponding BEGIN. See: BEGIN UPDATE -- 79 The currently valid block buffer is marked as modified. Blocks marked as modified will subsequently be automatically transferred to mass storage should its memory buffer be needed for storage of a different block or upon execution of FLUSH or SAVE-BUFFERS . VARIABLE -- M,79 A defining word executed in the form: VARIABLE <name> A dictionary entry for <name> is created and two bytes are ALLOTed in its parameter field. This parameter field is to be used for contents of the variable. The application is responsible for initializing the contents of the variable which it creates. When <name> is later executed, the address of its parameter field is placed on the stack. VOCABULARY -- M,83 A defining word executed in the form: VOCABULARY <name> A dictionary entry for <name> is created which specifies a new ordered list of word definitions. Subsequent execution of <name> replaces the first vocabulary in the search order with <name>. When <name> becomes the compilation vocabulary new definitions will be appended to <name>'s list. See: DEFINITIONS WHILE flag -- C,I,79 sys1 -- sys2 (compiling) Used in the form: BEGIN ... flag WHILE ... REPEAT Selects conditional execution based on flag. When flag is true, execution continues to just after the WHILE through to the REPEAT which then continues execution back to just after the BEGIN. When the flag is false, execution continues to just after the REPEAT, exiting the control structure. sys1 is balanced with its corresponding BEGIN. sys2 is balanced with its corresponding REPEAT . See: BEGIN WORD char -- addr M,83 Generates a counted string by non-destructively accepting characters from the input stream until the delimiting character char is encountered or the input stream is exhausted. Leading delimiters are ignored. The entire character string is stored in memory beginning at addr as a sequence of bytes. The string is followed by a blank which is not included in the count. The first byte of the string is the number of characters (0..255). If the string is longer than 255 characters, the count is unspecified. If the input stream is already exhausted as WORD is called, then a zero length character string will result. If the delimiter is not found the value of >IN is the size of the input stream. If the delimiter is found >IN is adjusted to indicate the offset to the character following the delimiter. #TIB is unmodified. The counted string returned by WORD may reside in the "free" dictionary area at HERE or above. Note that the text interpreter may also use this area. XOR 16b1 16b2 -- 16b3 79 "x-or" 16b3 is the bit-by-bit exclusive-or of 16b1 with 16b2. [ -- I,79 "left-bracket" -- (compiling) Sets interpret state. The text from the input stream is subsequently interpreted. For typical usage see LITERAL . See: ] ['] -- addr C,I,M,83 "bracket-tick" -- (compiling) Used in the form: ['] <name> Compiles the compilation address addr of <name> as a literal. When the colon definition is later executed addr is left on the stack. An error condition exists if <name> is not found in the currently active search order. See: LITERAL [COMPILE] -- C,I,M,79 "bracket-compile" -- (compiling) Used in the form: [COMPILE] <name> Forces compilation of the following word <name>. This allows compilation of an immediate word when it would otherwise have been executed. ] -- 79 "right-bracket" Sets the compilation state. The text from the input stream is subsequently compiled. For typical usage see LITERAL . See: [ 13. DOUBLE NUMBER EXTENSION WORD SET 13.2 The Double Number Extension Word Set Glossary 2! 32b addr -- 79 "two-store" 32 b is stored at the addr. 2@ addr -- 32b 79 "two-fetch" 32b is the value at addr. 2CONSTANT 32b -- M,83 "two-constant" A defining word executed in the form: 32b 2CONSTANT <name> creates a dictionary entry for <name> so that when <name> is later executed, 32b will be left on the stack. 2DROP 32b -- 79 "two-drop" 32b is removed from the stack. 2DUP 32b -- 32b 32b 79 "two-dupe" Duplicate 32b. 2OVER 32b1 32b2 -- 32b1 32b2 32b3 79 "two-over" 32b3 is a copy of 32b1. 2ROT 32b1 32b2 32b3 -- 32b2 32b3 32b1 79 "two-rote" The top three double numbers on the stack are rotated, bringing the third double number to the top of the stack. 2SWAP 32b1 32b2 -- 32b2 32b1 79 "two-swap" The top two double numbers are exchanged. 2VARIABLE -- M,79 "two-variable" A defining word executed in the form: 2VARIABLE <name> A dictionary entry for <name> is created and four bytes are ALLOTed in its parameter field. This parameter field is to be used for contents of the variable. The application is responsible for initializing the contents of the variable which it creates. When <name> is later executed, the address of its parameter field is placed on the stack. See: VARIABLE D+ wd1 wd2 -- wd3 79 See the complete definition in the Required Word Set. D- wd1 wd2 -- wd3 79 "d-minus" wd3 is the result of subtracting wd2 from wd1. D. d -- M,79 "d-dot" The absolute value of d is displayed in a free field format. A leading negative sign is displayed if d is negative. D.R d +n -- M,83 "d-dot-r" d is converted using the value of BASE and then displayed right aligned in a field +n characters wide. A leading minus sign is displayed if d is negative. If the number of characters required to display d is greater than +n, an error condition exists. D0= wd -- flag 83 "d-zero-equals" flag is true if wd is zero. D2/ d1 -- d2 83 "d-two-divide" d2 is the result of d1 arithmetically shifted right one bit. The sign is included in the shift and remains unchanged. D< d1 d2 -- flag 83 "d-less" See the complete definition in the Required Word Set. D= wd1 wd2 -- flag 83 "d-equal" flag is true if wd1 equals wd2. DABS d -- ud 79 "d-absolute" ud is the absolute value of d. If d is -2147483648 then ud is the same value. DMAX d1 d2 -- d3 79 "d-max" d3 is the greater of d1 and d2. DMIN d1 d2 -- d3 79 "d-min" d3 is the lesser of d1 and d2. DNEGATE d1 -- d2 79 See the complete definition in the Required Word Set. DU< ud1 ud2 -- flag 83 "d-u-less" flag is true if ud1 is less than ud2. Both numbers are unsigned. 14. ASSEMBLER EXTENSION WORD SET 14.2 Assembler Extension Word Set Usage Because of the system dependent nature of machine language programming, a Standard Program cannot use CODE or ;CODE . 14.3 Assembler Extension Word Set Glossary ;CODE -- C,I,79 "semi-colon-code" sys1 -- sys2 (compiling) Used in the form: : <namex> ... <create> ... ;CODE ... END-CODE Stops compilation, terminates the defining word <namex> and executes ASSEMBLER. When <namex> is executed in the form: <namex> <name> to define the new <name>, the execution address of <name> will contain the address of the code sequence following ;CODE in <namex>. Execution of any <name> will cause this machine code sequence to be executed. sys1 is balanced with its corresponding : . sys2 is balanced with its corresponding END-CODE . See: CODE DOES> ASSEMBLER -- sys M,83 Execution replaces the first vocabulary in the search order with the ASSEMBLER vocabulary. See: VOCABULARY CODE -- sys M,83 A defining word executed in the form: CODE <name> ... END-CODE Creates a dictionary entry for <name> to be defined by a following sequence of assembly language words. Words thus defined are called code definitions. This newly created word definition for <name> cannot be found in the dictionary until the corresponding END-CODE is successfully processed (see: END-CODE). Executes ASSEMBLER. sys is balanced with its corresponding END-CODE . END-CODE sys -- 79 "end-code" Terminates a code definition and allows the <name> of the corresponding code definition to be found in the dictionary. sys is balanced with its corresponding CODE or ;CODE . 15. THE SYSTEM EXTENSION WORD SET 15.2 System Extension Word Set Usage After BRANCH or ?BRANCH is compiled, >MARK or <RESOLVE is executed. The addr left by >MARK is passed to >RESOLVE . The addr left by <MARK is passed to <RESOLVE . For example: : IF COMPILE ?BRANCH >MARK ; IMMEDIATE : THEN >RESOLVE ; IMMEDIATE 15.3 The System Extension Word Set Glossary <MARK -- addr C,83 "backward-mark" Used at the destination of a backward branch. addr is typically only used by <RESOLVE to compile a branch address. <RESOLVE addr -- C,83 "backward-resolve" Used at the source of a backward branch after either BRANCH or ?BRANCH . Compiles a branch address using addr as the destination address. >MARK -- addr C,83 "forward-mark" Used at the source of a forward branch. Typically used after either BRANCH or ?BRANCH. Compiles space in the dictionary for a branch address which will later be resolved by >RESOLVE. >RESOLVE addr -- C,83 "forward-resolve" Used at the destination of a forward branch. Calculates the branch address (to the current location in the dictionary) using addr and places this branch address into the space left by >MARK . ?BRANCH flag -- C,83 "question-branch" When used in the form: COMPILE ?BRANCH a conditional branch operation is compiled. See BRANCH for further details. When executed, if flag is false the branch is performed as with BRANCH. When flag is true execution continues at the compilation address immediately following the branch address. BRANCH -- C,83 When used in the form: COMPILE BRANCH an unconditional branch operation is compiled. A branch address must be compiled immediately following this compilation address. The branch address is typically generated by following BRANCH with <RESOLVE or >MARK . CONTEXT -- addr U,79 The address of a variable which determines the dictionary search order. CURRENT -- addr U,79 The address of a variable specifying the vocabulary in which new word definitions are appended. 16. CONTROLLED REFERENCE WORDS The Controlled Reference Words are word definitions which, although not required, cannot be present with a non-standard definition in the vocabulary FORTH of a Standard System. These words have present usage and/or are candidates for future standardization. --> -- I,M,79 "next-block" -- (compiling) Continue interpretation on the next sequential block. May be used within a colon definition that crosses a block boundary. .R n +n -- M,83 "dot-r" n is converted using BASE and then displayed right aligned in a field +n characters wide. A leading minus sign is displayed if n is negative. If the number of characters required to display n is greater than +n, an error condition exists. 2* w1 -- w2 83 "two-times" w2 is the result of shifting w1 left one bit. A zero is shifted into the vacated bit position. BL -- 32 79 "b-l" Leave the ASCII character value for space (decimal 32). BLANK addr u -- 83 u bytes of memory beginning at addr are set to the ASCII character value for space. No action is taken if u is zero. C, 16b -- 83 "c-comma" ALLOT one byte then store the least-significant 8 bits of 16b at HERE 1- . DUMP addr u -- M,79 List the contents of u addresses at addr. Each line of values may be preceded by the address of the first value. EDITOR -- 83 Execution replaces the first vocabulary in the search order with the EDITOR vocabulary. See: VOCABULARY EMPTY-BUFFERS -- M,79 "empty-buffers" Unassigns all block buffers. UPDATEed blocks are not written to mass storage. See: BLOCK END flag -- C,I,79 sys -- (compiling) A synonym for UNTIL. ERASE addr u -- 79 u bytes of memory beginning at addr are set to zero. No action is taken if u is zero. HEX -- 79 Set the numeric input-output conversion base to sixteen. INTERPRET -- M,83 Begin text interpretation at the character indexed by the contents of >IN relative to the block number contained in BLK, continuing until the input stream is exhausted. If BLK contains zero, interpret characters from the text input buffer. K -- w C,83 w is a copy of the index of the second outer loop. May only be used within a nested DO-LOOP or DO-+LOOP in the form, for example: DO ... DO ... DO ... K ... LOOP ... +LOOP ... LOOP LIST u -- M,79 The contents of screen u are displayed. SCR is set to u. See: BLOCK OCTAL -- 83 Set the numeric input-output conversion base to eight. OFFSET -- addr U,83 The address of a variable that contains the offset added to the block number on the stack by BLOCK or BUFFER to determine the actual physical block number. QUERY -- M,83 Characters are received and transferred into the memory area addressed by TIB . The transfer terminates when either a "return" is received or the number of characters transferred reaches the size of the area addressed by TIB . The values of >IN and BLK are set to zero and the value of #TIB is set to the value of SPAN . WORD may be used to accept text from this buffer. See: EXPECT RECURSE -- C,I,83 -- (compiling) Compile the compilation address of the definition being compiled to cause the definition to later be executed recursively. SCR -- addr U,79 "s-c-r" The address of a variable containing the number of the screen most recently LISTed. SP@ -- addr 79 "s-p-fetch" addr is the address of the top of the stack just before SP@ was executed. THRU u1 u2 -- M,83 Load consecutively the blocks from u1 through u2. U.R u +n -- M,83 "u-dot-r" u is converted using the value of BASE and the displayed as an unsigned number right aligned in a field +n characters wide. If the number of characters required to display u is greater than +n, an error condition exists.