From 3de84278276ccdf4dd6aa32cf9ca4da5a24a2c3c Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 03:16:13 +0000 Subject: [PATCH] docs: the FORTH standards v4 is held to -- FORTH-79, FORTH-83, ANS Forth 1994 (#189) Captain Bob, 2026-11-14: the standard first, in the order 79, 83, ANS, then v3; the texts in the repository as references. FORTH-79 and FORTH-83 from the University of Vienna's FORTH archive (complang.tuwien.ac.at), ANS Forth's final draft (dpANS) from Taygeta, as fetched, with their sources in docs/reference/standards/README.md. Not pushed. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm --- docs/reference/standards/FORTH-79.TXT | 1998 ++++++ docs/reference/standards/FORTH83.TXT | 6139 +++++++++++++++++++ docs/reference/standards/README.md | 15 + docs/reference/standards/ans94/dpans.htm | 574 ++ docs/reference/standards/ans94/dpans1.htm | 700 +++ docs/reference/standards/ans94/dpans10.htm | 495 ++ docs/reference/standards/ans94/dpans11.htm | 1343 ++++ docs/reference/standards/ans94/dpans12.htm | 2395 ++++++++ docs/reference/standards/ans94/dpans13.htm | 606 ++ docs/reference/standards/ans94/dpans14.htm | 378 ++ docs/reference/standards/ans94/dpans15.htm | 918 +++ docs/reference/standards/ans94/dpans16.htm | 681 ++ docs/reference/standards/ans94/dpans17.htm | 372 ++ docs/reference/standards/ans94/dpans2.htm | 534 ++ docs/reference/standards/ans94/dpans3.htm | 1779 ++++++ docs/reference/standards/ans94/dpans4.htm | 370 ++ docs/reference/standards/ans94/dpans5.htm | 145 + docs/reference/standards/ans94/dpans6.htm | 5776 +++++++++++++++++ docs/reference/standards/ans94/dpans7.htm | 764 +++ docs/reference/standards/ans94/dpans8.htm | 783 +++ docs/reference/standards/ans94/dpans9.htm | 553 ++ docs/reference/standards/ans94/dpansa1.htm | 234 + docs/reference/standards/ans94/dpansa10.htm | 357 ++ docs/reference/standards/ans94/dpansa11.htm | 304 + docs/reference/standards/ans94/dpansa12.htm | 382 ++ docs/reference/standards/ans94/dpansa13.htm | 392 ++ docs/reference/standards/ans94/dpansa14.htm | 44 + docs/reference/standards/ans94/dpansa15.htm | 279 + docs/reference/standards/ans94/dpansa16.htm | 287 + docs/reference/standards/ans94/dpansa17.htm | 148 + docs/reference/standards/ans94/dpansa2.htm | 104 + docs/reference/standards/ans94/dpansa3.htm | 1434 +++++ docs/reference/standards/ans94/dpansa4.htm | 45 + docs/reference/standards/ans94/dpansa5.htm | 111 + docs/reference/standards/ans94/dpansa6.htm | 2043 ++++++ docs/reference/standards/ans94/dpansa7.htm | 89 + docs/reference/standards/ans94/dpansa8.htm | 162 + docs/reference/standards/ans94/dpansa9.htm | 292 + docs/reference/standards/ans94/dpansb.htm | 225 + docs/reference/standards/ans94/dpansc.htm | 1042 ++++ docs/reference/standards/ans94/dpansd.htm | 1155 ++++ docs/reference/standards/ans94/dpanse.htm | 631 ++ docs/reference/standards/ans94/dpansf.htm | 430 ++ 43 files changed, 37508 insertions(+) create mode 100644 docs/reference/standards/FORTH-79.TXT create mode 100644 docs/reference/standards/FORTH83.TXT create mode 100644 docs/reference/standards/README.md create mode 100644 docs/reference/standards/ans94/dpans.htm create mode 100644 docs/reference/standards/ans94/dpans1.htm create mode 100644 docs/reference/standards/ans94/dpans10.htm create mode 100644 docs/reference/standards/ans94/dpans11.htm create mode 100644 docs/reference/standards/ans94/dpans12.htm create mode 100644 docs/reference/standards/ans94/dpans13.htm create mode 100644 docs/reference/standards/ans94/dpans14.htm create mode 100644 docs/reference/standards/ans94/dpans15.htm create mode 100644 docs/reference/standards/ans94/dpans16.htm create mode 100644 docs/reference/standards/ans94/dpans17.htm create mode 100644 docs/reference/standards/ans94/dpans2.htm create mode 100644 docs/reference/standards/ans94/dpans3.htm create mode 100644 docs/reference/standards/ans94/dpans4.htm create mode 100644 docs/reference/standards/ans94/dpans5.htm create mode 100644 docs/reference/standards/ans94/dpans6.htm create mode 100644 docs/reference/standards/ans94/dpans7.htm create mode 100644 docs/reference/standards/ans94/dpans8.htm create mode 100644 docs/reference/standards/ans94/dpans9.htm create mode 100644 docs/reference/standards/ans94/dpansa1.htm create mode 100644 docs/reference/standards/ans94/dpansa10.htm create mode 100644 docs/reference/standards/ans94/dpansa11.htm create mode 100644 docs/reference/standards/ans94/dpansa12.htm create mode 100644 docs/reference/standards/ans94/dpansa13.htm create mode 100644 docs/reference/standards/ans94/dpansa14.htm create mode 100644 docs/reference/standards/ans94/dpansa15.htm create mode 100644 docs/reference/standards/ans94/dpansa16.htm create mode 100644 docs/reference/standards/ans94/dpansa17.htm create mode 100644 docs/reference/standards/ans94/dpansa2.htm create mode 100644 docs/reference/standards/ans94/dpansa3.htm create mode 100644 docs/reference/standards/ans94/dpansa4.htm create mode 100644 docs/reference/standards/ans94/dpansa5.htm create mode 100644 docs/reference/standards/ans94/dpansa6.htm create mode 100644 docs/reference/standards/ans94/dpansa7.htm create mode 100644 docs/reference/standards/ans94/dpansa8.htm create mode 100644 docs/reference/standards/ans94/dpansa9.htm create mode 100644 docs/reference/standards/ans94/dpansb.htm create mode 100644 docs/reference/standards/ans94/dpansc.htm create mode 100644 docs/reference/standards/ans94/dpansd.htm create mode 100644 docs/reference/standards/ans94/dpanse.htm create mode 100644 docs/reference/standards/ans94/dpansf.htm diff --git a/docs/reference/standards/FORTH-79.TXT b/docs/reference/standards/FORTH-79.TXT new file mode 100644 index 00000000..882ee4d8 --- /dev/null +++ b/docs/reference/standards/FORTH-79.TXT @@ -0,0 +1,1998 @@ + + FORTH-79 STANDARD + + + A PUBLICATION OF + THE FORTH STANDARDS TEAM + + + OCTOBER 1980 + + + CONTENTS + Page + 0. FOREWORD 1 + 1. PURPOSE 1 + 2. SCOPE 1 + 3. ORGANIZATION 1 + 4. DEFINITION OF TERMS 2 + 5. REFERENCES 9 + 6. REQUIREMENTS 10 + 7. COMPLIANCE AND LABELING 11 + 8. USE 12 + 9. GLOSSARY NOTATION 13 +10. REQUIRED WORD SET 15 +11. EXTENSION WORD SETS 32 + + 11.1 Double Number Word Set 32 + 11.2 Assembler Word Set 34 + +12. EXPERIMENTAL PROPOSALS 34 + + REFERENCE WORD SET + FORTH-79 HANDY REFERENCE CARD + + + + FORTH-79 STANDARD + + + A PUBLICATION OF + THE FORTH STANDARDS TEAM + + + OCTOBER 1980 + + +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. + + + 0. FOREWORD + + +The computer language FORTH was created by Mr. Charles Moore as an +extensible, multi-level environment containing elements of an +operating system, a machine monitor, and facilities for program +development and testing. + +This Standard is a direct descendant of FORTH-77, a work of the +FORTH Users Group (Europe). + + + 1. PURPOSE + + +The purpose of this FORTH Standard is to allow transportability of +standard FORTH programs in source form among standard FORTH +systems. A standard program shall execute equivalently on all +standard FORTH systems. + + + 2. SCOPE + + +This standard shall apply to any Standard FORTH program executing +on any Standard FORTH system, providing sufficient computer +resources (memory, mass storage) are available. + + + 3. ORGANIZATION + + +This standard consists of: + 1) General Text + 2) Definitions of Terms + 3) Required Word Set + 4) Extension Ward Sets + +Word sets may be subdivided for conceptual purposes by functions + Nucleus + Interpreter + Compiler + Devices + +Tradeoffs + +When conflicting choices must be made, the following order shall +guide the Standards Team. + + 1) Functional correctness + - known bounds, non-ambiguous. + 2) Portability + - repeatable results when transported among Standard + systems. + 3) Simplicity. + 4) Naming clarity + - uniformity of expression. Descriptive names are + preferred over procedural, (i.e., [COMPILE] rather + than 'C, and ALLOT rather than DP+! .) + 5) Generality. + 6) Execution speed. + 7) Memory compactness. + 8) Compilation speed. + 9) Historical continuity. + 10) Pronounceability. + 11) Teachability. + + + 4. DEFINITIONS OF TERMS + + +These definitions, when in lower case, are terms used within this +Standard. They present terms as specifically used within FORTH. + +address, byte + + An unsigned number that locates an 8-bit byte in a standard + FORTH address space over {0..65,535}. It may be a native + machine address or a representation on a virtual machine, + locating the 'addr-th' byte within the virtual byte address + space. Address arithmetic is modulo 65,536 without overflow. + +address, compilation + + The numerical value equivalent to a FORTH word definition, + which is compiled for that definition. The address + interpreter uses this value to locate the machine code + corresponding to each definition. (May also be called the + code field address.) + +address, native machine + + The natural address representation of the host computer. + +address, parameter field + + The address of the first byte of memory associated with a word + definition for the storage of compilation addresses (in a + colon-definition), numeric data and text characters. + +arithmetic + + All integer arithmetic is performed with signed 16 or 32 bit + two's complement results, unless noted. + +block + + The unit of data from mass storage, referenced by block + number. A block must contain 1024 bytes regardless of the + minimum data unit read/written from mass storage. The + translation from block number to device and physical record is + a function of the implementation. + +block buffer + + A memory area where a mass storage block is maintained. + +byte + + An assembly of 8 bits. In reference to memory, it is the + storage capacity for 8 bits. + +cell + + A 16-bit memory location. The n-th cell contains the 2n-th + and (2n+1)-th byte of the FORTH address space. The byte order + is presently unspecified. + +character + + A 7-bit number which represents a terminal character. The + ASCII character set is considered standard. When contained in + a larger field, the higher order bits are zero. + +compilation + + The action of accepting text words from the input stream and + placing corresponding compilation addresses in a new + dictionary entry. + +defining word + + A word that, when executed, creates a new dictionary entry. + The new word name is taken from the input stream. If the + input stream is exhausted before the new name is available, an + error condition exists. Common defining words are: + : CONSTANT CREATE + +definition + + See 'word definition'. + +dictionary + + A structure of word definitions in a computer memory. In + systems with a text interpreter, the dictionary entries are + organized in vocabularies to enable location by name. The + dictionary is extensible, growing toward high memory. + +equivalent execution + + For the execution of a standard program, a set of non-tine + dependent inputs will produce the same non-time dependent + outputs on any FORTH Standard System with sufficient resources + to execute the program. Only standard source code will be + transportable. + +error condition + + An exceptional condition which requires action by the system + other than the expected function. Actions may be: + + 1. ignore, and continue + 2. display a message + 3. execute a particular word + 4. interpret a block + 5. return control to the text interpreter + + A Standard System shall be provided with a tabulation of the + action taken for all specified error conditions. General + error conditions: + + 1. input stream exhausted before a required . + 2. empty stack and full stack for the text interpreter. + 3. an unknown word, not a valid number for the text + interpreter. + 4. compilation of incorrectly nested conditionals. + 5. interpretation of words restricted to compilation. + 6. FORGETing within the system to a point that removes + a word required for correct execution. + 7. insufficient space remaining in the dictionary. + +false + + A zero number represents the false condition flag. + +flag + + A number that may have two logical states, zero and non-zero. + These are named 'true' = non-zero, and 'false' = zero. + Standard word definitions leave 1 for true, 0 for false. + +glossary + + A set of word definitions given in a natural language + describing the corresponding computer execution action. + +immediate word + + A word defined to automatically execute when encountered + during compilation, which handles exception cases to the usual + compilation. See IF LITERAL ." etc. + +input stream + + A sequence of characters available to the system, for + processing by the text interpreter. The input stream + conventionally may be taken from a terminal (via the terminal + input buffer) and mass storage (via a block buffer). >IN and + BLK specify the input stream. Words using or altering >IN and + BLK are responsible for maintaining and restoring control of + the input stream. + +interpreter, address + + The (set of) word definitions which interprets (sequences of) + FORTH compilation addresses by executing the word definition + specified for each one. + +interpreter, text + + The (set of) word definitions that repeatedly accepts a word + name from the input stream, locates the corresponding + dictionary entry, and starts the address interpreter to + execute it. Text in the input stream interpreted as a number + leaves the corresponding value on the data stack. When in + the compile mode, the addresses of FORTH words are compiled + into the dictionary for later interpretation by the address + interpreter. In this case, numbers are compiled, to be placed + on the data stack when later interpreted. Numbers shall be + accepted unsigned or negatively signed, according to BASE. + +load + + The acceptance of text from a mass storage device and + execution of the dictionary definition of the words + encountered. This is the general method for compilation of + new definitions into the dictionary. + +mass storage + + Data is read from mass storage in the form of 1024 byte + blocks. This data is held in block buffers. When indicated + as UPDATEd (modified) data will be ultimately written to mass + storage. + +number + + When values exist within a larger field, the high order bits + are zero. When stored in memory the byte order of a number is + unspecified. + + type range minimum field + + bit 0..1 1 + character 0..127 7 + byte 0..255 8 + number -32,768..32,767 16 + positive number 0..32,767 16 + unsigned number O..65,535 16 + double number -2,147,483,648.. + 2,147,483,647 32 + positive double number 0..2,147,483,647 32 + unsigned double number 0..4,294,967,295 32 + + When represented on the stack, the higher 16-bits (with sign) + of a double number are most accessible. When in memory the + higher 16-bits are at the lower address. Storage extends over + four bytes toward high memory. The byte order within each 16 + -bit field is unspecified. + +output, pictured + + The use of numeric output primitives, which convert numerical + values into text strings. The operators are used in a + sequence which resembles a symbolic 'picture' of the desired + text format. Conversion proceeds from low digit to high, + from high memory to low. + +program + + A complete specification of execution to achieve a specific + function (application task) expressed in FORTH source code + form. + +return + + The means of terminating text from the input stream. + (Conventionally a null (ASCII 0) indicates end of text in the + input stream. This character is left by the 'return' key + actuation of the operator's terminal, as an absolute stopper + to text interpretation.) + +screen + + Textual data arranged for editing. By convention, a screen + consists of 16 lines (numbered 0 thru 15) of 64 characters + each. Screens usually contain program source text, but may be + used to view mass storage data. The first byte of a screen + occupies the first byte of a mass storage block, which is the + beginning point for text interpretation during a load. + +source definition + + Text consisting of word names suitable for execution by the + text interpreter. Such text is usually arranged in screens + and maintained on a mass storage device. + +stack, data + + A last in, first out list consisting of 16-bit binary values. + This stack is primarily used to hold intermediate values + during execution of word definitions. Stack values may + represent numbers, characters, addresses, boolean values, etc. + + When the name 'stack' is used, it implies the data stack. + +stack, return + + A last in, first out list which contains the machine addresses + of word definitions whose execution has not been completed by + the address interpreter. As a word definition passes control + to another definition, the return point is placed on the + return stack. + + The return stack may cautiously be used for other values, such + as loop control parameters, and for pointers for + interpretation of text. + +string + + A sequence of 8-bit bytes containing ASCII characters, located + in memory by an initial byte address and byte count. + +transportability + + This term indicates that equivalent execution results when a + program is executed on other than the system on which it was + created. See 'equivalent execution'. + +true + + A non-zero value represents the true condition flag. Any non- + zero value will be accepted by a standard word as 'true'; all + standard words return one when leaving a ' true' flag. + +user area + + An area in memory which contains the storage for user + variables. + +variables, user + + So that the words of the FORTH vocabulary may be re-entrant + (to different users), a copy of each system variable is + maintained in the user area. + +vocabulary + + An ordered list of word definitions. Vocabulary lists are an + advantage in reducing dictionary search time and in separating + different word definitions that may carry the sane name. + +word + + A sequence of characters terminated by at least one blank (or + 'return'). Words are usually obtained via the input stream, + from a terminal or mass storage device. + +word definition + + A named FORTH execution procedure compiled into the + dictionary. Its execution may be defined in terms of machine + code, as a sequence of compilation addresses or other compiled + words. If named, it nay be located by specifying this name + and the vocabulary in which it is located. + +word name + + The name of a word definition. Standard names must be + distinguished by their length and first thirty-one characters, + and may not contain an ASCII null, blank, or 'return'. + +word set + + A group of FORTH word definitions listed by common + characteristics. The standard word sets consist of: + + Required Word Set + Nucleus Words + Interpreter Words + Compiler Words + Device Words + + Extension Word Sets + 32-bit Word Set + Assembler Ward Set + + Included as reference material only: + Reference Word Set + +word set, compiler + + Words which add new procedures to the dictionary or aid + compilation by adding compilation addresses or data structures + to the dictionary. + +word set, devices + + Words which allow access to mass storage and computer + peripheral devices. + +word set, interpreter + + Words which support interpretation of text input from a + terminal or mass storage by execution of corresponding + dictionary entries, vocabularies, and terminal output. + +word set, nucleus + + The FORTH words generally defined in machine code that create + the stacks and fundamental stack operators (virtual FORTH + machine). + +word set, reference + + This set of words is provided as a reference document only, as + a set of formerly standardized words and candidate words for + standardization. + +word set, required + + The minimum words needed to compile and execute all Standard + Programs. + +word, standard + + A named FORTH procedure definition, formally reviewed and + accepted by the Standards Team. A serial number identifier + {100..999} indicates a Standard Word. A functional alteration + of a Standard Word will require assignment of a new serial + number identifier. + + The serial number identifier has no required use, other than + to correlate the definition name with its unique Standard + definition. + + + 5. REFERENCES + + +The following documents are considered to be a portion of this +Standard: + + American Standard Code for Information Interchange, + American National Standards Institute, X3.4-1968 + + Webster's Collegiate Dictionary shall be used to resolve + conflicts in spelling and English word usage. + +The following documents are noted as pertinent to the FORTH-79 +Standard, but are not part of this Standard. + + FORTH-77, FORTH Users Group, FST-780314 + FORTH-78, FORTH International Standards Team + FORTH-79, Reference Word Set + FORTH-79, Experimental Proposals + + + 6. REQUIREMENTS + + +6.1 Documentation Requirements + +Each Standard System and Standard Program shall be accompanied by a +statement of the minimum (byte) requirements for: + + 1. System dictionary space + 2. Application dictionary space + 3. Data stack + 4. Return stack + 5. Mass storage contiguous block quantity required + 6. An operator's terminal. + +Each Standard System shall be provided with a statement of the +system action upon each of the error conditions as identified in +this Standard. + +6.2 Testing Requirements + +The following host computer configuration is specified as a minimum +environment for testing against this Standard. Applications may +require different capacities. + + 1. 2000 bytes of memory for application dictionary + 2. Data stack of 64 bytes + 3. Return stack of 48 bytes + 4. Mass storage capacity of 32 blocks, numbered 0 through 31 + 5. One ASCII input/output device acting as an operator's + terminal. + + + 7. COMPLIANCE AND LABELING + + +The FORTH Standards Team hereby specifies the requirements for +labeling of systems and applications so that the conditions for +program portability may be established. + +A system may use the specified labeling if it complies with the +terms of this Standard, and meets the particular Word Set +definitions. + +A Standard Program (application) may use the specified labeling if +it utilizes the specified standard system according to this +Standard, and executes equivalently on any such system. + +FORTH Standard + +A system may be labeled 'FORTH-79 Standard' if it includes all of +the Required Word Set in either source or object form, and complies +with the text of this Standard. After executing "79-STANDARD" the +dictionary must contain all of the Required Word Set in the +vocabulary FORTH, as specified in this Standard. + +Standard Sub-set + +A system may be labeled 'FORTH-79 Standard Sub-set' if it includes +a portion of the Required Word Set, and complies with the remaining +text of this standard. However, no Required Word may be present +with a non-standard definition. + +Standard with Extensions + +A system may be labeled 'FORTH-79 Standard with Standard +Extensions)' if it comprises a FORTH-79 Standard System and one or +more Standard Extension Word Set(s). The designation would be in +the form: + 'FORTH-79 Standard with Double-Number-Standard Extensions' + + + 8. USE + + +A FORTH Standard, program may reference only the definitions of the +Required Word Set, and definitions which are subsequently defined +in terms of these words. Furthermore, a FORTH Standard program +must use the standard words as required by any conventions of this +Standard. Equivalent execution must result from Standard programs. + +The FORTH system may share the dictionary space with the user's +application, and the native addressing protocol of the host +computer is beyond the scope of this Standard. + +Therefore, in a Standard program, the user may only operate on data +which was stored by the application. No exceptions! + +A Standard Program may address: + + 1. parameter fields of variables, constants and DOES> words. + A DOES> word's parameter field may only be addressed with + respect to the address left by DOES> , itself. + + 2. dictionary space ALLOTed. + + 3. data in mass storage block buffers. (Note restriction in + BLOCK on latest buffer addressing.) + + 4. the user area and PAD. + +A Standard Program may NOT address: + + 1. directly into the data or return stacks. + + 2. into a definition's name field, link field, or code + field. + + 3. into a definition's parameter field if not stored by the + application. + +Further usage requirements are expected to be added for +transporting progran between standard systems. + +FORTH Standard definitions have a serial number assigned, in the +range 100 thru 999. Neither a Standard System nor Standard Program +may redefine these word names, within the FORTH vocabulary. + + + 9. GLOSSARY NOTATION + + +Order + + The Glossary definitions are listed in ASCII alphabetical + order. + +Stack Notation + + The first line of each entry describes the execution of the + definition: + + i.e., before -- after + + In this notation, the top of the stack is to the right. + Words may also be shown in context when appropriate. + +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. + + U A user variable. + +Capitalization + + Word names as used within the dictionary are conveniently + written in upper case characters. Within this Standard lower + case will be used when reference is made to the run-time + machine code, not directly accessible. + +Pronunciation + + The natural language pronunciation of word names is given in + double quotes ("). + +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 + curly brackets, particularly for the contents of variables, + i.e., BASE {{2..70}}. + +addr {0..65,535} + + A value representing the address of a byte, within the FORTH + standard memory space. This addressed byte may represent the + first byte of a larger data field in memory. + +byte {0..255} + + A value representing an 8 bit byte. When in a larger field, + the higher bits are zero. + +char {0..127} + + A value representing a 7 bit ASCII character code. When in a + larger field, the higher bits are zero. + +d {-2,147,483,648..2,147,483,647} + + 32 bit signed 'double' number. The most significant 16-bits, + with sign, is most accessible on the stack. + +flag + + A numerical value with two logical states; 0 = false, non- + zero = true. + +n {-32,768..32,767} + + 16 bit signed integer number. + + Any other symbol refers to an arbitrary signed 16-bit integer + in the range {-32,768..32,767}, unless otherwise noted. + +Input Text + + + + 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. If the input stream is exhausted before + encountering , an error condition exists. + + + 10. REQUIRED WORD SET + + +The words of the Required Word Set are grouped to show like +characteristics. No implementation requirements should be inferred +from this grouping. + +Nucleus Words + +! * */ */MOD + +! +loop - / +/MOD 0< 0= 0> 1+ 1- 2+ 2- < += > >R ?DUP @ ABS AND begin C! +C@ colon CMOVE constant create D+ +D< DEPTH DNEGATE do does> +DROP DUP else EXECUTE EXIT FILL I +if J LEAVE literal loop MAX MIN +MOD MOVE NEGATE NOT OR OVER PICK +R> R@ repeat ROLL ROT semicolon +SWAP then U* U/ until variable +while XOR + +(note that lower case entries refer to just the run-time code +corresponding to a compiling word.) + +Interpreter Words + +# #> #S ' ( -TRAILING . +79-STANDARD <# >IN ? ABORT BASE BLK +CONTEXT CONVERT COUNT CR CURRENT +DECIMAL EMIT EXPECT FIND FORTH HERE +HOLD KEY PAD QUERY QUIT SIGN SPACE +SPACES TYPE U. WORD + +Compiler Words + ++LOOP , ." : ; ALLOT BEGIN +COMPILE CONSTANT CREATE DEFINITIONS DO +DOES> ELSE FORGET IF IMMEDIATE +LITERAL LOOP REPEAT STATE THEN UNTIL +VARIABLE VOCABULARY WHILE [ [COMPILE] ] + +Device Words + +BLOCK BUFFER EMPTY-BUFFERS LIST +LOAD SAVE-BUFFERS SCR UPDATE + + + +! n addr -- 112 "store" + Store n at addr. + +# ud1 -- ud2 158 "sharp" + Generate from an unsigned double number d1, the next ASCII + character which is placed in an output string. Result d2 is + the quotient after division by BASE is maintained for further + processing. Used between <# and #> . + +#> d -- addr n 190 "sharp-greater" + End pictured numeric output conversion. Drop d, leaving the + text address, and character count, suitable for TYPE. + +#S ud -- 0 0 209 "sharp-s" + Convert all digits of an unsigned 32-bit number ud, adding + each to the pictured numeric output text, until remainder is + zero. A single zero is added to the output string if the + number was initially zero. Use only between <# and #>. + +' -- addr I,171 "tick" + Used in the form: + ' + If executing, leave the parameter field address of the next + word accepted from the input stream. If compiling, compile + this address as a literal; later execution will place this + value on the stack. An error condition exists if not found + after a search of the CONTEXT and FORTH vocabularies. Within + a colon-definition ' is identical to [ ' ] + LITERAL. + +( -- I,122 "paren" + Used in the form: + ( ccc) + Accept and ignore comment characters from the input stream, + until the next right parenthesis. As a word, the left + parenthesis must be followed by one blank. It may freely be + used while executing or compiling. An error condition exists + if the input stream is exhausted before the right parenthesis. + +* n1 n2 -- n3 138 "times" + Leave the arithmetic product of n1 times n2. + +*/ n1 n2 n3 -- n4 220 "times-divide" + Multiply n1 by n2, divide the result by n3 and leave the + quotient n4. n4 is rounded toward zero. The product of n1 + times n2 is maintained as an intermediate 32-bit value for + greater precision than the otherwise equivalent sequence: n1 + n2 * n3 / + +*/MOD n1 n2 n3 -- n4 n5 192 "times-divide-mod" + Multiply n1 by n2, divide the result by n3 and leave the + remainder n4 and quotient n5. A 32-bit intermediate product + is used as for */ . The remainder has the same sign as n1. + ++ n1 n2 -- n3 121 "plus" + Leave the arithmetic sum of n1 plus n2. + ++! n addr -- 157 "plus-store" + Add n to the 16-bit value at the address, by the convention + given for + . + ++LOOP n -- I,C,141 "plus-loop" + Add the signed increment n to the loop index using the + convention for +, and compare the total to the limit. Return + execution to the corresponding DO until the new index is equal + to or greater than the limit (n>0), or until the new index is + less than the limit (n<0). Upon the exiting from the loop, + discard the loop control parameters, continuing execution + ahead. Index and limit are signed integers in the range + {-32,768..32,767}. + + (Comment: It is a historical precedent that the limit for n<0 + is irregular. Further consideration of the characteristic is + unlikely.) + +, n -- 143 "comma" + Allot two bytes in the dictionary, storing n there. + +- n1 n2 -- n3 134 "minus" + Subtract n2 from n1 and leave the difference n3. + +-TRAILING addr n1 -- addr n2 148 "dash-trailing" + Adjust the character count n1 of a text string beginning at + addr to exclude trailing blanks, i.e., the characters at + addr+n2 to addr+n1-1 are blanks. An error condition exists if + n1 is negative. + +. n -- 193 "dot" + Display n converted according to BASE in a free field format + with one trailing blank. Display only a negative sign. + +." I,133 "dot-quote" + Interpreted or used in a colon definition in the form: + ." ccc" + Accept the following text from the input stream, terminated by + " (double-quote). If executing, transmit this text to the + selected output device. If compiling, compile so that later + execution will transmit the text to the selected output + device. At least 127 characters are allowed in the text. If + the input stream is exhausted before the terminating double- + quote, an error condition exists. + +/ n1 n2 -- n3 178 "divide" + Divide n1 by n2 and leave the quotient n3. n3 is rounded + toward zero. + +/MOD n1 n2 -- n3 n4 198 "divide-mod" + Divide n1 by n2 and leave the remainder n3 and quotient n4. + n3 has the same sign as n1. + +0< n -- flag 144 "zero-less" + True if n is less than zero (negative) + +0= n -- flag 180 "zero-equals" + True if n is zero. + +0> n -- flag 118 "zero-greater" + True if n is greater than zero. + +1+ n -- n+1 107 "one-plus" + Increment n by one, according to the operation of + . + +1- n -- n-1 105 "one-minus" + Decrement n by one, according to the operation of - . + +2+ n -- n+2 135 "two-plus" + Increment n by two, according to the operation of + . + +2- n -- n-1 129 "two-minus" + Decrement n by two, according to the operation of - . + +79-STANDARD 119 + Execute assuring that a FORTH-79 Standard system is available, + otherwise an error condition exists. + +: 116 "colon" + A defining word executed in the form: + : ... ; + Select the CONTEXT vocabulary to be identical to CURRENT. + Create a dictionary entry for in CURRENT, and set + compile mode. Words thus defined are called 'colon- + definitions'. The compilation addresses of subsequent words + from the input stream which are not immediate words are stored + in the dictionary to be executed when is later + executed. IMMEDIATE words are executed as encountered. + + If a word is not found after a search of the CONTEXT and FORTH + vocabularies, conversion and compilation of a literal number + is attempted, with regard to the current BASE; that failing, + an error condition exists . + +; I,C,196 "semi-colon" + Terminate a colon definition and stop compilation. If + compiling from mass storage and the input stream is exhausted + before encountering ; an error condition exists. + +< n1 n2 -- flag 139 "less-than" + True if n1 is less than n2. + + -32768 32767 < must return true. + -32768 0 < must be distinguished. + +<# 169 "less-sharp" + Initialize pictured numeric output. The words: + # #> #S <# HOLD SIGN + can be used to specify the conversion of a double-precision + number into an ASCII character string stored in right-to-left + order. + += n1 n2 -- flag 173 "equals" + True if n1 is equal to n2. + +> n1 n2 -- flag 102 "greater-than" + True if n1 is greater than n2. + +>IN -- addr U,201 "to-in" + Leave the address of a variable which contains the present + character offset within the input stream {{0..1023}} + See: WORD ( ." FIND + +>R n -- C,200 "to-r" + Transfer n to the return stack. Every >R must be balanced by + a R> in the same control structure nesting level of a colon- + definition. + +? addr -- 194 "question-mark" + Display the number at address, using the format of "." . + +?DUP n -- n ( n ) 184 "query-dupe" + Duplicate n if it is non-zero. + +@ addr -- n 199 "fetch" + Leave on the stack the number contained at addr. + +ABORT 101 + Clear the data and return stacks, setting execution mode. + Return control to the terminal. + +ABS n1 -- n1 108 "absolute" + Leave the absolute value of a number. + +ALLOT n -- 154 + Add n bytes to the parameter field of the most recently + defined word. + +AND n1 n2 -- n3 183 + Leave the bitwise logical 'and' of n1 and n2. + +BASE -- addr U,115 + Leave the address of a variable containing the current input- + output numeric conversion base. {{2..70}} + +BEGIN I,C,147 + Used in a colon-definition 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. flag is always dropped after + being tested. + +BLK -- addr U,132 "b-l-k" + Leave the address of a variable containing the number of the + mass storage block being interpreted as the input stream. If + the content is zero, the input stream is taken from the + terminal. + +BLOCK n -- addr 191 + Leave the address of the first byte in block n. If the block + is not already in memory, it is transferred from mass storage + into whichever memory buffer has been least recently accessed. + If the block occupying that buffer has been UPDATEd (i.e. + modified), it is rewritten onto mass storage before block n is + read into the buffer. n is an unsigned number. If correct + mass storage read or write is not possible, an error condition + exists. Only data within the latest block referenced by BLOCK + is valid by byte address, due to sharing of the block buffers. + +BUFFER n -- addr 130 + Obtain the next block buffer, assigning it to block n. The + block is not read from mass storage. If the previous + contents of the buffer has been marked as UPDATEd, it is + written to mass storage. If correct writing to mass storage + is not possible, an error condition exists. The address left + is the first byte within the buffer for data storage. n is an + unsigned number. + +C! n addr -- 219 "c-store" + Store the least significant 8-bits of n at addr. + +C@ addr -- byte 156 "c-fetch" + Leave on the stack the contents of the byte at addr (with + higher bits zero, in a 16-bit field). + +CMOVE addr1 addr2 n -- 153 "c-move" + Move n bytes beginning at address addr1 to addr2. The + contents of addr1 is moved first proceeding toward high + memory. If n is zero nothing is moved. + +COMPILE C,146 + When a word containing COMPILE executes, the 16-bit value + following the compilation address of COMPILE is copied + (compiled) into the dictionary. i.e., COMPILE DUP will copy + the compilation address of DUP. + COMPILE [ 0 , ] will copy zero. + +CONSTANT n -- 185 + A defining word used in the form: + n CONSTANT + to create a dictionary entry for , leaving n in its + parameter field. When is later executed, n will be + left on the stack. + +CONTEXT -- addr U,151 + Leave the address of a variable specifying the vocabulary in + which dictionary searches are to be made, during + interpretation of the input stream. + +CONVERT d1 addr1 -- d2 addr2 195 + Convert to the equivalent stack number the text beginning at + addr1+1 with regard to BASE. The new value is accumulated + into double number d1, being left as d2. addr2 is the address + of the first non-convertible character. + +COUNT addr -- addr+1 n 159 + Leave the address addr+1 and the character count of text + beginning at addr. The first byte at addr must contain the + character count n. Range of n is {0..255}. + +CR 160 "c-r" + Cause a carriage-return and line-feed to occur at the current + output device. + +CREATE 239 + A defining word used in the form: + CREATE + to create a dictionary entry for , without allocating + any parameter field memory. When is subsequently + executed, the address of the first byte of 's parameter + field is left on the stack. + +CURRENT -- addr U,137 + Leave the address of a variable specifying the vocabulary into + which new word definitions are to be entered. + +D+ d1 d2 --- d3 241 "d-plus" + Leave the arithmetic sum of d1 plus d2. + +D< d1 d2 -- flag 244 "d-less-than" + True if d1 is less than d2. + +DECIMAL 197 + Set the input-output numeric conversion base to ten. + +DEFINITIONS 155 + Set CURRENT to the CONTEXT vocabulary so that subsequent + definitions will be created in the vocabulary previously + selected as CONTEXT. + +DEPTH -- n 238 + Leave the number of the quantity of 16-bit values contained in + the data stack, before n added. + +DNEGATE d -- -d 245 "d-negate" + Leave the two's complement of a double number. + +DO n1 n2 -- I,C,142 + Used in a colon-definition: + DO ... LOOP or + DO ... +LOOP + Begin a loop which will terminate based on control parameters. + The loop index begins at n2, and terminates based on the limit + n1. At LOOP or +LOOP, the index is modified by a positive or + negative value. The range of a DO-LOOP is determined by the + terminating word. DO-LOOP may be nested. Capacity for three + levels of nesting is specified as a minimum for standard + systems. + +DOES> I,C,168 "does" + Define the run-time action of a word created by a high-level + defining word. Used in the form: + : ... CREATE ... DOES> ... ; + and then + Marks the termination of the defining part of the defining + word and begins the defining of the run-time action for + words that will later be defined by . On execution of + the sequence of words between DOES> and ; are + executed, with the address of 's parameter field on the + stack. + +DROP n -- 233 + Drop the top number from the stack. + +DUP n -- n n 205 "dupe" + Leave a copy of the top stack number. + +ELSE -- I,C,167 + Used in a colon-definition in the form: + IF ... ELSE ... THEN + ELSE executes after the true part following IF. ELSE forces + execution to skip till just after THEN. It has no effect on + the stack. (see IF) + +EMIT char -- 207 + Transmit character to the current output device. + +EMPTY-BUFFERS 145 + Mark all block buffers as empty, without necessarily affecting + their actual contents. UPDATEd blocks are not written to mass + storage. + +EXECUTE addr -- 163 + + Execute the dictionary entry whose compilation address is on + the stack. + +EXIT C,117 + When compiled within a colon-definition, terminate execution + of that definition, at that point. May not be used within a + DO...LOOP. + +EXPECT addr n -- 189 + Transfer characters from the terminal beginning at addr, + upward, until a "return" or the count of n has been received. + Take no action for n less than or equal to zero. One or two + nulls are added at the end of text. + +FILL addr n byte -- 234 + Fill memory beginning at address with a sequence of n copies + of byte. If the quantity n is less than or equal to zero, + take no action. + +FIND -- addr 203 + Leave the compilation address of the next word name, which is + accepted from the input stream. If that word cannot be found + in the dictionary after a search of CONTEXT and FORTH leave + zero. + +FORGET 186 + Execute in the form: + FORGET + Delete from the dictionary (which is in the CURRENT + vocabulary) and all words added to the dictionary after + , regardless of their vocabulary. Failure to find + in CURRENT or FORTH is an error condition. + +FORTH I,187 + The name of the primary vocabulary. Execution makes FORTH the + CONTEXT vocabulary. New definitions become a part of the + FORTH until a differing CURRENT vocabulary is established. + User vocabularies conclude by 'chaining' to FORTH, so it + should be considered that FORTH is 'contained' within each + user's vocabulary. + +HERE -- addr 188 + Return the address of the next available dictionary location. + +HOLD char -- 175 + Insert char into a pictured numeric output string. May only + be used between <# and #> . + +I -- n C,136 + Copy the loop index onto the data stack. May only be used in + the form: + DO ... I ... LOOP or + DO ... I ... +LOOP + +IF flag -- I,C,210 + Used in a colon-definition 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 are skipped. The ELSE part is optional. + If flag 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. + +IMMEDIATE 103 + Marks the most recently made dictionary entry as a word which + will be executed when encountered during compilation rather + than compiled. + +J -- n C,225 + Return the index of the next outer loop. May only be used + within a nested DO-LOOP in the form: + DO ... DO ... J ... LOOP ... LOOP + +KEY -- char 100 + Leave the ASCII value of the next available character from the + current input device. + +LEAVE C,213 + Force termination of a DO-LOOP at the next LOOP or +LOOP by + setting the loop limit equal to the current value of the + index. The index itself remains unchanged, and execution + proceeds normally until the loop terminating word is + encountered. + +LIST n -- 109 + List the ASCII symbolic contents of screen n on the current + output device, setting SCR to contain n. n is unsigned. + +LITERAL n -- I,215 + If compiling, then compile the stack value n as a 16-bit + literal, which when later executed, will leave n on the stack. + +LOAD n -- 202 + Begin interpretation of screen n by making it the input + stream; preserve the locators of the present input stream + (from >IN and BLK). If interpretation is not terminated + explicitly it will be terminated when the input stream is + exhausted. Control then returns to the input stream + containing LOAD, determined by the input stream locators >IN + and BLK. + +LOOP I,C,124 + Increment the DO-LOOP index by one, terminating the loop if + the new index is equal to or greater than the limit. The + limit and index are signed numbers in the range {-32,768 + ..32,767}. + +MAX n1 n2 -- n3 218 "max" + Leave the greater of two numbers. + +MIN n1 n2 -- n3 127 "min" + Leave the lesser of two numbers. + +MOD n1 n2 -- n3 104 + Divide n1 by n2, leaving the remainder n3, with the same sign + as n1. + +MOVE addr1 addr2 n -- 113 + Move the specified quantity n of 16-bit memory cells beginning + at addr1 into memory at addr2. The contents of addr1 is moved + first. If n is negative or zero, nothing is moved. + +NEGATE n -- -n 177 + Leave the two's complement of a number, i.e., the difference + of zero less n. + +NOT flag1 -- flag2 165 + Reverse the boolean value of flag1. This is identical to 0=. + +OR n1 n2 -- n3 223 + Leave the bitwise inclusive-or of two numbers. + +OVER n1 n2 -- n1 n2 n1 170 + Leave a copy of the second number on the stack. + +PAD -- addr 226 + The address of a scratch area used to hold character strings + for intermediate processing. The minimum capacity of PAD is + 64 characters (addr through addr+63). + +PICK n1 -- n2 240 + Return the contents of the n1-th stack value, not counting n1 + itself. An error condition results for n less than one. + 2 PICK is equivalent to OVER. {1..n} + +QUERY 235 + Accept input of up to 80 characters (or until a 'return') from + the operator's terminal, into the terminal input buffer. WORD + may be used to accept text from this buffer as the input + stream, by setting >IN and BLK to zero. + +QUIT 211 + Clear the return stack, setting execution mode, and return + control to the terminal. No message is given. + +R> -- n C,110 "r-from" + Transfer n from the return stack to the data stack. + +R@ -- n C,228 "r-fetch" + Copy the number on top of the return stack to the data stack. + +REPEAT -- I,C,120 + Used in a colon-definition in the form: + BEGIN ... WHILE ... REPEAT + At run-time, REPEAT returns to just after the corresponding + BEGIN. + +ROLL n -- 236 + Extract the n-th stack value to the top of the stack, not + counting n itself, moving the remaining values into the + vacated position. An error condition results for n less than + one. {1..n} + 3 ROLL = ROT + 1 ROLL = null operation + +ROT n1 n2 n3 -- n2 n3 n1 212 "rote" + Rotate the top three values, bringing the deepest to the top. + +SAVE-BUFFERS 221 + Write all blocks to mass-storage that have been flagged as + UPDATEd. An error condition results if mass-storage writing + is not completed. + +SCR -- addr U,217 + Leave the address of a variable containing the number of the + screen most recently listed. + +SIGN n -- C,140 + Insert the ASCII "-" (minus sign) into the pictured numeric + output string, if n is negative. + +SPACE 232 + Transmit an ASCII blank to the current output device. + +SPACES n -- 231 + Transmit n spaces to the current output device. Take no + action for n of zero or less. + +STATE -- addr U,164 + Leave the address of the variable containing the compilation + state. A non-zero content indicates compilation is occurring, + but the value itself may be installation dependent. + +SWAP n1 n2 -- n2 n1 230 + Exchange the top two stack values. + +THEN I,C,161 + Used in a colon-definition in the form: + IF ... ELSE ... THEN or + IF ... THEN + THEN is the point where execution resumes after ELSE or IF + (when no ELSE is present). + +TYPE addr n -- 222 + Transmit n characters beginning at address to the current + output device. No action takes place for n less than or equal + to zero. + +U* un1 un2 -- ud3 242 "u-times" + Perform an unsigned multiplication of un1 by un2, leaving the + double number product ud3. All values are unsigned. + +U. un -- 106 "u-dot" + Display un converted according to BASE as an unsigned number, + in a free-field format, with one trailing blank. + +U/MOD ud1 un2 -- un3 un4 243 "u-divide-mod" + Perform the unsigned division of double number ud1 by un2, + leaving the remainder un3, and the quotient un4. All values + are unsigned. + +U< un1 un2 -- flag 150 "u-less-than" + Leave the flag representing the magnitude comparison of un1 < + un2 where un1 and un2 are treated as 16-bit unsigned integers. + +UNTIL flag -- I,C,,237 + Within a colon-definition, mark 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 returns to the + first word after BEGIN. BEGIN-UNTIL structures may be nested. + +UPDATE 229 + Mark the most recently referenced block as modified. The + block will subsequently be automatically transferred to mass + storage should its memory buffer be needed for storage of a + different block, or upon execution of SAVE-BUFFERS. + +VARIABLE 227 + A defining word executed in the form: + VARIABLE + to create a dictionary entry for and allot two bytes + for storage in the parameter field. The application must + initialize the stored value. When is later executed, + it will place the storage address on the stack. + +VOCABULARY 208 + A defining word executed in the form: + VOCABULARY + to create (in the CURRENT vocabulary) a dictionary entry for + , which specifies a new ordered list of word + definitions. Subsequent execution of will make it the + CONTEXT vocabulary. When becomes the CURRENT + vocabulary (see DEFINITIONS), new definitions will be created + in that list. + + In lieu of any further specification, new vocabularies 'chain' + to FORTH. That is, when a dictionary search through a + vocabulary is exhausted, FORTH will be searched. + +WHILE flag -- I,C,149 + Used in the form: + BEGIN ... flag WHILE ... REPEAT + Select conditional execution based on flag. On a true flag, + continue execution through to REPEAT, which then returns back + to just after BEGIN. On a false flag, skip execution to just + after REPEAT, exiting the structure. + +WORD char -- addr 181 + Receive characters from the input stream until the non-zero + delimiting character is encountered or the input stream is + exhausted, ignoring leading delimiters. The characters are + stored as a packed string with the character count in the + first character position. The actual delimiter encountered + (char or null) is stored at the end of the text but not + included in the count. If the input stream was exhausted as + WORD is called, then a zero length will result. The address + of the beginning of this packed string is left on the stack. + +XOR n1 n2 -- n3 174 "x-or" + Leave the bitwise exclusive-or of two numbers. + +[ I,125 "left-bracket" + End the compilation mode. The text from the input stream is + subsequently executed. See ] + +[COMPILE] I,C,179 "bracket-compile" + Used in a colon-definition in the form: + [COMPILE] + Forces compilation of the following word. This allows + compilation of an IMMEDIATE word when it would otherwise be + executed. + +] 126 "right-bracket" + Sets the compilation mode. The text from the input stream is + subsequently compiled. See [ + + + 11. EXTENSION WORD SETS + + +11.1 DOUBLE NUMBER WORD SET + + +2! d addr -- "two-store" + Store d in 4 consecutive bytes beginning at addr, as for a + double number. + +2@ addr -- d "two-fetch" + Leave on the stack the contents of the four consecutive bytes + beginning at addr, as for a double number. + +2CONSTANT d -- "two-constant" + A defining word used in the form: + d 2CONSTANT + to create a dictionary entry for , leaving d in its + parameter field. When is later executed, d will be + left on the stack. + +2DROP d -- "two-drop" + Drop the top double number on the stack. + +2DUP d -- d d "two-dupe" + Duplicate the top double number on the stack. + +2OVER d1 d2 -- d1 d2 d1 "two-over" + Leave a copy of the second double number on the stack. + +2ROT d1 d2 d3 -- d2 d3 d1 "two-rote" + Rotate the third double number to the top of the stack. + +2SWAP d1 d2 -- d2 d1 "two-swap" + Exchange the top two double numbers on the stack. + +2VARIABLE "two-variable" + A defining word used in the form: + 2VARIABLE + to create a dictionary entry of and assign four bytes + for storage in the parameter field. When is later + executed, it will leave the address of the first byte of its + parameter field is placed on the stack. + +D+ d1 d2 -- d3 241 "d-plus" + Leave the arithmetic sum of d1 and d2. + +D- d1 d2 -- d3 129 "d-minus" + Subtract d2 from d1 and leave the difference d3. + +D. d -- 129 "d-dot" + Display d converted according to BASE in a free field format, + with one trailing blank. Display the sign only if negative. + +D.R d n -- "d-dot-r" + Display d converted according to BASE, right aligned in an c + character field. Display the sign only if negative. + +D0= d -- flag "d-zero-equals" + Leave true if d is zero. + +D< d1 d2 -- flag 244 "d-less" + True if d1 is less than d2. + +D= d1 d2 -- flag "d-equal" + True if d1 equals d2. + +DABS d1 -- d2 "d-absolute" + Leave as a positive double number d2, the absolute value of a + double number, d1. {0..2,147,483,647} + +DMAX d1 d2 -- d3 "d-max" + Leave the larger of two double numbers. + +DMIN d1 d2 -- d3 "d-min" + Leave the smaller of two double numbers. + +DNEGATE d -- -d 245 + Leave the double number two's complement of a double number, + i.e., the difference 0 less d. + +DU< ud1 ud2 -- flag "d-u-less" + True if ud1 is less than ud2. Both numbers are unsigned. + + +11.2 ASSEMBLER WORD SET + +;CODE C,I,206 "semi-colon-code" + Used in the form: + : ... ;CODE + Stop compilation and terminate a defining word . + ASSEMBLER becomes the CONTEXT vocabulary. When is + executed in the form: + + to define the new , the execution address of + will contain the address of the code sequence following the + ;CODE in . Execution of any will cause this + machine code sequence to be executed. + +ASSEMBLER I,166 + Select assembler as the CONTEXT vocabulary. + +CODE 111 + A defining word used in the form: + CODE ... END-CODE + to create a dictionary entry for to be defined by a + following sequence of assembly language words. ASSEMBLER + becomes the context vocabulary. + +END-CODE + Terminate a code definition, resetting the CONTEXT vocabulary + to the CURRENT vocabulary. If no errors have occurred, the + code definition is made available for use. + + + 12. EXPERIMENTAL PROPOSALS + + +No Experimental Proposals were submitted for publication. + + + REFERENCE WORD SET + + +This word set is furnished as a reference document. It is a set of +formerly standardized words and candidate words for +standardization. + + REFERENCE WORD SET + FORTH-79 + +The Reference Word Set contain both Standard Word Definitions (with +serial number identifiers in the range 100 through 999), and +uncontrolled word definitions. + +Uncontrolled definitions are included for public reference of words +that have present usage and/or are candidates for future +standardization. + +No restrictions are placed on the definition or usage of +uncontrolled words. However, use of these names for procedures +differing from the given definitions is discouraged. + + +!BITS n1 addr n2 -- "store-bits" + Store the value of n1 masked by n2 into the equivalent masked + part of the contents of addr, without affecting bits outside + the mask. + +** n1 n2 -- n3 "power" + Leave the value of n1 to the power n2. + ++BLOCK n1 -- n2 "plus-block" + Leave the sum of n1 plus the number of the block being + interpreted, n1 and n2 are unsigned. + +-' -- ( addr ) flag "dash-tick" + Used in the form: + -' + Leave the parameter field of beneath zero (false) if + the name can be found in the CONTEXT vocabulary; leave only + true if not found. + +--> I,131 "next-block" + Continue interpretation on the next sequential block. May be + used within a colon definition that crosses a block boundary. + +-MATCH addr1 n1 addr2 n2 -- addr3 f "dash-match" + Attempt to find the n2-character string beginning at addr2 + somewhere in the n1-character string beginning at addr1. + Return the last+1 character address addr3 of the match point + and a flag which is zero if a match exists. + +-TEXT addr1 n1 addr2 -- n2 "dash-text" + Compare two strings over the length n1 beginning at addr1 and + addr2. Return zero if the strings are equal. If unequal, + return n2, the difference between the last characters + compared: addr1(i) - addr2(i) + +.R n1 n2 -- "dot-r" + Print n1 right aligned in a field of n2 characters, according + to BASE. If n2 is less than 1, no leading blanks are + supplied. + +/LOOP n -- "up-loop" + A DO-LOOP terminating word. The loop index is incremented by + the unsigned magnitude of n. Until the resultant index + exceeds the limit, execution returns to just after the + corresponding DO: otherwise, the index and limit are + discarded. Magnitude logic is used. + +1+! addr -- "one-plus-store" + Add one to the 16-bit contents at addr. + +1-! addr -- "one-minus-store" + Subtract 1 from the 16-bit contents at addr. + +2* n1 -- n2 "two-times" + Leave 2*(n1). + +2/ n1 -- n2 "two-divide" + Leave (n1)/2. + +;: C "semi-colon-oolon" + Used to specify a new defining word: + : ... + ;: ... ; + + When is executed, it creates an entry for the new word + . Later execution of will execute the sequence + of words between ;: and ; , with the address of the first + (if any) parameters associated with on the stack. + +;S "semi-s" + Stop interpretation of a block. For execution only. + +<> n1 n2 -- flag "not-equal" + Leave true if n1 is not equal to n2. + + in defining words, in the form: + : . . . ... ; + and then + When executes, . The sequence of words between established a parameter field for . When + is later executed, the sequence of words following DOES> will + be executed, with the parameter field address of on + the data stack. + +< n1 -- n2 "byte-swap" + Swap the high and low bytes within n1. + +>MOVE< addr1 addr2 n -- "byte-swap-move" + Move n bytes beginning at addr1 to the memory beginning at + addr2. During this move, the order of each byte pair is + reversed. + +@BITS addr n1 -- n2 "fetch-bits" + Return the 16-bits at addr masked by n1. + +ABORT" flag -- I,C "abort-quote" + Used in a colon-definition in the form: + ABORT" stack empty" + If the flag is true, print the following text, till ". Then + execute ABORT. + +AGAIN I,C,114 + Effect an unconditional jump back to the start of a BEGIN- + AGAIN loop. + +ASCII -- char (executing) + -- (compiling) I,C + Leave the ASCII character value of the next non-blank + character in the input stream. If compiling, compile it as a + literal, which will be later left when executed. + +ASHIFT n1 n2 -- n3 + Shift the value n1 arithemetically n2 bits left if n2 is + positive, shifting zeros into the least-significant bit + positions. If n2 is negative, n1 is shifted right. Sign + extension is to be consistent with the processor's arithmetic + shift. + +B/BUF -- 1024 "bytes-per-buffer" + A constant leaving 1024, the number of bytes per block buffer. + +BELL + Activate a terminal bell or noise-maker as appropriate to the + device in use. + +BL -- n 176 "b-l" + Leave the ASCII character value for space (decimal 32). + +BLANKS addr n -- 152 + Fill an area of memory over n bytes with the value for ASCII + blank, starting at addr. If n is less than or equal to zero, + take no action. + +C, n -- "c-comma" + Store the low-order 8 bits of n at the next byte in the + dictionary, advancing the dictionary pointer. + +CHAIN + Used in the form: + CHAIN + Connect the CURRENT vocabulary to all definitions that might + be entered into the vocabulary 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 + +COM n1 -- n2 + Leave the one's complement of n1. + +CONTINUED n -- + Continue interpretation at block n. + +CUR -- addr + A variable pointing to the physical record number before which + the tape is currently positioned. REWIND sets CUR=1. + +DBLOCK d -- addr "D-block" + Identical to BLOCK but with a 32-bit block unsigned number. + +DPL -- addr "d-p-l" + A variable containing the number of places after the + fractional point for output conversion. If DPL contains zero, + the last character output will be a decimal point. No point + is output if DPL contains a negative value. DPL may be set + explicitly, or by certain output words, but is unaffected by + number input. + +DUMP addr n -- 123 + List the contents of n addresses at addr. Each line of values + may be preceded by the address of the first value. + +EDITOR I,172 + The name of the editor vocabulary. When this name is + executed, EDITOR is established as the CONTEXT vocabulary. + +END I,C,224 + A synonym for UNTIL. + +ERASE addr n -- 182 + Fill an area of memory over n bytes with zeros, starting at + addr. If n is zero or less, take no action. + +FLD -- addr "f-l-d" + A variable pointing to the field length reserved for a number + during output conversion. + +FLUSH + A synonym for SAVE-BUFFERS. + +H. n -- + Output n as a hexadecimal integer with one trailing blank. + The current base is unchanged. + +HEX -- 162 + Set the numeric input-output conversion base to sixteen. + +I' -- n C "i-prime" + Used within a colon-definition executed only from within a DO- + LOOP to return the corresponding loop index. + +IFEND + Terminate a conditional interpretation sequence begun by + IFTRUE. + +IFTRUE flag -- + Begin an + IFTRUE ... OTHERWISE ... IFEND + conditional sequence. These conditional words operate like + IF ... ELSE ... THEN + except that they cannot be nested, and are to be used only + 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. + +INDEX n1 n2 -- + Print the first line of each screen over the range {n1..n2}. + This displays the first line of each screen of source text, + which conventionally contains a title. + +INTERPRET + Begin 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 terminal input + buffer. + +K -- n C + Within a nested DO-LOOP, return the index of the second outer + loop. + +LAST -- addr + A variable containing the address of the beginning of the last + dictionary entry made, which may not yet be a complete or + valid entry. + +LINE n -- addr + Leave the address of the beginning of line n for the screen + whose number is contained in SCR. The range of n is {0..15}. + +LINELOAD n1 n2 -- + Begin interpretation at line n1 of screen n2. + +LOADS n -- + A defining word used in the form: + n LOADS + When is subsequently executed, block n will be loaded. + +MAP0 -- addr + A variable pointing to the first location in the tape map. + +MASK n1 -- n2 + Leave a mask of n1 most significant bits if n1 is positive, or + n least significant bits if n1 is negative. + +MS n -- + Delay for approximately n milliseconds. + +NAND n1 n2 -- n3 + Hie one's complement of the logical and of n1 and n2. + +NOR n1 n2 -- n3 + The one's complement of the logical or of n1 and n2. + +NUMBER addr -- n + Convert the count and character string at addr, to a signed + 32-bit integer, using the current base. If numeric conversion + is not possible, an error condition exists. The string may + contain a preceding negative sign. + +O. n -- + Print n in octal format with one trailing blank. The value in + base is unaffected. + +OCTAL + Set the number base to 8. + +OFFSET -- addr 128 + A variable that contains the offset added to the block number + on the stack by BLOCK to determine the actual physical block + number. The user must add any desired offset when utilizing + BUFFER. + +OTHERWISE + An interpreter-level conditional word. See IFTRUE. + +PAGE + Clear the terminal screen or perform an action suitable to the + output device currently active. + +READ-MAP + Read to the next file mark on tape constructing a + correspondence table in memory (the map) relating physical + block position to logical block number. The tape should + normally be rewound to its load point before executing READ- + MAP. + +REMEMBER + A defining word used in the form: + REMEMBER + Defines a word which, when executed, will cause and all + subsequently defined words to be deleted from the dictionary. + may be compiled into and executed from a colon + definition. The sequence + DISCARD REMEMBER DISCARD + provides a standardized preface to any group of transient word + definitions. + +REWIND + Rewind the tape to its load point, setting CUR=1. + +ROTATE n1 n2 -- n3 + Rotate the value n1 left n2 bits if n2 is positive, right n2 + bits if n2 is negative. Bits shifted out of one end of the + cell are shifted back in at the opposite end. + +S0 -- addr "s-zero" + Returns the address of the bottom of the stack, when empty. + +SET n addr -- + A defining word used in the form: + n addr SET + + Defines a word which, when executed, will cause the + value n to be stored at address. + +SHIFT n1 n2 -- n3 + Logical shift n1 left n2 bits if n2 in positive, right + if n2 is negative. Zeros are shifted into vacated bit + positions. + +SP@ -- addr 214 "s-p-fetch" + Return the address of the top of the stack, just before SP@ + was executed. + +TEXT c -- + Accept characters from the input stream, as for WORD, into + PAD, blank-filling the remainder of PAD to 64 characters. + +THRU n1 n2 -- + Load consecutively the blocks from n1 through n2. + +U.R un1 n2 -- 216 "u-dot-r" + Output un1 as an unsigned number right justified in a field n2 + characters wide. If n2 is smaller than the characters + required for n1, no leading spaces are given. + +USER n -- + A defining word used in the form: + n USER + which creates a user variable . n is the cell offset + within the user area where the value for is stored. + Execution of leaves its absolute user area storage + address. + +VLIST + List the word names of the CONTEXT vocabulary starting with + the most recent definition. + +WHERE + 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. + +\LOOP n -- I,C "down-loop" + A DO-LOOP terminating word. The loop index is decremented by + n and the loop terminated when the resultant index becomes + equal to or less than the limit. Magnitude logic is used, and + n must be positive. + diff --git a/docs/reference/standards/FORTH83.TXT b/docs/reference/standards/FORTH83.TXT new file mode 100644 index 00000000..93dc3276 --- /dev/null +++ b/docs/reference/standards/FORTH83.TXT @@ -0,0 +1,6139 @@ + + + + + + + + + + + + + + + + + + + + + + + FORTH-83 STANDARD + + A PUBLICATION OF THE FORTH STANDARDS TEAM + + + + + + + + + + + + + + + + + AUGUST 1983 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + FORTH-83 STANDARD + + + + + 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. + + ISBN 0-914699-03-2 + + FORTH STANDARDS TEAM + P.O. BOX 4545 + MOUNTAIN VIEW, CA 94040 + USA + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ii + + + + + + FORTH-83 STANDARD + + + + + TABLE OF CONTENTS + + 1. FOREWORD ............................................... 1 + 2. PURPOSE ................................................ 2 + 3. SCOPE .................................................. 2 + 4. TRADEOFFS .............................................. 3 + 5. DEFINITIONS OF TERMS ................................... 4 + 6. REFERENCES ............................................. 13 + 7. REQUIREMENTS ........................................... 14 + 8. COMPLIANCE AND LABELING ................................ 16 + 9. USAGE .................................................. 18 + 10. ERROR CONDITIONS ....................................... 21 + 11. GLOSSARY NOTATION ...................................... 23 + 12. REQUIRED WORD SET ...................................... 27 + 13. DOUBLE NUMBER EXTENSION WORD SET ....................... 45 + 14. ASSEMBLER EXTENSION WORD SET ........................... 48 + 15. SYSTEM EXTENSION WORD SET .............................. 50 + 16. CONTROLLED REFERENCE WORDS ............................. 52 + + APPENDICES + A. FORTH STANDARDS TEAM MEMBERSHIP ................... 55 + B. UNCONTROLLED REFERENCE WORDS ...................... 58 + C. EXPERIMENTAL PROPOSALS ............................ 65 + C.1 SEARCH ORDER SPECIFICATION AND CONTROL ....... 66 + C.2 DEFINITION FIELD ADDRESS CONVERSION OPERATORS . 71 + D. STANDARDS TEAM CHARTER ............................ 74 + E. PROPOSAL/COMMENT FORM AND INSTRUCTIONS ............ 85 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + iii + + + + + + FORTH-83 STANDARD + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + iv + + + + + + 1. FOREWORD + + + + + 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-1970s + 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. + + The FORTH Standards Team is comprised of individuals who have a + great variety of experience and technical expertise with FORTH. + The FORTH Standards Team consists of both users and implementers. + Comments, proposals, and correspondence should be mailed to: + FORTH Standards Team, P.O. Box 4545, Mountain View, CA 94040 USA. + + 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. If the standard does not explicitly + specify a requirement or restriction, a system or application may + utilize any choice without sacrificing compliance to the standard + provided that the system or application remains transportable and + obeys the other requirements of the standard. + + + + + + + + + + + + + + + + + + + + 1 + + + + + + 2. PURPOSE + + + + + 2. PURPOSE + + + The purpose of this 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, provided sufficient + computer resources (memory, mass storage) are available. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 2 + + + + + + 4. TRADEOFFS + + + + + 4. TRADEOFFS + + + When conflicting choices are made, the following order guides the + Standards Team: + + 1) Functional correctness - known bounds, non-ambiguous; + + 2) Portability - repeatable results when programs are + transported among Standard Systems; + + 3) Simplicity; + + 4) Naming clarity - uniformity of expression using descriptive + rather than procedure names, i.e., [COMPILE] rather than 'C, + and ALLOT rather than DP+! ; + + 5) Generality; + + 6) Execution speed; + + 7) Memory compactness; + + 8) Compilation speed; + + 9) Historical continuity; + + 10) Pronounceability; + + 11) Teachability. + + + + + + + + + + + + + + + + + + + + + + + + + + 3 + + + + + + 5. DEFINITIONS OF TERMS + + + + + 5. DEFINITIONS OF TERMS + + + These are the definitions of the terms used within this Standard. + + address, byte + An unsigned 16-bit number that locates an 8-bit byte in a + standard FORTH address space over the range {0..65,535}. It + may be a native machine address or a representation on a + virtual machine, locating the addr-th byte within the + virtual byte address space. Addresses are treated as + unsigned numbers. See: "arithmetic, two's complement" + + address, compilation + The numerical value compiled for a FORTH word definition + which identifies that definition. The address interpreter + uses this value to locate the machine code corresponding to + each definition. + + address, native machine + The natural address representation of the host computer. + + address, parameter field + The address of the first byte of memory associated with a + word definition for the storage of compilation addresses (in + a colon definition), numeric data, text characters, etc. + + arithmetic, two's complement + Arithmetic is performed using two's complement integers + within a field of either 16 or 32 bits as indicated by the + operation. Addition and subtraction of two's complement + integers ignore any overflow condition. This allows numbers + treated as unsigned to produce the same results as if the + numbers had been treated as signed. + + block + The 1024 bytes of data from mass storage which are + referenced by block numbers in the range {0..the number of + blocks available -1}. The actual amount of data transferred + and the translation from block number to device and physical + record is a function of the implementation. See: "block + buffer" "mass storage" + + block buffer + A 1024-byte memory area where a block is made temporarily + available for use. Block buffers are uniquely assigned to + blocks. See: "9.7 Multiprogramming Impact" + + byte + An assembly of 8 bits. In reference to memory, it is the + storage capacity for 8 bits. + + + + + 4 + + + + + + 5. DEFINITIONS OF TERMS + + + character + A 7-bit number the significance of which is given by the + ASCII standard. When contained in a larger field, the + higher order bits are zero. See: "6. REFERENCES" + + compilation + The action of converting text words from the input stream + into an internal form suitable for later execution. When in + the compile state, the compilation addresses of FORTH words + are compiled into the dictionary for later execution by the + address interpreter. Numbers are compiled to be placed on + the data stack when later executed. Numbers are accepted + from the input stream unsigned or negatively signed and + converted using the value of BASE . See: "number" "number + conversion" "interpreter, text" + + defining word + A word that, when executed, creates a new dictionary entry + in the compilation vocabulary. The new word name is taken + from the input stream. If the input stream is exhausted + before the new name is available, an error condition exists. + Example of defining words are: : CONSTANT CREATE + + definition + See: "word definition" + + dictionary + A structure of word definitions in computer memory which is + extensible and grows toward higher memory addresses. + Entries are organized in vocabularies to aid location by + name. See: "search order" + + display + The process of sending one or more characters to the current + output device. These characters are typically displayed or + printed on a terminal. The selection of the current output + device is system dependent. + + division, floored + Integer division in which the remainder carries the sign of + the divisor or is zero, and the quotient is rounded to its + arithmetic floor. Note that, except for error conditions, + n1 n2 SWAP OVER /MOD ROT * + is identical to n1. See: + "floor, arithmetic" + Examples: + dividend divisor remainder quotient + 10 7 3 1 + -10 7 4 -2 + 10 -7 -4 -2 + -10 -7 -3 1 + + + + + + + + 5 + + + + + + 5. DEFINITIONS OF TERMS + + + equivalent execution + A standard program will produce the same results, exclusive + of timing dependencies, when given the same inputs on any + Standard System which has sufficient resources to execute + the program. Only standard source programs are + transportable. + + error condition + An exceptional condition which requires action by the system + which may be other than the expected function. Refer to the + section "10. Error Conditions". + + false + A zero number represents the false state of a flag. + + flag + A number that may have one of two logical states, false or + true. See: "false" "true" + + floor, arithmetic + If z is any real number, then the floor of z is the greatest + integer less than or equal to z. + The floor of +.6 is 0 + The floor of -.4 is -1 + + free field format + Numbers are converted using the value of BASE and then + displayed with no leading zeros. A trailing space is + displayed. The number of characters displayed is the + minimum number of characters, at least one, to uniquely + represent the number. See: "number conversion" + + glossary + A set of explanations in natural language to describe the + corresponding computer execution of word definitions. + + immediate word + A word which executes when encountered during compilation or + interpretation. Immediate words handle special cases during + compilation. See, for example, IF LITERAL ." etc. + + input stream + A sequence of characters available to the system, for + processing by the text interpreter. The input stream + conventionally may be taken from the current input device + (via the text input buffer) and mass storage (via a block + buffer). BLK , >IN , TIB and #TIB specify the input stream. + Words using or altering BLK , >IN , TIB and #TIB are + responsible for maintaining and restoring control of the + input stream. + + + + + + + + 6 + + + + + + 5. DEFINITIONS OF TERMS + + + The input stream extends from the offset value of >IN to the + size of the input stream. If BLK is zero the input stream + is contained within the area addressed by TIB and is #TIB + bytes long. If BLK is non-zero the input stream is + contained within the block buffer specified by BLK and is + 1024 bytes long. See: "11.8 Input Text" + + interpreter, address + The machine code instructions, routine or other facilities + that execute compiled word definitions containing + compilation addresses. + + interpreter, text + The word definitions(s) that repeatedly accepts a word name + from the input stream, locates the corresponding compilation + address and starts the address interpreter to execute it. + Text from the input stream interpreted as a number leaves + the corresponding value on the data stack. Numbers are + accepted from the input stream unsigned or negatively signed + and converted using the value of BASE . See: "number" + "number conversion" + + layers + The grouping of word names of each Standard word set to show + like characteristics. No implementation requirements are + implied by this grouping. + + layer, compiler + Word definitions which add new procedures to the dictionary + or which aid compilation by adding compilation addresses or + data structures to the dictionary. + + layer, devices + Word definitions which allow access to mass storage and + computer peripheral devices. + + layer, interpreter + Word definitions which support vocabularies, terminal + output, and the interpretation of text from the text input + buffer or a mass storage device by executing the + corresponding word definitions. + + layer, nucleus + Word definitions generally defined in machine code that + control the execution of the fundamental operations of a + virtual FORTH machine. This includes the address + interpreter. + + load + Redirection of the text interpreter's input stream to be + from mass storage. This is the general method for + compilation of new definitions into the dictionary. + + + + + + 7 + + + + + + 5. DEFINITIONS OF TERMS + + + mass storage + Storage which might reside outside FORTH's address space. + Mass storage data is made available in the form of 1024-byte + blocks. A block is accessible within the FORTH address + space in a block buffer. When a block has been indicated as + UPDATEed (modified) the block will ultimately be transferred + to mass storage. + + number + When values exist within a larger field, the most- + significant bits are zero. 16-bit numbers are represented + in memory by addressing the first of two bytes at + consecutive addresses. The byte order is unspecified by + this Standard. Double numbers are represented on the stack + with the most-significant 16 bits (with sign) most + accessible. Double numbers are represented in memory by two + consecutive 16-bit numbers. The address of the least + significant 16 bits is two greater than the address of the + most significant 16 bits. The byte order within each 16-bit + field is unspecified. See: "arithmetic, two's complement" + "number types" "9.8 Numbers" "11.7 Stack Parameters" + + number conversion + Numbers are maintained internally in binary and represented + externally by using graphic characters within the ASCII + character set. Conversion between the internal and external + forms is performed using the current value of BASE to + determine the digits of a number. A digit has a value + ranging from zero to the value of BASE-1. The digit with + the value zero is represented by the ASCII character "0" + (position 3/0 with the decimal equivalent of 48). This + representation of digits proceeds through the ASCII + character set to the character "(" corresponding to the + decimal value 9. For digits with a value exceeding 9, the + ASCII graphic characters beginning with the character "A" + (position 4/1 with the decimal equivalent 65) corresponding + to the decimal value 10 are used. This sequence then + continues up to and including the digit with the decimal + value 71 which is represented by the ASCII character "~" + (position 7/14 with a decimal equivalent 126). A negative + number may be represented by preceding the digits with a + single leading minus sign, the character "-". + + number types + All number types consist of some number of bits. These bits + are either arbitrary or are weighted. + + + + + + + + + + + + 8 + + + + + + 5. DEFINITIONS OF TERMS + + + Signed and unsigned numbers use weighted bits. Weighted + bits within a number have a value of a power of two + beginning with the rightmost (least-significant) bit having + the value of two to the zero power. This weighting + continues to the leftmost bit increasing the power by one + for each bit. For an unsigned number this weighting pattern + includes the leftmost bit; thus, for an unsigned 16-bit + number the weight of the leftmost bit is 32,768. For a + signed number this weighting pattern includes the leftmost + bit but the weight of the leftmost bit is negated; thus, for + a signed 16-bit number the weight of the leftmost bit is + -32,768. This weighting pattern for signed numbers is + called two's complement notation. + + Unspecified weighted numbers are either unsigned numbers or + signed numbers; program context determines whether the + number is signed or unsigned. See: "11.7 Stack Parameters" + + pictured numeric output + The use of numeric output definitions which convert + numerical values into text strings. These definitions are + used in a sequence which resembles a symbolic 'picture' of + the desired text format. Conversion proceeds from least- + significant digit to most-significant digit, and converted + characters are stored from higher memory addresses to lower. + + program + A complete specification of execution to achieve a specific + function (application task) expressed in FORTH source code + form. + + receive + The process of obtaining one character from the current + input device. The selection of the current input device is + system dependent. + + recursion + The process of self-reference, either directly or + indirectly. + + return + The means of indicating the end of text by striking a key on + an input device. The key used is system dependent. This + key is typically called "RETURN", "CARRIAGE RETURN", or + "ENTER". + + screen + Textual data arranged for editing. By convention, a screen + consists of 16 lines (numbered 0 through 15) of 64 + characters each. Screens usually contain program source + text, but may be used to view mass storage data. The first + byte of a screen occupies the first byte of a mass storage + block, which is the beginning point for text interpretation + during a load. + + + + 9 + + + + + + 5. DEFINITIONS OF TERMS + + + search order + A specification of the order in which selected vocabularies + in the dictionary are searched. Execution of a vocabulary + makes it the first vocabulary in the search order. The + dictionary is searched whenever a word is to be located by + its name. This order applies to all dictionary searches + unless otherwise noted. The search order begins with the + last vocabulary executed and ends with FORTH , unless + altered in a system dependent manner. + + source definition + Text consisting of word names suitable for compilation or + execution by the text interpreter. Such text is usually + arranged in screens and maintained on a mass storage device. + + stack, data + A last in, first out list consisting of 16-bit binary + values. This stack is primarily used to hold intermediate + values during execution of word definitions. Stack values + may represent numbers, characters, addresses, boolean + values, etc. + + When the name 'stack' is used alone, it implies the data + stack. + + stack, return + A last in, first out list which contains the addresses of + word definitions whose execution has not been completed by + the address interpreter. As a word definition passes + control to another definition, the return point is placed on + the return stack. + + The return stack may cautiously be used for other values. + + string, counted + A sequence of consecutive 8-bit bytes located in memory by + their low memory address. The byte at this address contains + a count {0..255} of the number of bytes following which are + part of the string. The count does not include the count + byte itself. Counted strings usually contain ASCII + characters. + + string, text + A sequence of consecutive 8-bit bytes located in memory by + their low memory address and length in bytes. Strings + usually, but not exclusively, contain ASCII characters. + When the term 'string' is used alone or in conjunction with + other words it refers to text strings. + + + + + + + + + + 10 + + + + + + 5. DEFINITIONS OF TERMS + + + structure, control + A group of FORTH words which when executed alter the + execution sequence. The group starts and terminates with + compiler words. Examples of control structures: DO ... + LOOP DO ... +LOOP BEGIN ... WHILE ... REPEAT BEGIN ... + UNTIL IF ... THEN IF ... ELSE ... THEN See: "9.9 Control + Structures" + + transportability + This term indicates that equivalent execution results when a + program is executed on other than the system on which it was + created. See: "equivalent execution" + + true + A non-zero value represents the true state of a flag. Any + non-zero value will be accepted by a standard word as + 'true'; all standard words return a 16-bit value with all + bits set to one when returning a 'true' flag. + + user area + An area in memory which contains the storage for user + variable. + + variable, user + A variable whose data storage area is usually located in the + user area. Some system variables are maintained in the user + area so that the words may be re-entrant to different users. + + vocabulary + An ordered list of word definitions. Vocabularies are an + advantage in separating different word definitions that may + have the same name. More than one definition with the same + name can exist in one vocabulary. The latter is called a + redefinition. The most recently created redefinition will + be found when the vocabulary is searched. + + vocabulary, compilation + The vocabulary into which new word definitions are appended. + + word + A sequence of characters terminated by one blank or the end + of the input stream. Leading blanks are ignored. Words are + usually obtained via the input stream. + + word definition + A named FORTH execution procedure compiled into the + dictionary. Its execution may be defined in terms of + machine code, as a sequence of compilation address, or other + compiled words. + + + + + + + + + 11 + + + + + + 5. DEFINITIONS OF TERMS + + + word name + The name of a word definition. Word names are limited to 31 + characters and may not contain an ASCII space. If two + definitions have different word names in the same vocabulary + they must be uniquely findable when this vocabulary is + searched. See: "vocabulary" "9.5.3 EXPECT" + + word set + A named group of FORTH word definitions in the Standard. + + word set, assembler extension + Additional words which facilitate programming in the native + machine language of the computer which are by nature system + dependent. + + word set, double number extension + Additional words which facilitate manipulation of 32-bit + numbers. + + word set, required + The minimum words needed to compile and execute Standard + Programs. + + word set, system extension + Additional words which facilitate the access to internal + system characteristics. + + word, standard + A named FORTH procedure definition, in the Required word set + or any extension word sets, formally reviewed and accepted + by the Standards Team. + + + + + + + + + + + + + + + + + + + + + + + + + + + 12 + + + + + + 6. REFERENCES + + + + + 6. REFERENCES + + + The following document is considered to be a portion of this + Standard: + + American National Standard Code for Information Interchange, + X3.4-1977 (ASCII), American National Standards Institute, + 1430 Broadway, New York, NY 10018, USA. + + The following documents are noted as pertinent to the FORTH-83 + Standard, but are not part of this Standard. + + FORTH-77, FORTH Users Group, FST-780314 + + FORTH-78, FORTH International Standards Team + + FORTH-79, FORTH Standards Team + + FORTH-83 STANDARD, Appendices, FORTH Standards Team + + Webster's Collegiate Dictionary shall be used to resolve + conflicts in spelling and English word usage. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 13 + + + + + + 7. REQUIREMENTS + + + + + 7. REQUIREMENTS + + + + 7.1 Documentation Requirements + + + 7.1.1 Each Standard System shall be accompanied by a + statement of: + + 1. System dictionary space used in bytes; + + 2. Application dictionary space available in bytes; + + 3. Data space in bytes; + + 4. Return stack space in bytes; + + 5. Mass storage block ranges used by the system; + + 6. Mass storage block ranges available to applications; + + 7. Operator's terminal facilities available; + + 8. System action taken upon each of the general or specified + error conditions as identified in this standard. + + + 7.1.2 Each standard program shall be accompanied by a + statement of the minimum requirements for: + + 1. Dictionary space in bytes; + + 2. Data stack space in bytes; + + 3. Return stack space in bytes; + + 4. Mass storage block ranges; + + 5. Operator's terminal facilities + + + 7.2 Testing Requirements + + The following host computer configuration is specified as a + minimum environment for testing against this Standard. + Applications may require different capacities. + + 1. 2000 bytes of memory for application dictionary; + + 2. Data stack of 64 bytes; + + + + + 14 + + + + + + 7. REQUIREMENTS + + + 3. Return stack of 48 bytes; + + 4. Mass storage capacity of 32 blocks, numbered 0 through 31; + + 5. One ASCII input/output device acting as an operator's + terminal. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 15 + + + + + + 8. COMPLIANCE AND LABELING + + + + + 8. COMPLIANCE AND LABELING + + + The FORTH Standards Team hereby specifies the requirements for + labeling of systems and applications so that the conditions for + program portability may be established. + + A Standard System may use the specified labeling if it complies + with the terms of this Standard and meets the particular Word Set + definitions. + + A Standard Program (application) may use the specified labeling + if it utilizes the specified Standard System according to this + Standard and executes equivalently on any such system. + + In a system or application, a standard word may not be redefined + to perform a different function within the vocabulary FORTH. + + + FORTH Standard + + A system may be labeled: + + FORTH-83 Standard + + if it includes all of the Required Word Set in either source or + object form and complies with the text of this Standard. After + executing "FORTH-83" the dictionary must contain all of the + Required Word Set in the vocabulary FORTH, as specified in this + Standard. + + + Standard Sub-set + + A system may be labeled: + + FORTH-83 Standard Sub-set + + if it includes a portion of the Required Word Set and complies + with the remaining text of this Standard. However, no Required + Word may be present with a non-standard definition. + + + Standard with Extensions + + A system may be labeled: + + FORTH-83 Standard with Standard Extension(s) + + if it comprises a FORTH-83 Standard System and one or more + Standard Extension Word Set(s). For example, a designation would + be in the form: + + + + 16 + + + + + + 8. COMPLIANCE AND LABELING + + + FORTH-83 Standard with Double-Number Standard Extension + + + Standard Program + + A FORTH source program which executes equivalently on any + Standard System may be labeled: + + FORTH-83 Standard Program + + See: "equivalent execution" "7. REQUIREMENTS" + + + Standard Program with Environmental Dependencies + + A program which is standard in all ways except for specific + environmentally dependent words may be labeled: + + FORTH-83 Standard Program with Environmental Dependencies + + if the following additional requirements are met: + + 1) Environmental dependencies (including hardware + dependencies) shall be factored into an isolated set of + application word definitions. + + 2) Each environmentally dependent word definition must be + fully documented, including all dependencies in a manner at + least as detailed as the standard words. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 17 + + + + + + 9. USAGE + + + + + 9. USAGE + + + + 9.1 Words 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.2 Addressable Memory + + The FORTH system may share the dictionary space with the user's + application. The native addressing protocol of the host computer + is beyond the scope of this Standard. + + Therefore, in a Standard Program, the user may only operate on + data which was stored by the application. No exceptions! + + A Standard Program may address: + + 1. parameter fields of words created with CREATE , VARIABLE , + and user defined words which execute CREATE ; + + 2. dictionary space ALLOTted; + + 3. data in a valid mass storage block buffer. + See: "9.7 Multiprogramming Impact"; + + 4. data area of user variables; + + 5. text input buffer and PAD up to the amount specified as the + minimum for each area. + + A Standard Program may NOT address: + + 1. directly into the data or return stacks; + + 2. into a definition's name field, link field, or code field; + + + + 18 + + + + + + 9. USAGE + + + 3. into a definition's parameter field if not stored by the + application. + + + 9.3 Return Stack + + A Standard Program may cautiously use the return stack with the + following restrictions: + + The return stack may not be accessed inside a do-loop for values + placed on the return stack before the loop was entered. Further, + neither I nor J may be used to obtain the index of a loop if + values are placed and remain on the return stack within the loop. + When the do-loop is executed all values placed on the return + stack within that loop must be removed before LOOP , +LOOP , or + LEAVE is executed. Similarly, all values placed on the return + stack within a colon definition must be removed before the colon + definition is terminated at ; or before EXIT is executed. + + + 9.4 Compilation + + The system uses the return stack and the dictionary in a system + dependent manner during the compilation of colon definitions. + Some words use the data stack in a system dependent manner during + compilation. See: "sys (11.7)" + + + 9.5 Terminal Input and Output + + + 9.5.1 KEY + + A Standard System must receive all valid ASCII characters. Each + KEY receives one ASCII character, with more-significant bits + environmentally dependent and might 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 anticipated that control characters can + be received. + + + + + + + + + + + 19 + + + + + + 9. USAGE + + + 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. + + + 9.6 Transporting Programs Between Standard Systems + + Further usage requirements are expected to be added for + transporting programs between Standard Systems. + + + 9.7 Multiprogramming Impact + + In a multiprogrammed system, Device Layer words and those words + which implicitly reference the Device Layer words may relinquish + control of the processor to other tasks. Although there is + insufficient experience to specify a standard for + multiprogramming, historical usage dictates that a programmer be + aware of the potential impact with regard to resources shared + between tasks. The only shared resources specified within the + Standard are block buffers. Therefore the address of a block + buffer returned by BLOCK or BUFFER becomes invalid during and + after the execution of any word marked by the attribute M in the + glossary or any words executing them. A block buffer is valid + only if its address is valid. See: "11.4 Attributes" + + + 9.8 Numbers + + Interpreted or compiled numbers are in the range + {-32,768..65,535}. See: "number conversion" + + + 9.9 Control Structures + + Control structures are compiled inside colon definitions. + Control structures can be nested but cannot overlap. For + additional limitations see DO . + + + + + + 20 + + + + + + 10. ERROR CONDITIONS + + + + + 10. ERROR CONDITIONS + + + + 10.1 Possible Actions on an Error + + When an error condition occurs, a Standard System may take one or + more of the following actions: + + 1. ignore and continue; + + 2. display a message; + + 3. execute a particular word; + + 4. set interpret state and interpret a block; + + 5. set interpret state and begin interpretation; + + 6. other system dependent actions. + + See: "7.1 Documentation Requirements" + + + 10.2 General Error Conditions + + The following error conditions apply in many situations. These + error conditions are listed below, but may occur at various times + and with various words. + + 1. input stream exhausted before encountering a required + or delimiting character; + + 2. insufficient stack space or insufficient number of stack + entries during text interpretation or compilation; + + 3. a word not found and not a valid number, during text + interpretation or compilation; + + 4. compilation of incorrectly nested control structures; + + 5. execution of words restricted to compilation only, when not + in the compile state and while not compiling a colon + definition; + + 6. FORGETting within the system to a point that removes a word + required for correct execution; + + 7. insufficient space remaining in the dictionary; + + 8. a stack parameter out of range, e.g., a negative number when + a +n was specified in the glossary; + + + + 21 + + + + + + 10. ERROR CONDITIONS + + + 9. correct mass storage read or write was not possible. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 22 + + + + + + 11. GLOSSARY NOTATION + + + + + 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 exectution + 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 a potential multiprogramming impact. + See: "9.7 Multiprogramming Impact" + + U A user variable. + + + + + + + + + + 23 + + + + + + 11. GLOSSARY NOTATION + + + 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 references to numbers apply to 16- + bit signed integers. The implied range of values is shown as + {from..to}. The contents of an address is shown by double + braces, 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 24 + + + + + + 11. GLOSSARY NOTATION + + + Stack Number Range in Minimum + Abbrv. Type Decimal Field + + flag boolean 0=false, else=true 16 + true boolean -1 (as a result) 16 + false boolean 0 16 + 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) {-32,768..32,767} 16 + +n positive number {0..32,767} 16 + u unsigned number {0..65,535} 16 + w unspecified weighted number + (n or u) {-32,768..65,535} 16 + addr address (same as u) {0..65,535} 16 + 32b 32 arbitrary bits not applicable 32 + d double number {-2,147,483,648.. + 2,147,483,647} 32 + +d positive double number {0..2,147,483,647} 32 + ud unsigned double number {0..4,294,967,295} 32 + wd unspecified weighted double + number (d or ud) {-2,147,483,648.. + 4,294,967,295} 32 + sys 0, 1, or more system + dependent stack entries not applicable na + + 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). See: "arithmetic, two's + complement" "number" "number types" "stack, data" + + + 11.8 Input Text + + + + 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. See: "10.2 General Error + Conditions" + + + + + + + + + + + + + 25 + + + + + + 11. GLOSSARY NOTATION + + + 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. See: "10.2 General Error Conditions" + + + 11.9 References to other words and definitions + + Glossary definitions may refer to other glossary definitions or + to definitions of terms. Such references are made using the + expression "See:". These references provide additional + information which apply as if the information is a portion of the + glossary entry using "See:". + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 26 + + + + + + 12. REQUIRED WORD SET + + + + + 12. REQUIRED WORD SET + + + + 12.1 The Required Word Set Layers + + The words of the Required Word Set are grouped to show like + characteristics. No implementation requirements should be + inferred from this grouping. + + + Nucleus layer + + ! * */ */MOD + +! - / /MOD 0< 0= 0> 1+ 1- 2+ + 2- 2/ < = > >R ?DUP @ ABS AND C! C@ CMOVE + CMOVE> COUNT D+ D< DEPTH DNEGATE DROP DUP EXECUTE + EXIT FILL I J MAX MIN MOD NEGATE NOT OR OVER PICK + R> R@ ROLL ROT SWAP U< UM* UM/MOD XOR + + + Device layer + + BLOCK BUFFER CR EMIT EXPECT FLUSH KEY SAVE-BUFFERS + SPACE SPACES TYPE UPDATE + + + Interpreter layer + + # #> #S #TIB ' ( -TRAILING . .( <# >BODY >IN + ABORT BASE BLK CONVERT DECIMAL DEFINITIONS FIND + FORGET FORTH FORTH-83 HERE HOLD LOAD PAD QUIT SIGN + SPAN TIB U. WORD + + + Compiler layer + + +LOOP , ." : ; ABORT" ALLOT BEGIN COMPILE CONSTANT + CREATE DO DOES> ELSE IF IMMEDIATE LEAVE LITERAL LOOP + REPEAT STATE THEN UNTIL VARIABLE VOCABULARY WHILE [ + ['] [COMPILE] ] + + + + + + + + + + + + + + + + 27 + + + + + + 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}} See: "input stream" + + ' -- addr M,83 "tick" + Used in the form: + ' + addr is the compilation address of . An error + condition exists if is not found in the currently + active search order. + + ( -- I,M,83 "paren" + -- (compiling) + 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 ccc. ( may + be freely used while interpreting or compiling. The number + of characters in ccc may be 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. + + + + 28 + + + + + + 12. REQUIRED WORD SET + + + */ 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 {-32,768..32,767}. See: "division, + floored" + + */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 outside of the range {-32,768..32,767}. See: + "division, floored" + + + 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. + + + + + + 29 + + + + + + 12. REQUIRED WORD SET + + + ." -- 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 {-32,768..32,767}. + See: "division, floored" + + /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 + {-32,768..32,767}. See: "division, floored" + + 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 + operations 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 - . + + + + + 30 + + + + + + 12. REQUIRED WORD SET + + + 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: + : ... ; + Create a word definition for 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. is called a "colon + definition". The newly created word definition for + 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 ; . See: + "compilation" "9.4 Compilation" + + ; -- C,I,79 "semi-colon" + sys -- (compiling) + Stops compilation of a colon definition, allows the + 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 : "stack, + return" "9.4 Compilation" + + < n1 n2 -- flag 83 "less-than" + flag is true if n1 is less than n2. + -32678 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. + + + + + + + 31 + + + + + + 12. REQUIRED WORD SET + + + >BODY addr1 -- addr2 83 "to-body" + addr2 is the parameter field address corresponding to the + compilation address addr1. See: "9.2 Addressable Memory" + + >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. See "9.3 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. See: "arithmetic, two's complement" + + ALLOT w -- 79 + Allocates w bytes in the dictionary. The address of the + next available dictionary entry 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}} + + + + + + + + + + 32 + + + + + + 12. REQUIRED WORD SET + + + 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 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 . See: "9.9 Control + Structures" + + 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 "input stream" + + 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 the 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. + + + + + 33 + + + + + + 12. REQUIRED WORD SET + + + CMOVE> addr1 addr2 u -- 83 "c-move-up" + Move the 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: + : ... COMPILE ... ; + When is executed, the compilation address compiled + for is compiled and not executed. is + typically immediate and is typically not immediate. + See: "compilation" + + CONSTANT 16b -- M,83 + A defining word executed in the form: + 16b CONSTANT + Creates a dictionary entry for so that when 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 encounter. addr2 is the location + of the first unconvertible character. + + COUNT addr1 -- addr2 +n 79 + addr2 is addr1+1 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} See: "string, counted" + + 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 + Creates a dictionary entry for . After is + created, the next available dictionary location is the first + byte of 's parameter field. When is + subsequently executed, the address of the first byte of + 's parameter field is left on the stack. CREATE does + not allocate space in '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. + + + + 34 + + + + + + 12. REQUIRED WORD SET + + + DECIMAL -- 79 + Set the input-output numeric conversion base to ten. + + DEFINITIONS -- 79 + The compilation vocabulary is changed to be the same as the + first vocabulary in the search order. See: "vocabulary, + compilation" + + 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 65,536 times. sys is + balanced with its corresponding LOOP or +LOOP . See: "9.9 + Control Structures" + + 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: + : ... ... DOES> ... ; + and then + + where is CREATE or any user defined word which + executes CREATE . + + Marks the termination of the defining part of the defining + word and then begins the definition of the + execution-time action for words that will later be defined + by . When is later executed, the address of + '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. + + + + 35 + + + + + + 12. REQUIRED WORD SET + + + 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: + ; "stack, return" "9.3 Return Stack" + + EXPECT addr +n -- M,83 + Receive characters and store each into 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 the immediate attribute, + n is set to one. If the word is non-immediate, n is set to + minus one (true). + + + + + + + + 36 + + + + + + 12. REQUIRED WORD SET + + + 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 + If is found in the compilation vocabulary, delete + from the dictionary and all words added to the + dictionary after regardless of their vocabulary. + Failure to find is an error condition. An error + condition also exists if the compilation vocabulary is + deleted. See: "10.2 General Error Conditions" + + 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 + + + + + + + + + + + + + + + + + + 37 + + + + + + 12. REQUIRED WORD SET + + + 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, the words from IF through ELSE , or from + IF through THEN (when no ELSE is used), are skipped. sys is + balanced with its corresponding ELSE or THEN . See: "9.9 + Control Structures" + + 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. See: "9.3 Return Stack" + + 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. + + + + + + + 38 + + + + + + 12. REQUIRED WORD SET + + + 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 corresponding 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 {-32,768..32,767}. See: "division, + floored" + + 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. + + + + + 39 + + + + + + 12. REQUIRED WORD SET + + + 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 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. See: "9.3 Return 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 + corresponding 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 vacated 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. + + + + + + + 40 + + + + + + 12. REQUIRED WORD SET + + + 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 a 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. + + + + + + + + + 41 + + + + + + 12. REQUIRED WORD SET + + + 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..65,535}. See: "floor, arithmetic" + + 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 + A dictionary entry for is created and two bytes are + ALLOTted 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 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 + A dictionary entry for is created which specifies a + new ordered list of word definitions. Subsequent execution + of replaces the first vocabulary in the search order + with . When becomes the compilation vocabulary + new definitions will be appended to 's list. See: + DEFINITIONS "search order" + + + + + + + + + + + + + + + 42 + + + + + + 12. REQUIRED WORD SET + + + 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 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. See: "input stream" + + 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: + ['] + Compiles the compilation address addr of as a + literal. When the colon definition is later executed addr + is left on the stack. An error condition exists if + is not found in the currently active search order. See: + LITERAL + + + + + + 43 + + + + + + 12. REQUIRED WORD SET + + + [COMPILE] -- C,I,M,79 "bracket-compile" + -- (compiling) + Used in the form: + [COMPILE] + Forces compilation of the following word . This + allows compilation of an immediate word when it would + otherwise have been executed. + + ] -- 79 "right-bracket" + Sets compilation state. The text from the input stream is + subsequently compiled. For typical usage see LITERAL . + See: [ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 44 + + + + + + 13. DOUBLE NUMBER EXTENSION WORD SET + + + + + 13. DOUBLE NUMBER EXTENSION WORD SET + + + + 13.1 The Double Number Extension Word Set Layers + + + Nucleus layer + + 2! 2@ 2DROP 2DUP 2OVER 2ROT 2SWAP D+ D- D0= D2/ + D< D= DABS DMAX DMIN DNEGATE DU< + + + Device layer + + none + + + Interpreter layer + + D. D.R + + + Compiler layer + + 2CONSTANT 2VARIABLE + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 45 + + + + + + 13. DOUBLE NUMBER EXTENSION WORD SET + + + + + + 13.2 The Double Number Extension Word Set Glossary + + 2! 32b addr -- 79 "two-store" + 32b is stored at addr. See: "number" + + 2@ addr -- 32b 79 "two-fetch" + 32b is the value at addr. See: "number" + + 2CONSTANT 32b -- M,83 "two-constant" + A defining word executed in the form: + 32b 2CONSTANT + Creates a dictionary entry for so that when 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 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 + A dictionary entry for is created and four bytes are + ALLOTted 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 is later executed, the + address of its parameter field is placed on the stack. See: + VARIABLE + + D+ wd1 wd2 -- wd3 79 "d-plus" + 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. + + + + 46 + + + + + + 13. DOUBLE NUMBER EXTENSION WORD SET + + + 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. See: "number conversion" + + 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-than" + 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 -2,147,483,648 then + ud is the same value. See: "arithmetic, two's complement" + + 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 "d-negate" + 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. + + + + + + + + + + + + + + + + + + + + + + 47 + + + + + + 14. ASSEMBLER EXTENSION WORD SET + + + + + 14. ASSEMBLER EXTENSION WORD SET + + + + 14.1 The Assembler Extension Word Set Layers + + + Nucleus layer + + none + + + Device layer + + none + + + Interpreter layer + + ASSEMBLER + + + Compiler layer + + ;CODE CODE END-CODE + + + 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 . + + + + + + + + + + + + + + + + + + + + + + + + + 48 + + + + + + 14. ASSEMBLER EXTENSION WORD SET + + + + + + 14.3 The Assembler Extension Word Set Glossary + + ;CODE -- C,I,79 "semi-colon-code" + sys1 -- sys2 (compiling) + Used in the form: + : ... ... ;CODE ... END-CODE + Stops compilation, terminates the defining word and + executes ASSEMBLER. When is executed in the form: + + to define the new , the execution address of + will contain the address of the code sequence following the + ;CODE in . Execution of any 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 -- 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 ... END-CODE + Creates a dictionary entry for to be defined by a + following sequence of assembly language words. Words thus + defined are called code definitions. This newly created + word definition for 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 of the + corresponding code definition to be found in the dictionary. + sys is balanced with its corresponding CODE or ;CODE . See: + CODE + + + + + + + + + + + + + + + + + + + 49 + + + + + + 15. THE SYSTEM EXTENSION WORD SET + + + + + 15. THE SYSTEM EXTENSION WORD SET + + + + 15.1 The System Extension Word Set Layers + + + Nucleus layer + + BRANCH ?BRANCH + + + Device layer + + none + + + Interpreter layer + + CONTEXT CURRENT + + + Compiler layer + + MARK >RESOLVE + + + 15.2 System Extension Word Set Usage + + After BRANCH or ?BRANCH is compiled, >MARK or MARK is passed to >RESOLVE . The + addr left by MARK ; IMMEDIATE + : THEN >RESOLVE ; IMMEDIATE + + + + + + + + + + + + + + + + + + + + + + 50 + + + + + + 15. THE SYSTEM EXTENSION WORD SET + + + + + + 15.3 The System Extension Word Set Glossary + + 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 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. + + + + + + + + + + 51 + + + + + + 16. CONTROLLED REFERENCE WORDS + + + + + 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" + -- (compilation) + 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. See: "number conversion" + + 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 starting 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" + Unassign all block buffers. UPDATEed blocks are not written + to mass storage. See: BLOCK + + + + + + + 52 + + + + + + 16. CONTROLLED REFERENCE WORDS + + + 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. See: "input stream" + + 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 "input stream" + + 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. + + + + 53 + + + + + + 16. CONTROLLED REFERENCE WORDS + + + 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 then 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. See: "number + conversion" + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 54 + + + + + + A. STANDARDS TEAM MEMBERSHIP + + + + + APPENDIX A. STANDARDS TEAM MEMBERSHIP + + + + A.1 Standard Team Membership: Members + + The following is a list in alphabetical order of the people who + are FORTH Standards Team Members. These names are provided to + indicate the texture and make-up of the team itself. Where + appropriate, the official capacity of individuals is also + indicated. + + Paul Bartholdi, Sauverny, Switzerland + Robert Berkey, Palo Alto, California USA Treasurer + David Boulton, Redwood City, California USA + John Bumgarner, Morgan Hill, California USA + Don Colburn, Rockville, Maryland USA + James T. Currie, Jr., Blacksburg, Virginia USA + Thomas B. Dowling, Lowell, Massachusetts USA + William S. Emery, Malibu, California USA + Lawrence P. Forsley, Rochester, New York USA + Kim R. Harris, Palo Alto, California USA Referee + John S. James, Los Gatos, California USA + Guy M. Kelly, La Jolla, California USA Chair + Thea Martin, Rochester, New York USA + Michael McNeil, Scotts Valley, California USA + Robert E. Patten, Modesto, California USA + Michael Perry, Berkeley, California USA + David C. Petty, Cambridge, Massachusetts USA + William F. Ragsdale, Hayward, California USA + Elizabeth D. Rather, Hermosa Beach, California USA + Dean Sanderson, Hermosa Beach, California USA Referee + Klaus Schleisiek, Hamburg, W-Germany + George W. Shaw II, Hayward, California USA Referee + Robert L. Smith, Palo Alto, California USA Secretary + Michael K. Starling, Elkview, West Virginia USA + John K. Stevenson, Portland, Oregon USA + Glenn S. Tenney, San Mateo, California USA Referee + + + + + + + + + + + + + + + + + + 55 + + + + + + A. STANDARDS TEAM MEMBERSHIP + + + + + + A.2 FORTH Standards Team Sponsors + + The following is a list in alphabetical order of individuals and + organizations who have contributed funds and other assistance to + aid the word of the FST and deserve recognition for their + involvement. FST sponsors have no duties or responsibilities in + the FST, but they receive copies of proposals and comments + considered at a formal meeting, and drafts and adopted standards + prepared as a result of that meeting. + + Creative Solutions Inc., 4801 Randolph Rd., Rockville, MD 20852 + USA + + Fantasia Systems Inc., 1059 Alameda de las Pulgas, Belmont, CA + 94002 USA + + FORTH, Inc., 2309 Pacific Coast Highway, Hermosa Beach, CA 90254 + USA + + FORTH Interest Group Inc., P.O. Box 1105, San Carlos, CA 94070 + USA + + Forthright Enterprises, P.O. Box 50911, Palo Alto, CA 94020 USA + + Glen Haydon Enterprises, Box 439 Rt. 2, La Honda, CA 94020 USA + + John K. Gotwals, W. Lafayette, IN USA + + John D. Hall, Oakland, CA USA + + Hartronix, Inc., 1201 N. Stadem, Tempe, AZ 85281 USA + + Hewlett-Packard Corvallis Div., 1000 NE Circle Blvd., Corvallis, + OR 97330 USA + + Information Unlimited Software, Inc., 2401 Marinship, Sausalito, + CA 94965 USA + + Henry H. Laxen, 1259 Cornell Avenue, Berkeley, CA 94705 USA + + Laxen & Harris, Inc. + + George B. Lyons, 280 Henderson Street, Jersey Cit, NJ 07302 USA + + C. Kevin McCabe, Chicago, IL USA + + MicroMotion, 12077 Wilshire Blvd #506, Los Angeles, CA 90025 USA + + Bruce R. Montague, Monterey, CA USA + + Mountain View Press, P.O. Box 4659, Mountain View, CA 94040 USA + + + + 56 + + + + + + A. STANDARDS TEAM MEMBERSHIP + + + Michael A. Perry, Berkeley, CA USA + + Robert Berkey Services, 2334 Dumbarton Ave., Palo Alto, CA 94303 + USA + + Royal Greenwich Observatory, Herstmonsioux Castle, Eastbourne, + England + + Shaw Laboratories, Ltd., 24301 Southland Drive #216, Hayward, CA + 94545 USA + + Sygnetron Protection Systems, Inc., 2103 Greenspring, Timonium, + MD 21093 USA + + Telelogic Inc., 196 Broadway, Cambridge, MA 02139 USA + + UNISOFT, P.O. Box 2644, New Carrollton, MD 20784 USA + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 57 + + + + + + B. UNCONTROLLED REFERENCE WORDS + + + + + APPENDIX B. UNCONTROLLED REFERENCE WORDS + + + The Uncontrolled Reference Word Set contains glossary definitions + which are included for public reference of words that have past + or present usage and/or are candidates for future + standardization. No recommendation is made that these words be + included in a system. + + No restrictions are placed on the definition or usage of + uncontrolled words. However, use of these names for procedures + differing from the given definitions is discouraged. + + !BITS 16b1 addr 16b2 -- "store-bits" + Store the value of 16b1 masked by 16b2 into the equivalent + masked part of the contents of addr, without affecting bits + outside the mask. + + ** n1 n2 -- n3 "power" + n3 is the value of n1 to the power n2. + + +BLOCK w -- u "plus-block" + u is the sum of w plus the number of the block being + interpreted. + + -' -- addr false "dash-tick" + -- true + Used in the form: + -' + Leave the parameter field of beneath zero (false) if + can be found in the search order; leave only true if + not found. + + -MATCH addr1 +n1 addr2 +n2 -- addr3 flag "dash-match" + Attempt to find the +n2-length text string beginning at + addr2 somewhere in the +n1-length text string beginning at + addr1. Return the last+1 address addr3 of the match point + and a flag which is zero if a match exists. + + -TEXT addr1 +n1 addr2 -- n2 "dash-text" + Compare two strings over the length +n1 beginning at addr1 + and addr2. Return zero if the strings are equal. If + unequal, return n2, the difference between the last + characters compared: addr1(i) - addr2(i). + + + + + + + + + + + + 58 + + + + + + B. UNCONTROLLED REFERENCE WORDS + + + /LOOP +n -- C,I "up-loop" + sys -- (compiling) + A do-loop terminating word. The loop index is incremented + by the positive value +n. If the unsigned magnitude of the + resultant index is greater than the limit, then the loop is + terminated, otherwise execution returns to the corresponding + DO . The comparison is unsigned magnitude. sys is balanced + with its corresponding DO . See: DO + + 1+! addr -- "one-plus-store" + Add one to the 16-bit contents at addr. + + 1-! addr -- "one-minus-store" + Subtract one from the 16-bit contents at addr. + + ;: -- addr C,I "semi-colon-colon" + Used to specify a new defining word: + : ... ;: ... ; + and then + + When is executed, it creates an entry for the new + word . Later execution of will execute the + sequence of words between ;: and ; , with the address of the + first (if any) parameters associated with on the + stack. + + ;S -- Interpret only "semi-s" + Stop interpretation of a block. + + <> w1 w2 -- flag "not-equal" + flag is true if w1 is not equal to w2. + + in defining words, in the + form: + : ... ... ; + and then + + When executes, . The sequence of words between established a parameter field for . When + is later executed, the sequence of words following + DOES> will be executed, with the parameter field address of + on the data stack. + + . + + >< 16b1 -- 16b2 "byte-swap" + Swap the high and low bytes within 16b1. + + + + + + + + 59 + + + + + + B. UNCONTROLLED REFERENCE WORDS + + + >MOVE< addr1 addr2 u -- "byte-swap-move" + Move u bytes beginning at addr1 to the memory beginning at + addr2. During this move, the order of each byte pair is + reversed. + + @BITS addr 16b1 -- 16b2 "fetch-bits" + Return the 16-bits at addr masked by 16b1. + + AGAIN -- C,I + sys -- (compiling) + Effect an unconditional jump back to the start of a BEGIN- + AGAIN loop. sys is balanced with its corresponding BEGIN . + See: BEGIN + + ASCII -- char I,M "as-key" + -- (compiling) + Used in the form: + ASCII ccc + where the delimiter of ccc is a space. char is the ASCII + character value of the first character in ccc. If + interpreting, char is left on the stack. If compiling, + compile char as a literal so that when the colon definition + is later executed, char is left on the stack. + + ASHIFT 16b1 n -- 16b2 "a-shift" + Shift the value 16b1 arithmetically n bits left if n is + positive, shifting zeros into the least significant bit + positions. If n is negative, 16b1 is shifted right; the + sign is included in the shift and remains unchanged. + + B/BUF -- 1024 "bytes-per-buffer" + A constant leaving 1024, the number of bytes per block + buffer. + + BELL -- M + Activate a terminal bell or noise-maker as appropriate to + the device in use. + + CHAIN -- M + Used in the form: + CHAIN + Connect the CURRENT vocabulary to all definitions that might + be entered into the vocabulary 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 + + CONTINUED u -- M + Continue interpretation at block u. + + + + + + + 60 + + + + + + B. UNCONTROLLED REFERENCE WORDS + + + CUR -- addr + A variable pointing to the physical record number before + which the tape is currently positioned. REWIND sets CUR=1. + + DBLOCK ud -- addr M "d-block" + Identical to BLOCK but with a 32-bit block unsigned number. + + DPL -- addr U "d-p-l" + A variable containing the number of places after the + fractional point for input conversion. + + FLD -- addr U "f-l-d" + A variable pointing to the field length reserved for a + number during output conversion. + + H. u -- M "h-dot" + Output u as a hexadecimal integer with one trailing blank. + The current base is unchanged. + + I' -- w C "i-prime" + Used within a colon definition executed only from within a + do-loop to return the corresponding loop index. + + IFEND Interpret only "if-end" + Terminate a conditional interpretation sequence begun by + IFTRUE . + + IFTRUE flag -- Interpret only "if-true" + Begin an: + IFTRUE ... OTHERWISE ... IFEND + conditional sequence. These conditional words operate + like: + IF ... ELSE ... THEN + except that they cannot be nested, and are to be used only + 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. + + INDEX u1 u2 -- M + Print the first line of each screen over the range {u1..u2}. + This displays the first line of each screen of source text, + which conventionally contains a title. + + LAST -- addr U + A variable containing the address of the beginning of the + last dictionary entry made, which may not yet be a complete + or valid entry. + + LINE +n -- addr M + addr is the address of the beginning of line +n for the + screen whose number is contained in SCR . The range of +n + is {0..15}. + + + + + + 61 + + + + + + B. UNCONTROLLED REFERENCE WORDS + + + LINELOAD +n u -- M "line-load" + Begin interpretation at line +n of screen u. + + LOADS u -- M + A defining word executed in the form: + u LOADS + When is subsequently executed, block u will be + loaded. + + MAP0 -- addr "map-zero" + A variable pointing to the first location in the tape map. + + MASK n -- 16b + 16b is a mask of n most-significant bits if n is positive, + or n least-significant bits if n is negative. + + MOVE addr1 addr2 u -- + The u bytes at address addr1 are moved to address addr2. + The data are moved such that the u bytes remaining at + address addr2 are the same data as was originally at address + addr1. If u is zero nothing is moved. + + MS +n -- M "m-s" + Delay for approximately +n milliseconds. + + NAND 16b1 16b2 -- 16b3 + 16b3 is the one's complement of the logical AND of 16b1 with + 16b2. + + NOR 16b1 16b2 -- 16b3 + 16b3 is the one's complement of the logical OR of 16b1 with + 16b2. + + NUMBER addr -- d + Convert the count and character string at addr, to a signed + 32-bit integer, using the value of BASE . If numeric + conversion is not possible, an error condition exists. The + string may contain a preceding minus sign. + + O. u -- M "o-dot" + Print u in octal format with one trailing blank. The value + in BASE is unaffected. + + OTHERWISE -- Interpret only + An interpreter-level conditional word. See: IFTRUE + + PAGE -- M + Clear the terminal screen or perform a form-feed action + suitable to the output device currently active. + + + + + + + + + 62 + + + + + + B. UNCONTROLLED REFERENCE WORDS + + + READ-MAP -- M "read-map" + Read to the next file mark on tape constructing a + correspondence table in memory (the map) relating physical + block position to logical block number. The tape should + normally be rewound to its load point before executing READ- + MAP . + + REMEMBER -- M + A defining word executed in the form: + REMEMBER + Defines a word which, when executed, will cause and + all subsequently defined words to be deleted from the + dictionary. may be compiled into and executed from a + colon definition. The sequence + DISCARD REMEMBER DISCARD + provides a standardized preface to any group of transient + word definitions. + + REWIND -- M + Rewind the tape to its load point, setting CUR equal to one. + + ROTATE 16b1 n -- 16b2 + Rotate 16b1 left n bits if n is positive, right n bits if n + is negative. Bits shifted out of one end of the cell are + shifted back in at the opposite end. + + S0 -- addr U "s-zero" + A variable containing the address of the bottom of the + stack. + + SET 16b addr -- M + A defining word executed in the form: + 16b addr SET + Defines a word which, when executed, will cause the + value 16b to be stored at addr. + + SHIFT 16b1 n -- 16b2 + Logical shift 16b1 left n bits if n is positive, right n + bits if n is negative. Zeros are shifted into vacated bit + positions. + + TEXT char -- M + Accept characters from the input stream, as for WORD , into + PAD , blank-filling the remainder of PAD to 84 characters. + + USER +n -- M + A defining word executed in the form: + +n USER + which creates a user variable . +n is the offset + within the user area where the value for is stored. + Execution of leaves its absolute user area storage + address. + + + + + + 63 + + + + + + B. UNCONTROLLED REFERENCE WORDS + + + WORDS -- M + List the word names in the first vocabulary of the currently + active search order. + + \LOOP +n -- C,I "down-loop" + sys -- (compiling) + A do-loop terminating word. The loop index is decremented + by the positive value +n. If the unsigned magnitude of the + resultant index is less than or equal to the limit, then the + loop is terminated, otherwise execution returns to the + corresponding DO . The comparison is unsigned. sys is + balanced with its corresponding DO . See: DO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 64 + + + + + + C. EXPERIMENTAL PROPOSALS + + + + + APPENDIX C. EXPERIMENTAL PROPOSALS + + + Since FORTH is an extensible language and subject to evolution, + the Standard contains a section describing experimental + proposals. FORTH users are encouraged to study, implement, and + try these proposals to aid in the analysis of and the decision + for or against future adoption into the Standard. Readers are + cautioned that these proposals contain opinions and conclusions + of the authors of the proposals and that these proposals may + contain non-standard source code. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 65 + + + + + + C. EXPERIMENTAL PROPOSALS + + + + + + + SEARCH ORDER SPECIFICATION AND CONTROL + + + WILLIAM F. RAGSDALE + + + 1 INTRODUCTION + + The method of selecting the order in which the dictionary is + searched has grown from unchained vocabularies to the present use + of chained vocabularies. Many techniques are in use for + specification of the sequence in which multiple vocabularies may + be searched. In order to offer generality and yet get precision + in specification, this proposal is offered. + + + 2 DESCRIPTION + + The following functions are required: + + 1. Two search orders exist. CONTEXT is the group of + vocabularies searched during interpretation of text from the + input stream. CURRENT is the single vocabulary into which + new definitions are compiled, and from which FORGET + operates. + + 2. Empty CONTEXT to a minimum number of system words. These + are just the words to further specify the search order. + + 3. Add individual vocabularies into CONTEXT. The most recently + added is searched first. + + 4. Specify which single vocabulary will become CURRENT. + + The following optional functions aid the user: + + 1. Display the word names of the first vocabulary in the + CONTEXT search order. + + 2. Display the vocabulary names comprising CURRENT and CONTEXT + search orders. + + + + + + + + + + + + + 66 + + + + + + C. EXPERIMENTAL PROPOSALS + + + 3 ADVANTAGES + + Use over the past year has demonstrated that the proposed + methods may emulate the vocabulary selection of all other + systems. The order is explicit by execution, may be interpreted + and compiled, and is obvious from the declaration. The search + order is specified at run-time rather than the time a new + vocabulary is created. + + + 4 DISADVANTAGES + + By migrating to a common structure, vendors give up one + point at which they may claim their product is better than + others. Another drawback is that the number of CONTEXT + vocabularies is fixed; older methods had an indefinite 'tree' + structure. In practice, the branching of such a structure was + very rarely greater than four. + + Forth words operate in a context sensitive environment, as + word names may be redefined and have different definitions in + different vocabularies. This proposal compounds the problem. By + displaying the search order names, the user at least can readily + verify the search order. + + + 5 IMPACT + + The text of the Forth 83 Standard has been carefully chosen + for consistency and generality. However, no specification on how + the search order is developed by the user is given. This + omission is unavoidable, due to the diversity of contemporary + practice. This proposal is intended to complete the Forth 83 + requirements in a fashion that exceeds all other methods. + + Previously standardized words continue in their use: + VOCABULARY, FORTH, DEFINITIONS, and FORGET. However, this + proposal assumes that vocabulary names are not IMMEDIATE . + + + 6 DEFINITIONS + + Search order: + The sequence in which vocabularies are selected when + locating a word by name in the dictionary. Consists of one + transient and up to three resident vocabularies. + + Transient order: + Execution of any vocabulary makes it the first vocabulary + searched, replacing the previously selected transient + vocabulary. + + + + + + + 67 + + + + + + C. EXPERIMENTAL PROPOSALS + + + Resident order: + After searching the transient order, up to three additional + vocabularies may be searched. The application program + controls this selection. + + + 7 GLOSSARY + + ONLY -- ONLY + Select just the ONLY vocabulary as both the transient + vocabulary and resident vocabulary in the search order. + + FORTH -- ONLY + The name of the primary vocabulary. Execution makes FORTH + the transient vocabulary, the first in the search order, and + thus replaces the previous transient vocabulary. + + ALSO -- ONLY + The transient vocabulary becomes the first vocabulary in the + resident portion of the search order. Up to the last two + resident vocabularies will also be reserved, in order, + forming the resident search order. + + ORDER -- ONLY + Display the vocabulary names forming the search order in + their present search order sequence. Then show the + vocabulary into which new definitions will be placed. + + WORDS -- ONLY + Display the word names in the transient vocabulary, starting + with the most recent definition. + + FORGET -- ONLY + Used in the form: + FORGET + Delete from the dictionary and all words added to the + dictionary after regardless of the vocabulary. + Failure to find is an error condition. An error + condition also exists upon implicitly forgetting a + vocabulary (due to its definition after ). + + DEFINITIONS -- ONLY + Select the transient vocabulary as the current vocabulary + into which subsequent definitions will be added. + + SEAL -- ONLY + Delete all occurances of ONLY from the search order. The + effect is that only specified application vocabularies will + be searched. + + + + + + + + + 68 + + + + + + C. EXPERIMENTAL PROPOSALS + + + 8 TYPICAL SOURCE CODE + + 0 ( ALSO ONLY 82jun12 WFR ) + 1 ( note the systems -FIND searches 1 to 5 vocabs in CONTEXT ) + 2 VOCABULARY ONLY ONLY DEFINITIONS + 3 : ALSO ( slide transient into resident ) + 4 CONTEXT DUP 2+ 6 CMOVE> ; + 5 + 6 HERE 2+ ] ( alter run time from usual vocabulary ) + 7 DOES> CONTEXT 8 ERASE DUP CONTEXT ! CONTEXT 8 + ! + 8 ALSO EXIT [ + 9 ' ONLY CFA ! ( Patch into ONLY; make NULL word ) + 10 CREATE X ' EXIT >BODY X ! 41088 ' X NFA ! IMMEDIATE + 11 : FORTH FORTH ; + 12 : DEFINITIONS DEFINITIONS ; : FORGET FORGET ; + 13 : VOCABULARY VOCABULARY ; : ONLY ONLY ; + 14 : WORDS WORDS ; + 15 + + 0 ( ORDER 82jun12 WFR ) + 1 : ORDER ( show the search order ) + 2 10 SPACES CONTEXT 10 OVER + SWAP + 3 DO I @ ?DUP 0= ?LEAVE ID. 2 +LOOP + 4 10 SPACES CURRENT @ ID. ; + 5 + 6 ONLY FORTH ALSO DEFINITIONS + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + + + 9 EXAMPLES OF USE + + ONLY reduce search order to minimum + FORTH search FORTH then ONLY + ALSO EDITOR search EDITOR, FORTH then ONLY + DEFINITIONS new definitions will be added into the EDITOR + + The same sequence would be compiled: + + : SETUP ONLY FORTH ALSO EDITOR DEFINITIONS ; + + + 10 REFERENCES + + W. F. Ragsdale, The 'ONLY' Concept for Vocabularies, Proceedings + of the 1982 FORML Conference, pub. Forth Interest Group. + + + + + 69 + + + + + + C. EXPERIMENTAL PROPOSALS + + + W. F. Ragsdale, fig-FORTH Installation Manual, Forth Interest + Group. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 70 + + + + + + C. EXPERIMENTAL PROPOSALS + + + + + + + DEFINITION FIELD ADDRESS CONVERSION OPERATORS + + + by + + Kim R. Harris + + + A. INTRODUCTION + + The standard provides a transportable way to obtain the + compilation address of a definition in the dictionary of a FORTH + system (cf., FIND and ' ). It also provides an operator to + convert a compilation address to its corresponding parameter + field address. However, the standard does not provide a + transportable way to convert either of these addresses to the + other fields of a definition. Since various FORTH + implementations have different dictionary structures, a standard + set of conversion operators would increase transportability and + readability. + + A set of words is proposed which allows the conversion of any + definitions field address to any other. + + + B. GLOSSARY + + In the following words, the compilation address is either the + source or the destination, so it is not indicated in the names. + + >BODY addr1 -- addr2 "to-body" + addr2 is the parameter field address corresponding to the + compilation address addr1. + + >NAME addr1 -- addr2 "to-name" + addr2 is the name field address corresponding to the + compilation address addr1. + + >LINK addr1 -- addr2 "to-link" + addr2 is the link field address corresponding to the + compilation address addr1. + + BODY> addr1 -- addr2 "from-body" + addr2 is the compilation address corresponding to the + parameter field address addr1. + + NAME> addr1 -- addr2 "from-name" + addr2 is the compilation address corresponding to the name + field address addr1. + + + + + 71 + + + + + + C. EXPERIMENTAL PROPOSALS + + + LINK> addr1 -- addr2 "from-link" + addr2 is the compilation address corresponding to the link + field address addr1. + + The previous set of words is complete, but may be inefficient for + going between two fields when one is not the compilation address. + For greater efficiency, additional operators may be defined which + name both the source and destination fields. + + N>LINK addr1 -- addr2 "name-to-link" + addr2 is the link field address corresponding to the name + field address addr1. + + L>NAME addr1 -- addr2 "link-to-name" + addr2 is the name field address corresponding to the link + field address addr1. + + + C. DISCUSSION + + The previous words provide a complete, consistent, and efficient + set of definition field address conversion operations. They can + be implemented in a FORTH system which uses any combination of + the following options for its dictionary structure: + + Link fields first or second. + Fixed or variable length name fields. + Additional fields in the definitions structure. + + Heads contiguous or separated from bodies. + + Indirect, direct, subroutine, or token threaded code. + + The words are compatible with this standard; their inclusion + would not require other changes to be made to the standard. + + Disadvantages to including them in the standard include: + + They add 6 to 8 more words to the standard. + + A standard program may not use all of them since it is not + allowed to access the name or link fields. However, this + does not disqualify them from being in the standard. + + If a definition's head is not in the dictionary, an error + condition would exist. In this case, what action should the + words take in an implemented system? + + The author of this experimental proposal recommends that FORTH + system implementors try them and that they be included in the + System Word Set of the next FORTH standard. + + + + + + + 72 + + + + + + C. EXPERIMENTAL PROPOSALS + + + D. SOURCE CODE EXAMPLE + + High level source code is shown below for a very simple + dictionary structure. This code assumes a FORTH system which + uses indirect threaded code, heads contiguous to bodies, and a + definition structure of the following format: + + Name field, 4 bytes long, fixed length. + Link field, 2 bytes long. + Code field, 2 bytes long. + Parameter field, variable length. + + : >BODY ( acf -- apf ) 2+ ; + : BODY> ( apf -- acf ) 2- ; + : >LINK ( acf -- alf ) 2- ; + : LINK> ( alf -- acf ) 2- ; + : >NAME ( acf -- anf ) 6 - ; + : NAME> ( anf -- alf ) 6 + ; + : N>LINK ( anf -- alf ) 4 + ; + : L>NAME ( alf -- anf ) 4 - ; + + + E. EXAMPLES OF USE + + No examples are given because their use should be obvious. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 73 + + + + + + D. CHARTER + + + + + APPENDIX D. + + + CHARTER + + of the + + FORTH STANDARDS TEAM + + + + 1. Purpose and Goals + + + 1.1 Purpose + + 1.1.1 This Charter establishes and guides a voluntary + membership professional organization, the FORTH Standards + Team (hereafter referred to as the "FST") and provides a + method for its operation. + + + 1.2 Goals + + 1.2.1 The goal of the FST is the creation, maintenance, and + proliferation of a standard (hereafter referred to as the + "Standard") for the FORTH computer programming system and + for application programs executed by a Standard system. The + Standard shall specify requirements and constraints which + such computer software must satisfy. + + 1.2.2 The team shall also develop a method of + identification and labeling of FORTH implementations and + programs which conform to the Standard. + + + 1.3 Organization + + 1.3.1 The FST is a voluntary membership organization with + no formal status as a legal entity. It operates by + consensus of the professional and commercial FORTH community + and conducts business by the professional discourse and + agreement of its members. It is intended that this Charter + be a guide to the operation of the FST subject to reasonable + minor digression, rather than being a rigid document under + which vested rights are granted. + + + + + + + + + + 74 + + + + + + D. CHARTER + + + 2. METHODS + + + 2.1 Formal Meetings + + 2.1.1 The FST shall hold periodic formal meetings for + discussion and decisions concerning a current or future + Standard. + + 2.1.2 There is not specified frequency for formal meetings. + Each meeting shall be at such time and place as was decided + at the prior meeting. If a meeting cannot be held as + decided, the Chairperson may designate another time and + place. + + 2.1.3 The Chairperson shall send a written notice at least + sixty (60) days in advance of each formal meeting to each + voting member. A longer notification period is recommended. + It is anticipated that the continuing close coordination of + the participants, the decision at the prior formal meeting, + and publication of a meeting notice in FORTH Dimensions and + other trade journals will provide sufficient notice to the + FORTH community. + + 2.1.4 At a formal FST meeting, there shall be general + sessions consisting of all attendees. General sessions are + for matters that are ready for discussion and decision. All + votes concerning the Standard, Charter, or FST procedures + must take place during a general session. + + 2.1.5 Also at formal meetings, subteams will be established + to examine groups of proposals and to prepare + recommendations for a general session. All meeting + attendees may participate in the work and voting of a + subteam. Each subteam should elect from its members a + coordinator to conduct its meetings and a reporter to record + and report its recommendations. + + 2.1.6 The Chairperson may publish and distribute an agenda + at or in advance of a formal meeting. As a guideline, each + day of a formal meeting begins with a general session, + followed by concurrent subteam meetings followed by another + general session. + + 2.1.7 In view of the voluntary nature of the FST, at least + one third of the membership is required to hold a formal + meeting. Two thirds of the number of voting members present + at the start of each day's first general session shall set + the quorum for the remainder of that day. + + + + + + + + + 75 + + + + + + D. CHARTER + + + 2.1.8 Between formal meetings, the Chairperson may appoint + such informal working groups as is appropriate. Each group + may be given a goal and scope to direct its activities. Its + conclusions or recommendations must be given to the + Chairperson in written form. + + + 2.2 Proposals and Comments + + 2.2.1 Prior to each formal meeting, the Chairperson may + solicit submission of comments and proposals for changes, + additions, or deletions to the then-current Standard, the + draft Standard or this Charter. A cutoff date may be + specified for the submission of such proposals. + + 2.2.2 A considerable amount of information must accompany + each proposal to help FST members analyze the proposal. + Therefore, submission of proposals and comments shall be + according to the format and instructions shown in the + "Proposal/Comment Form" included as an Appendix to this + Standard. Any proposal not in the appropriate form or + received after the cutoff date may not be considered unless + the Chairperson deems it to be of sufficient significance. + + 2.2.3 Unsolicited proposals and comments by volunteers are + acknowledged as valuable. Any individual or group may + submit proposals and/or comments concerning the Standard or + this Charter. These should be sent to the official address + of the FST. Properly formatted proposals and comments are + preferred. The author or a representative should plan to + attend the next formal meeting to emphasize, support, and + possibly modify the proposals. + + 2.2.4 Since the quantity of proposals and comments may + exceed the number for which there is time to be voted upon, + submission of a proposal does not automatically mean that it + will be voted upon at the next formal FST meeting. The + Chairperson or some members appointed by the Chairperson or + elected by the voting members may screen and organize the + received proposals and comments for voting upon at the next + formal meeting. + + 2.2.5 To allow reflection and examination, proposals and + comments shall be distributed to FST voting members and + sponsors in advance of a formal meeting. Proposals and + comments not distributed in advance, including proposals + made during a formal meeting, may be considered at the + discretion of the Chairperson. + + + + + + + + + + 76 + + + + + + D. CHARTER + + + 2.3 Draft Standard + + After a formal meeting, the referees and officers of the FST + shall prepare a draft Standard for review by the then- + current FST voting members. The referees and officers shall + consolidate proposals accepted by vote during the meeting, + resolve any ambiguities or problems, and incorporate these + changes with the text of the previous Standard or draft + Standard. + + + 2.4 Standard + + 2.4.1 The referees and officers may, by near unanimous + decision (not more than one no vote), declare the draft + Standard, as mentioned in the previous paragraph, as being + the proposed Standard. + + 2.4.2 A proposed Standard shall be distributed to all FST + voting members for a mail ballot. This ballot shall be + based solely on the text of the proposed Standard as + distributed. + + 2.4.3 Each ballot returned shall be signed by the voting + member submitting it. An affirmative vote of at least two + thirds of the voting members shall adopt the document. Such + adoption makes the draft Standard the current, official FST + Standard which supersedes all prior Standards. + + + 2.5 Charter + + 2.5.1 At a formal FST meeting, the charter may be amended + by a simple majority of voting members present provided that + at least one third of all voting members are present; such + amendments become effective at the end of the current formal + meeting. + + 2.5.2 At other than a formal FST meeting, the charter may + be amended by a simple majority of all voting members, such + vote to be taken by signed mail ballots. + + + + + + + + + + + + + + + + + 77 + + + + + + D. CHARTER + + + 3. MEMBERSHIP + + + 3.1 General + + Membership in the FST is a privilege, not a right. An + invitation for voting membership may be extended to those + who the FST feels can contribute to the goals of the + Standard and the FST. There are several classes of + participation in the efforts of the FST. Membership in each + class has no specified term but continues from the time when + membership is initiated to the conclusion of the next formal + meeting. + + + 3.2 Voting Members + + 3.2.1 Voting members are individuals who are elected into + such membership at the concluding session of a formal FST + meeting. Any voting member who resigns between formal + meetings shall not be replaced until the membership + elections at the conclusion of the next formal meeting. A + newly elected voting member gains voting rights only after + all voting members have been elected. A significant + professional FORTH background is required of voting members. + + 3.2.2 Each voting member present at a formal meeting shall + indicate in writing his or her desire to continue as a + voting member. Only these voting members can vote in a + general session of a formal meeting on any matters affecting + the Standard or the Charter and on the election of all + voting members. + + 3.2.3 Voting members are elected by a simple majority of + those voting members present. The number of voting members + shall be limited to thirty (30). Individuals eligible to be + elected are selected from each of the following ordered + categories in order, until the number of voting members + reaches the limit. + + 3.2.3.1 Category 1: current voting member who have + actively participated in at least two days of a formal + meeting. Voting members are expected to actively + participate in subteam meetings and all general + sessions. + + 3.2.3.2 Category 2: current voting members who are + not eligible by Category 1, but who have requested in + writing that his or her voting membership be + maintained. + + 3.2.3.3 Category 3: eligible candidates. Eligible + candidates will be presented to the voting members then + elected as follows: + + + + 78 + + + + + + D. CHARTER + + + 3.2.3.3.1 If the number of eligible candidates + does not exceed the number of openings for voting + membership, each candidate is voted upon and + accepted by a simple majority. + + 3.2.3.3.2 If the number of eligible candidates + does exceed the number of openings for voting + membership, candidates will be voted upon by + ballot whereby each voting member may vote for up + to the number of openings remaining. Those + candidates receiving the most votes will be + elected until there are no more openings for + voting membership. + + + 3.3 Candidates + + 3.3.1 Candidates are individuals who desire to actively + participate in and support the FST by becoming voting + members. + + 3.3.2 To be eligible, each Candidate must: declare in + writing to the secretary at the first general session of a + formal FST meeting that he or she is a Candidate, actively + participate in subteam meetings and all general sessions at + a formal FST meeting, and have a significant professional + background in FORTH. The Chairperson may request + information or ask questions of any candidate to determine + his or her technical knowledge and experience. Candidates + are expected to submit proposals, participate in the + discussions of the formal meeting, and contribute to the + work and voting of subteams. + + + 3.4 Observers + + 3.4.1 Observers are individuals who attend a formal meeting + but are neither voting members nor candidates. At the + discretion of the Chairperson, they may contribute to the + discussion at general sessions and to the work of subteams. + The number of observers allowed at a formal meeting may be + limited by the Chairperson. + + + 3.5 FST Sponsors + + 3.5.1 FST sponsors are individuals or organizations who + contribute funds and other assistance to aid the work of the + FST. FST sponsors have no duties or responsibilities in the + FST, but they will receive copies of proposals and comments + considered at a formal meeting, and drafts and adopted + standards prepared as a result of that meeting. + + + + + + 79 + + + + + + D. CHARTER + + + 3.5.2 FST sponsorship exists from the end of one formal + meeting to the end of the next formal meeting. + + 3.5.3 Qualification of FST sponsors may be determined by a + simple majority vote at a formal FST meeting. If no such + qualification exist, the Chairperson may specify + qualifications, including the amount of financial + contributions, which will remain in effect until the next + formal FST meeting. + + + 4. OFFICERS + + + 4.1 General + + There shall be four types of elected officers of the FST: + the Chairperson, the Secretary, the Treasurer, and one or + more Referees. Each officer shall be elected at a formal + meeting of the FST and serve until the next formal meeting. + + + 4.2 Vacancies + + If any office other than the Chairperson becomes vacant + between formal meetings, the Chairperson may appoint a + replacement. If the office of the Chairperson becomes + vacant between formal meetings, a new Chairperson shall be + elected by an informal majority vote of the remaining + officers. At any formal meeting, any officer, including the + Chairperson, may be replaced by a simple majority vote of + the voting members present at that meeting. + + + 4.3 Chairperson + + 4.3.1 The Chairperson is responsible for governing the + general business of the FST. He or she is responsible for + implementing the FST's Charter and any other requirements + specified by the Standard. + + 4.3.2 The Chairperson's term of office shall be from the + conclusion of the formal meeting at which he or she is + elected to the conclusion of the next formal meeting. The + election of a Chairperson is held at the concluding general + session of a formal meeting after the election of voting + members; hence, newly elected voting members may vote for + the Chairperson. Only voting members are eligible to be + elected Chairperson. + + 4.3.3 The Chairperson shall conduct each formal meeting. + In general, the meetings will follow the current Robert's + Rules of Order; however, the Chairperson may determine the + specific rules for a formal meeting. + + + + 80 + + + + + + D. CHARTER + + + 4.3.4 Any matter needing a decision between formal meetings + not specified by this Charter shall be decided by the + Chairperson. + + 4.3.5 The Chairperson has duties and responsibilities + specified elsewhere in this Charter. + + + 4.4 Secretary + + 4.4.1 The Secretary is responsible for recording the + activities and results of the FST. + + 4.4.2 The Secretary is elected at the first general session + of a formal meeting and serves until a Secretary is elected + at the beginning of the next formal meeting. + + 4.4.3 The Secretary has many responsibilities. + + 4.4.3.1 The Secretary is responsible for collecting, + maintaining, and archiving the official copies of the + Standard, the Charter, all other FST documents, + correspondence, and lists of the FST members of each class. + + 4.4.3.2 During a formal meeting, the Secretary is + responsible for: + + (a) Keeping the minutes of the general sessions, + including all votes taken. For votes affecting the + Standard or Charter, he or she shall: record the + number of voting members present, determine if a quorum + is present, determine the number of affirmative votes + required for the vote to pass, the number of voting + members voting in the affirmative and negative, and the + result of the vote. + + (b) Recording and verifying the attendance and + membership class of each attendee. + + (c) Recording the recommendations of subteams. + + 4.4.3.3 The Secretary is also responsible for collecting, + archiving, and distributing proposals before a formal + meeting. He or she is also responsible for incorporating + proposals accepted during a formal meeting into the Standard + or Charter. Other officers aid the Secretary in these + duties. + + 4.5 Treasurer + + 4.5.1 The Treasurer is responsible for managing the + financial business of the FST. He or she is responsible for + maintaining accurate and current financial records and for + accepting and dispersing funds for official FST activities. + + + + 81 + + + + + + D. CHARTER + + + 4.5.2 The Treasurer's term of office shall be from the + conclusion of the formal meeting at which he or she is + elected to the conclusion of the next formal meeting. The + election of a Treasurer is held just after the election of + the Chairperson. Only voting members are eligible to be + elected Treasurer. + + + 4.6 Referees + + 4.6.1 At the conclusion of a formal meeting there may be + additional technical work required to prepare a draft + Standard or Charter. This work shall be performed by the + officers of the FST, including a group of Referees. They + should be individuals who have superior knowledge and + experience in the implementation and use of FORTH. + + 4.6.2 At least three and no more than five Referees shall + be elected by a majority of the voting members present at + the concluding general sessions of a formal meeting. This + takes place after the election of voting members. A + Referee's term is from election at the end of one formal + meeting until the end of the next formal meeting. Only + voting members are eligible to be elected as Referees. + + 4.6.3 The Referees shall adopt methods and rules as they + deem appropriate to complete their work; they may be + informal. However, any matter committed to the Referees for + resolution must achieve near unanimous agreement (not more + than one no vote). Lacking that, the matter shall be + omitted from further action pending further consideration at + the next formal meeting. + + + 5. EXPERIMENTAL PROPOSALS + + + 5.1 General + + 5.1.1 Since FORTH is an extensible language and subject to + evolution, the Standard may contain a section describing + experimental proposal to aid in the analysis of and the + decision for or against future adoption into the Standard. + After the results of experimentation are known, each + proposal will be considered, at a future formal meeting, for + inclusion into the Standard. + + 5.1.2 An experimental proposal may be individual FORTH + words, sets of related words, or specifications for part of + the Standard. Experimental proposals may be derived from + ordinary proposals or other contributions. + + + + + + + 82 + + + + + + D. CHARTER + + + 5.2 Required Information + + Each experimental proposal must contain the following + minimum information: + + 5.2.1 A description of the proposal including an overview + of its functions and its interactions with existing FORTH + words. + + 5.2.2 A glossary entry of each word in the form and + notation of the Standard. + + 5.2.3 A statement by the author(s) indicating why the + proposal meets inclusion into the Standard. Both advantages + and disadvantages should be discussed. + + + 5.3 Suggested Information + + It is suggested that each experimental proposal also + include: + + 5.3.1 A source definition for each word in the proposal. + High level definitions using Standard words are preferred, + but new primitive words may be defined in an assembly + language of one commonly-known processor. Sufficient + documentation should be provided so that implementation on + other processors is direct. + + 5.3.2 An example showing usage of the new words. + + + 6. VOTING + + + 6.1 General + + Only voting members have the right to vote on proposals + affecting the Standard, a draft Standard, or this Charter. + + + 6.2 Advisory Votes + + At the discretion of the Chairperson, advisory votes may be + requested at a formal meeting. At the discretion of the + Chairperson, all attendees may participate in an advisory + vote. + + + 6.3 Method + + Any vote at a formal meeting may be by show of hands or, at + the discretion of the Chairperson, by an informal secret + paper ballot or a roll call. + + + + 83 + + + + + + D. CHARTER + + + 6.4 Number + + A vote to adopt a proposal into the draft Standard or to + change the Standard, except for the Experimental Proposals + section of the Standard requires a two-thirds affirmative + vote of the voting members present at a general session of a + formal meeting, provided that the number of votes cast are + at least two thirds of that morning's quorum count. To + adopt an experimental proposal into the Experimental + Proposals section of the draft Standard or to change this + Charter, an affirmative vote of a simple majority is + required. Accepting any other procedural matter at a formal + meeting requires only a simple majority affirmative vote. + + + 6.5 Proxies + + All votes must be cast by the particular voting member + eligible to vote. No proxy voting is allowed. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 84 + + + + + + E. PROPOSAL/COMMENT FORM + + + + + APPENDIX E. PROPOSAL/COMMENT FORM + + + The following pages are the proposal and/or comment submittal + form. The form includes instructions which should be + explanatory. Copies of submitted proposals and comments will be + made available to FORTH Standards Team members and to team + sponsors. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 85 + + + + + + + + + + FST Proposal and Comment Submittal Form + ----------------------------------------------------------------- + FST USER Title: Proposal Number: + ONLY --> Related Proposals: Disposition: + ================================================================= + Keyword(s): Category: + ( ) Proposal or ( ) Comment + FORTH Word(s): Section #(s): + ----------------------------------------------------------------- + Abstract: + + + + + + + ----------------------------------------------------------------- + Proposal and Discussion: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ---------------------------------------------------------------- + Submitted by: Date: + Page of + ================================================================= + FORTH Standards Team; PO Box 4545; Mountain View, CA 94040 820801 + + + + 86 + + + + + + + + + + + Proposal and Comment Submittal Form Instructions + + Please use the supplied forms for your entire proposal. The + continuation form is only to be used if absolutely necessary; try + to get your proposal to fit on the first sheet. If it helps, use + a reducing copy machine to get more material onto the first + sheet. If you must use multiple sheets, put the main idea onto + the first sheet and less important material onto continuation + sheets. Remember that material on continuation sheets may be + overlooked. + + The proposal forms have been produced on a computer system so + that you may produce your proposals using your own computer + system. If you print your proposal and form on your computer + system, all of the information shown on the form(s) MUST be + printed and in the same location. + + The following are the instructions for each of the areas of the + form: + + 1. Please think of the most appropriate keyword or keywords + describing your proposal. + + 2. Select the best of the following categories of proposals: + 0 Nucleus Layer other than #1 (i.e., + AND ) + 1 Memory Operations (i.e., @ CMOVE ) + 2 Dictionary (i.e., ' FORGET ) + 3 String Operations (i.e., WORD COUNT ) + 4 Interpreter Layer other than #2 or #3 (i.e., ABORT . ) + 5 Compiler Layer (i.e., : DO ) + 6 Device Layer (i.e., BLOCK TYPE ) + 7 Experimental (i.e., 32-bit stack entries) + 8 Other Technical (i.e., mono-addressing) + 9 Charter + + 3. Mark whether this is a PROPOSAL or a COMMENT. + + 4. Indicate which FORTH word or words are relevant. + + 5. Indicate which section or sections of the Standard are + relevant. + + 6. The abstract must be kept short. The title, keywords, + category, and abstract may be used in a database for + organization and display on a terminal during a Standards + Team meeting. + + 7. Detail your proposal and provide supporting discussion. + + 8. Indicate the name of the submitter or the names of the + submitters. + + + + + 87 + + + + + + + + + 9. Finally, date the submittal and number each page. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 88 + + + + + + + + + FST Proposal and Comment Submittal Continuation Form + ----------------------------------------------------------------- + FST USE ONLY --> Proposal Number: + ================================================================= + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ----------------------------------------------------------------- + Submitted by: Date: + Page of + ================================================================= + FORTH Standards Team; PO Box 4545; Mountain View, CA 94040 820801 + + + + 89 + + \ No newline at end of file diff --git a/docs/reference/standards/README.md b/docs/reference/standards/README.md new file mode 100644 index 00000000..581a10ed --- /dev/null +++ b/docs/reference/standards/README.md @@ -0,0 +1,15 @@ +# The FORTH standards v4 is held to + +Captain Bob, 2026-11-14, on v3's whole POST (#189 Phase 7; `docs/v4.0.0/POST-PARITY.md`): **"The standard +first"**, in this order -- FORTH-79, then FORTH-83 for what 79 lacks, then ANS Forth 1994 for what both lack, +then v3 (held to its own table where v3 contradicts it) only for what no standard defines. And: "Put the two +standards' texts ... into the repository as references" -- "Yes, docs/reference/standards/". + +| File | What | From (fetched 2026-11-14) | +|---|---|---| +| `FORTH-79.TXT` | The FORTH-79 Standard | https://www.complang.tuwien.ac.at/forth/fth79std/FORTH-79.TXT | +| `FORTH83.TXT` | The FORTH-83 Standard | https://www.complang.tuwien.ac.at/forth/fth83std/FORTH83.TXT | +| `ans94/` | ANS Forth (X3J14 dpANS-6, the 1994 standard's final draft), as HTML | https://www.taygeta.com/forth/dpans.htm | + +Kept as fetched, unedited. A ruling or a POST rule that rests on one of them cites the file and the word's +entry (or the section). diff --git a/docs/reference/standards/ans94/dpans.htm b/docs/reference/standards/ans94/dpans.htm new file mode 100644 index 00000000..30371e7c --- /dev/null +++ b/docs/reference/standards/ans94/dpans.htm @@ -0,0 +1,574 @@ + +DPANS94 + + + +
+

American National Standard +for Information Systems

+ +

Programming Languages

+ +

Forth

+ +

+ +Secretariat +
+Computer and Business Equipment Manufacturers Association +
+Approved: March 24, 1994 +
+American National Standards Institute, Inc. +

+ + +


+

+ +Copyright (c) 1994 by Technical Committee X3J14. All rights reserved. +

+ +This is a working document of Technical Committee X3J14 which +represents the last draft of ANS Forth submitted to ANSI for publication. +Permission is hereby granted to copy this document provided that it is +copied in its entirety without alteration or as altered by (1) adding text +that is clearly marked as an insertion; (2) shading or highlighting +existing text; and/or (3) deleting examples. +

+ +Specifically, permission is granted to use this working document as the +foundation for textbooks, system manuals, and online documentation so +long as the requirements in the preceding paragraph are met and the +resulting product addresses a technical need that is not practically met by +the official ANS. +

+ +

NOTE: +
This file is provided as a working document of the TC for +public review and comment as well as documentation uses described above. +It is not intended as a substitute for the official ANS Forth document +published by ANSI. In the event of conflict, only the printed document +X3.215-1994 represents the official ANS Forth.
+ +

+ +To obtain the official standard, please contact the American +National Standards Institute Sales Department, at (212) 642-4900 or FAX +(212) 302-1286, or Global Engineering Documents, at (800) 854-7179 or +FAX (303) 843-9880, and request Document X3.215-1994. Thank you very +much for your interest. + +

+ + +


+ +

HTML version 3.2

+ +Editorial Notes +
+Requests for Interpretations +

+


+ +

Table of Contents

+
+ + +

+ + +


+Foreword +
+X3 Membership +
+X3J14 Membership +
+

+ + +


+1. Introduction +
+
+1.1 Purpose +
+1.2 Scope +
+1.3 Document organization +
+1.4 Future directions +
+ +

+ + +


+2. Terms, notation, and references +
+
+2.1 Definitions of terms +
+2.2 Notation +
+
+2.2.1 Numeric notation +
+2.2.2 Stack notation +
+2.2.3 Parsed-text notation +
+2.2.4 Glossary notation +
+2.3 References +
+ +

+ +


+3. Usage requirements +
+
+3.1 Data types +
+
+3.1.1 Data-type relationships +
+3.1.2 Character types +
+3.1.3 Single-cell types +
+3.1.4 Cell-pair types +
+3.1.5 System types +
+3.2 The implementation environment +
+
+3.2.1 Numbers +
+3.2.2 Arithmetic +
+3.2.3 Stacks +
+3.2.4 Operator terminal +
+3.2.5 Mass storage +
+3.2.6 Environmental queries +
+3.3 The Forth dictionary +
+
+3.3.1 Name space +
+3.3.2 Code space +
+3.3.3 Data space +
+3.4 The Forth text interpreter +
+
+3.4.1 Parsing +
+3.4.2 Finding definition names +
+3.4.3 Semantics +
+3.4.4 Possible actions on an ambiguous condition +
+3.4.5 Compilation +
+
+ +

+ +


+4. Documentation requirements +
+
+4.1 System documentation +
+4.2 Program documentation +
+ +

+ +


+5. Compliance and labeling +
+
+5.1 ANS Forth systems +
+5.2 ANS Forth programs +
+ +

+ +


+6. Glossary +
+
+6.1 Core words +
+6.2 Core extension words +
+ +

+ +


+7. The optional Block word set +
+
+7.1 Introduction +
+7.2 Additional terms +
+7.3 Additional usage requirements +
+7.4 Additional documentation requirements +
+7.5 Compliance and labeling +
+7.6.1 Block words +
+7.6.2 Block extension words +
+ +

+ +


+8. The optional Double-Number word set +
+
+8.1 Introduction +
+8.2 Additional terms and notation +
+8.3 Additional usage requirements +
+8.4 Additional documentation requirements +
+8.5 Compliance and labeling +
+8.6.1 Double-Number words +
+8.6.2 Double-Number extension words +
+ +

+ +


+9. The optional Exception word set +
+
+9.1 Introduction +
+9.2 Additional terms and notation +
+9.3 Additional usage requirements +
+9.4 Additional documentation requirements +
+9.5 Compliance and labeling +
+9.6.1 Exception words +
+9.6.2 Exception extension words +
+ +

+ +


+10. The optional Facility word set +
+
+10.1 Introduction +
+10.2 Additional terms and notation +
+10.3 Additional usage requirements +
+10.4 Additional documentation requirements +
+10.5 Compliance and labeling +
+10.6.1 Facility words +
+10.6.2 Facility extension words +
+ +

+ +


+11. The optional File-Access word set +
+
+11.1 Introduction +
+11.2 Additional terms +
+11.3 Additional usage requirements +
+11.4 Additional documentation requirements +
+11.5 Compliance and labeling +
+11.6.1 File-Access words +
+11.6.2 File-Access extension words +
+ +

+ +


+12. The optional Floating-Point word set +
+
+12.1 Introduction +
+12.2 Additional terms and notation +
+12.3 Additional usage requirements +
+12.4 Additional documentation requirements +
+12.5 Compliance and labeling +
+12.6.1 Floating-Point words +
+12.6.2 Floating-Point extension words +
+ +

+ +


+13. The optional Locals word set +
+
+13.1 Introduction +
+13.2 Additional terms and notation +
+13.3 Additional usage requirements +
+13.4 Additional documentation requirements +
+13.5 Compliance and labeling +
+13.6.1 Locals words +
+13.6.2 Locals extension words +
+ +

+ +


+14. The optional Memory-Allocation word set +
+
+14.1 Introduction +
+14.2 Additional terms and notation +
+14.3 Additional usage requirements +
+14.4 Additional documentation requirements +
+14.5 Compliance and labeling +
+14.6.1 Memory-Allocation words +
+ +

+ +


+15. The optional Programming-Tools word set +
+
+15.1 Introduction +
+15.2 Additional terms and notation +
+15.3 Additional usage requirements +
+15.4 Additional documentation requirements +
+15.5 Compliance and labeling +
+15.6.1 Programming-Tools words +
+15.6.2 Programming-Tools extension words +
+ +

+ +


+16. The optional Search-Order word set +
+
+16.1 Introduction +
+16.2 Additional terms and notation +
+16.3 Additional usage requirements +
+16.4 Additional documentation requirements +
+16.5 Compliance and labeling +
+16.6.1 Search-Order words +
+16.6.2 Search-Order extension words +
+ +

+ +


+17. The optional String word set +
+
+17.1 Introduction +
+17.2 Additional terms and notation +
+17.3 Additional usage requirements +
+17.4 Additional documentation requirements +
+17.5 Compliance and labeling +
+17.6.1 String words +
+

+ +


+A. Rationale (informative annex) +
+
+A.1 Introduction +
+A.2 Terms and notation +
+A.3 Usage requirements +
+A.4 Documentation requirements +
+A.5 Compliance and labeling +
+A.6 Glossary +
+A.7 The optional Block word set +
+A.8 The optional Double-Number word set +
+A.9 The optional Exception word set +
+A.10 The optional Facility word set +
+A.11 The optional File-Access word set +
+A.12 The optional Floating-Point word set +
+A.13 The optional Locals word set +
+A.14 The optional Memory-Allocation word set +
+A.15 The optional Programming-Tools word set +
+A.16 The optional Search-Order word set +
+A.17 The optional String word set +
+ +

+ +


+B. Bibliography (informative annex) +
+
+Industry standards +
+Books +
+Journals, magazines and newsletters +
+Selected articles +
+ +

+ +


+C. Perspective (informative annex) +
+
+C.1 Features of Forth +
+C.2 History of Forth +
+C.3 Hardware implementations of Forth +
+C.4 Standardization efforts +
+C.5 Programming in Forth +
+C.6 Multiprogrammed systems +
+C.7 Design and management considerations +
+C.8 Conclusion +
+ +

+ +


+D. Compatibility analysis of ANS Forth +(informative annex) +
+
+D.1 FIG Forth (circa 1978) +
+D.2 Forth-79 +
+D.3 Forth-83 +
+D.4 Recent developments +
+D.5 ANS Forth approach +
+D.6 Differences from Forth-83 +
+ +

+ +


+E. ANS Forth portability guide (informative +annex) +
+
+E.1 Introduction +
+E.2 Hardware peculiarities +
+E.3 Number representation +
+E.4 Forth system implementation +
+E.5 ROMed application disciplines and +conventions +
+E.6 Summary +
+ +

+ +


+F. Alphabetic list of words (informative +annex) +
+
+

+ + diff --git a/docs/reference/standards/ans94/dpans1.htm b/docs/reference/standards/ans94/dpans1.htm new file mode 100644 index 00000000..babd4165 --- /dev/null +++ b/docs/reference/standards/ans94/dpans1.htm @@ -0,0 +1,700 @@ + +DPANS94 + + + + + + + + + +
+ + + +Table of Contents +
+

+


+ +

American National Standard for Information Systems

+ +

Programming Languages

+ +

Forth

+ + +Secretariat + +
+Computer and Business Equipment Manufacturers Association + +
+Approved: March 24, 1994 + +
+American National Standards Institute, Inc. + +

+ + +Copyright (c) 1994 by Technical Committee X3J14. +All rights reserved. + +

+ + +This is a working document of Technical Committee X3J14 which represents +the last draft of ANS Forth submitted to ANSI for publication. +Permission is hereby granted to copy this document provided that it is +copied in its entirety without alteration or as altered by (1) adding +text that is clearly marked as an insertion; (2) shading or highlighting +existing text; and/or (3) deleting examples. + +

+ + +Specifically, permission is granted to use this working document as the +foundation for textbooks, system manuals, and online documentation so +long as the requirements in the preceding paragraph are met and the +resulting product addresses a technical need that is not practically met +by the official ANS. + +

+ + +NOTE: This file is provided as a working document of the TC for public +review and comment as well as documentation uses described above. It is +not intended as a substitute for the official ANS Forth document +published by ANSI. In the event of conflict, only the printed document +X3.215-1994 represents the official ANS Forth. + +

+ + +To obtain the official standard, please contact the American National +Standards Institute Sales Department, at (212) 642-4900 or FAX (212) +302-1286, or Global Engineering Documents, at (800) 854-7179 or FAX +(303) 843-9880, and request Document X3.215-1994. Thank you very much +for your interest. + + + +


+ +

Foreword

+
+ + +(This foreword is not a part of +American National Standard X3.215-1994) + +

+ + +Forth is a language for direct communication between human beings and +machines. Using natural-language diction and machine-oriented syntax, +Forth provides an economical, productive environment for interactive +compilation and execution of programs. Forth also provides low-level +access to computer-controlled hardware, and the ability to extend the +language itself. This extensibility allows the language to be quickly +expanded and adapted to special needs and different hardware systems. + +

+ + +Forth was invented by Mr. Charles Moore to increase programmer +productivity 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-1970s by an +international group of users and implementors who adopted the name +Forth Standards Team. 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. Major changes were made by the Forth Standards Team in the +Forth-83 Standard, which was published in 1983. + +

+ + +The first meeting of the Technical Committee on Forth Programming +Systems was convened by the Organizing Committee of the X3J14 Forth +Technical Committee on August 3, 1987, and has met subsequently on +November 11-12, 1987, February 10-12, 1988, May 25-28, 1988, August +10-13, 1988, October 26-29, 1988, January 25-28, 1989, May 3-6, 1989, +July 26-29, 1989, October 25-28, 1989, January 24-27, 1990, May 22-26, +1990, August 21-25, 1990, November 6-10,1990, January 29-February 2, +1991, May 3-4, 1991, June 16-19, 1991, July 30-August 3, 1991, March +17-21, 1992, October 13-17, 1992, January 26-30, 1993, June 28-30, 1993, +and June 21, 1994. + +

+ +Requests for interpretation, suggestions for improvement or addenda, or +defect reports are welcome. They should be sent to the X3 Secretariat, +Computer and Business Equipment Manufacturers Association, 1250 Eye +Street, NW, Suite 200, Washington, DC 20005. + + + +


+ +

X3 Membership

+
+ +This standard was processed and approved for submittal to ANSI by the +Accredited Standards Committee on Information Processing Systems, X3. +Committee approval of this standard does not necessarily imply that all +committee members voted for its approval. At the time it approved this +standard, the X3 Committee had the following members: + +

+ + +James D. Converse, Chair +Donald C. Loughry, Vice-Chair +Joanne Flanagan, Secretary + +

+ + + + +

+Producer Group                          Name of Representative
+--------------                          ----------------------
+AMP Incorporated                        Edward Kelly
+                                        Charles Brill (Alt.)
+
+AT&T/NCR Corporation                    Thomas W. Kern
+                                        Thomas F. Frost (Alt.)
+
+Apple Computer, Inc.                    Karen Higginbottom
+
+Compaq Computers                        James Barnes
+
+Digital Equipment Corporation           Delbert Shoemaker
+                                        Kevin Lewis
+
+Hitachi America Ltd.                    John Neumann
+                                        Kei Yamashita (Alt.)
+
+Hewlett Packard                         Donald C. Loughry
+
+Bull HN Information Systems Inc.        William George
+
+IBM Corporation                         Joel Urman
+                                        Mary Anne Lawler (Alt.)
+
+Unisys Corporation                      John Hill
+                                        Stephen P. Oksala (Alt.)
+
+Sony Corporation of America             Michael Deese
+
+Storage Technology Corporation          Joseph S. Zajaczkowski
+                                        Samuel D. Cheatham (Alt.)
+
+Sun Microsystems, Inc.                  Scott Jameson
+                                        Gary S. Robinson (Alt.)
+
+* Xerox Corporation                     Dwight McBain
+                                        Roy Pierce (Alt.)
+
+3M Company                              Edie T. Morioka
+                                        Paul D. Jahnke (Alt.
+
+
+

+ + +Consumers Group + +
+--------------- + + +

+Boeing Company                          Catherine Howells
+                                        Andrea Vanosdoll (Alt.)
+
+Eastman Kodak Company                   James Converse
+                                        Michael Nier (Alt.)
+
+General Services Administration         Douglas Arai
+                                        Larry L. Jackson (Alt.)
+
+Guide International Inc.                Frank Kirshenbaum
+                                        Harold Kuneke (Alt.)
+
+** Hughes Aircraft Company              Harold Zebrack
+
+National Communications Systems         Dennis Bodson
+
+Northern Telecom Inc.                   Mel Woinsky
+                                        Subhash Patel (Alt.)
+
+** Recognition Tech Users Association   Herbert P. Schantz
+                                        Edwin Hale (Alt.)
+
+Share Inc.                              Gary AinsworthDavid Thewis (Alt.)
+
+U. S. Department of Defense             William Rinehuls
+                                        J. Pasquariello (Alt.)
+
+U. S. Department of Energy              Alton Cox
+                                        Lawrence A. Wasson (Alt.)
+
+Wintergreen Information Services        John Wheeler
+
+

+ + + +General Interest Group + +
+---------------------- + + +

+American Nuclear Society                Geraldine C. Main
+                                        Sally Hartzell (Alt.)
+
+Assn. of the Institute for Certification of Computer Professionals
+                                        Kenneth Zemrowski
+
+Nat'l Institute of Standards and Technology     
+                                        Robert E. Rountree
+                                        Micharl Hogan (Alt.)
+
+Neville & Associates                    Carlton Neville
+________________________
+
+* Abstain      ** Non-Response
+
+ +

+ + + + +


+ +

X3J14 Membership

+
+ +At the time it approved this draft of the proposed American National +Standard, the Technical Committee X3J14 on the Forth Programming +Language had the following members: + +

+ + +Elizabeth Rather, Chair + +
+Mitch Bradley, acting Vice-Chair + +
+Don Colburn, Secretary + +
+John Rible, Technical Editor + +
+Len Zettel, Vocabulary Representative + +
+Greg Bailey, Technical Subcommittee Chair + +
+ +

+ + + + +

+Organization Represented                Name of Representative
+------------------------                ----------------------
+ATHENA Programming, Inc.                Greg Bailey
+                                        Howe Fong (Alt.)
+
+Bradley Forthware                       Mitch Bradley
+
+Creative Solutions, Inc.                Don Colburn
+
+Ford Motor Company                      Leonard F. Zettel, Jr.
+
+FORTH, Inc.                             Elizabeth Rather
+                                        Dennis Ruffer (Alt.)
+
+Institute for Applied Forth Research    Lawrence Forsley
+                                        Horace Simmons (Alt.)
+
+Johns Hopkins University, Applied Physics Lab.  
+                                        John Hayes
+
+Mephistopheles Systems                  Dave Harralson
+
+NASA/Goddard Space Flight Center        James Rash
+
+Nomadic Software                        John K. Stevenson
+
+Unisyn, Inc.                            Gary Betts
+                                        Stephen Egbert (Alt.)
+
+Up and Running                          Martin Tracy
+
+Vesta Technology                        Jack Woehr
+
+Individual Members                      Loring Craymer
+                                        John Rible
+                                        E. (Jet) Thomas
+
+X3 Liasons                              Clyde R. Camp
+                                        Kathleen McMillan
+
+ +

+ + +The following organizations and individuals have also participated in this +project as Technical Committee members, alternates, or observers. The +Technical Committee recognizes and respects their contributions: + +

+ + +Organizations + +
+------------- + + +

+British Columbia Inst. of Tech.  MCI Telecommunications Corp.
+Computer Cowboys                 Micromotion
+Computer Sciences Corp.          MicroProcessor Engineering Ltd.
+Computer Strategies, Inc.        National Institute of Standards & Technology
+Digalog Corp.                    NCR Medical Systems Group
+Embedded Sys. Programming Mag.   Performance Packages, Inc.
+Forth Interest Group (FIG)       Purdue University
+H.B. Pascal & Co., Inc.          Robert Berkey Services
+Harris Semiconductor             Shaw Laboratories
+IBM Corporation                  Social Security Administration
+IEEE                             Software Engineering
+Kelly Enterprises                Texas Instruments
+Laboratory Microsystems, Inc.    The Dickens Company
+Maxtor Corp.
+
+ +

+ + +Individuals + +
+----------- + + +

+David J. Angel  Ray Duncan      Charles Moore   Dean Sanderson
+Wil Baden       Douglas Fishman Mike Nemeth     George Shaw
+Robert Berkey   Tom Hand        Harry Pascal    Gerald Shifrin
+Ron Braithwaite Gregory Ilg     Stephen Pelc    Robert Smith
+Jack Brown      Charles Keane   Dean Perrine    Tyler Sperry
+Chris Colburn   Guy M. Kelly    David C. Petty  Tom Zimmer
+Ted Dickens     Andrew Kobziar  Bill Ragsdale   James Ryland
+John Dorband    Martin Lascelles
+
+
+

+ +


+

AMERICAN NATIONAL STANDARD ANSI X3.215-1994 American National +Standard for Information Systems

+ + + +

Programming Language

+ + +

Forth

+ + + +
+ +

1. Introduction

+
+ + +
+ +

1.1 Purpose

+
+ +The purpose of this Standard is to promote the portability of Forth programs +for use on a wide variety of computing systems, to facilitate the +communication of programs, programming techniques, and ideas among Forth +programmers, and to serve as a basis for the future evolution of the Forth +language. + +

+ + +


+ +

1.2 Scope

+
+ +This Standard specifies an interface between a Forth System and a Forth +Program by defining the words provided by a Standard System. + +

+ +See: +A.1.2 Scope + +

+ +


+ +

1.2.1 Inclusions

+
+ +This Standard specifies: +

+ + +

    +
  • the forms +that a program written in the Forth language may take; +
  • the rules for interpreting the meaning of a program and its data. +
+ +

+ + +


+ +

1.2.2 Exclusions

+
+ +This Standard does not specify: +

+ + +

    +
  • the mechanism +by which programs are transformed for use on computing +systems; +
  • the operations +required for setup and control of the use of programs +on computing systems; +
  • the method +of transcription of programs or their input or output data +to or from a storage medium; +
  • the program +and Forth system behavior when the rules of this Standard +fail to establish an interpretation; +
  • the size +or complexity of a program and its data that will exceed the +capacity of any specific computing system or the capability of a particular +Forth system; +
  • the physical +properties of input/output records, files, and units; +
  • the physical +properties and implementation of storage. +
+ +

+ + +


+ +

1.3 Document organization

+
+ +

+ + +


+ +

1.3.1 Word sets

+
+ +This Standard groups Forth words and capabilities into word sets under a name +indicating some shared aspect, typically their common functional area. Each +word set may have an extension, containing words that offer additional +functionality. These words are not required in an implementation of the word +set. + +

+ + +The Core word set, defined in sections 1 through 6, contains the +required +words and capabilities of a Standard System. The other word sets, defined in +sections 7 through 17, are optional, making it possible to provide Standard +Systems with tailored levels of functionality. + +

+ +See: +A.1.3.1 Word sets + +

+ + + +


+ +

1.3.1.1 Text sections

+
+ +Within each word set, section 1 contains introductory and explanatory material +and section 2 introduces terms and notation used throughout the Standard. +There are no requirements in these sections. + +

+ + +Sections 3 and 4 contain the usage and documentation requirements, +respectively, for Standard Systems and Programs, while section 5 specifies +their labeling. + +

+ + +


+ +

1.3.1.2 Glossary sections

+
+ +Section 6 of each word set specifies the required behavior of the definitions +in the word set and the extensions word set. + +

+ + +


+ +

1.3.2 Annexes

+
+ +The annexes do not +contain any required material. +

+ + +Annex A +provides some of the rationale behind the committee's decisions in +creating this Standard, as well as implementation examples. It has the same +section numbering as the body of the Standard to make it easy to relate each +requirements section to its rationale section. + +

+ + +Annex B +is a short bibliography on Forth. + +

+ + +Annex C +provides an introduction to Forth. + +

+ + +Annex D +discusses the compatibility of ANS Forth with earlier Forths, +emphasizing the differences from Forth-83. + +

+ + +Annex E +presents some techniques for writing portable programs in ANS Forth. + +

+ + +Annex F +includes the words from all word sets in a single list, and serves as +an index of ANS Forth words. + +

+ + +


+ +

1.4 Future directions

+
+ + + +
+ +

1.4.1 New technology

+
+ +This Standard adopts certain words and practices that are increasingly found +in common practice. New words have also been adopted to ease creation of +portable programs. + +

+ +


+ +

1.4.2 Obsolescent features

+
+ +This Standard adopts certain words and practices that cause some previously +used words to become obsolescent. Although retained here because of their +widespread use, their use in new implementations or new programs is +discouraged, because they may be withdrawn from future revisions of the +Standard. + +

+ +This Standard designates the following words as obsolescent: +

+ + + +

+6.2.0060        #TIB
+15.6.2.1580     FORGET
+6.2.2240        SPAN
+6.2.0970        CONVERT
+6.2.2040        QUERY
+6.2.2290        TIB
+6.2.1390        EXPECT
+
+ +

+ +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpans10.htm b/docs/reference/standards/ans94/dpans10.htm new file mode 100644 index 00000000..781f25fc --- /dev/null +++ b/docs/reference/standards/ans94/dpans10.htm @@ -0,0 +1,495 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

10. The optional Facility word set

+ + +
+ +

10.1 Introduction

+
+ + +
+ +

10.2 Additional terms and notation

+
+ +None. +

+ + +


+ +

10.3 Additional usage requirements

+
+ + +
+ +

10.3.1 Character types

+
+ +Programs that use more than seven bits of a character by +10.6.2.1305 +EKEY have an environmental dependency. +

+ + +See: +3.1.2 Character types + +

+ + +


+ +

10.3.2 Environmental queries

+
+ +Append table 10.1 to table 3.5. +

+ + +See: +3.2.6 Environmental queries + +

+ +Table 10.1 - Environmental query strings + + +

+String          Value data type   Constant?   Meaning
+------          ---------------   ---------   -------
+FACILITY        flag              no          facility word set present
+FACILITY-EXT    flag              no          facility extensions word set present
+
+
+ +

+ +


+ +

10.4 Additional documentation requirements

+
+ + +
+ +

10.4.1 System documentation

+
+ + +
+ +

10.4.1.1 Implementation-defined options

+
+ +
    +
  • encoding of keyboard events +(10.6.2.1305 EKEY); +
  • duration of a system clock tick; +
  • repeatability to be expected from execution of +10.6.2.1905 MS. +
+

+ + +


+ +

10.4.1.2 Ambiguous conditions

+
+ +
    +
  • 10.6.1.0742 AT-XY +operation can't be performed on user output device. +
+

+ + +


+ +

10.4.1.3 Other system documentation

+
+ +
    +
  • no additional requirements. +
+

+ +


+ +

10.4.2 Program documentation

+
+ + +
+ +

10.4.2.1 Environmental dependencies

+
+ +
    +
  • using more than seven bits of a character in +10.6.2.1305 EKEY. +
+

+ + +


+ +

10.4.2.2 Other program documentation

+
+ +
    +
  • no additional requirements. +
+

+ +


+ +

10.5 Compliance and labeling

+
+ + +
+ +

10.5.1 ANS Forth systems

+
+ +The phrase Providing the Facility word set shall be appended to +the label of any Standard System that provides all of the Facility word +set. +

+ +The phrase Providing name(s) from the Facility Extensions word +set shall be appended to the label of any Standard System that +provides portions of the Facility Extensions word set. +

+ +The phrase Providing the Facility Extensions word set shall be +appended to the label of any Standard System that provides all of the +Facility and Facility Extensions word sets. +

+ + +


+ +

10.5.2 ANS Forth programs

+
+ +The phrase Requiring the Facility word set shall be appended to +the label of Standard Programs that require the system to provide the +Facility word set. +

+ +The phrase Requiring name(s) from the Facility Extensions word +set shall be appended to the label of Standard Programs that require +the system to provide portions of the Facility Extensions word set. +

+ +The phrase Requiring the Facility Extensions word set shall be +appended to the label of Standard Programs that require the system to +provide all of the Facility and Facility Extensions word sets. +

+ + +


+ +

10.6 Glossary

+
+ + +
+ +

10.6.1 Facility words

+
+ + +
+ + +10.6.1.0742 AT-XY + + +
+at-x-y FACILITY +
+
+	( u1 u2 -- )
+
+

+ +Perform implementation-dependent steps so that the next character +displayed will appear in column u1, row u2 of the user output device, +the upper left corner of which is column zero, row zero. An ambiguous +condition exists if the operation cannot be performed on the user output +device with the specified parameters. + +

+ +See: +A.10.6.1.0742 AT-XY + +

+ +


+ + +10.6.1.1755 KEY? + + +
+key-question FACILITY +
+
+	( -- flag )
+
+

+ +If a character is available, return true. Otherwise, return false. If +non-character keyboard events are available before the first valid +character, they are discarded and are subsequently unavailable. The +character shall be returned by the next execution of +KEY. +

+ +After KEY? returns with a value of true, subsequent executions of KEY? +prior to the execution of KEY or +EKEY also return true, without +discarding keyboard events. + +

+ +See: +A.10.6.1.1755 KEY? + +

+ + +


+ + +10.6.1.2005 PAGE + + +
+FACILITY +
+
+	( -- )
+
+

+ +Move to another page for output. Actual function depends on the output +device. On a terminal, PAGE clears the screen and resets the cursor +position to the upper left corner. On a printer, PAGE performs a form +feed. +

+ + + +


+ +

10.6.2 Facility extension words

+
+ + +
+ + +10.6.2.1305 EKEY + + +
+ e-key FACILITY EXT +
+
+	( -- u )
+
+

+ +Receive one keyboard event u. The encoding of keyboard events is +implementation defined. +

+ + +See: +10.6.1.1755 KEY? , +6.1.1750 KEY , +A.10.6.2.1305 EKEY + +

+ + + +


+ + +10.6.2.1306 EKEY>CHAR + + +
+e-key-to-char FACILITY EXT +
+
+	( u -- u false | char true )
+
+

+ +If the keyboard event u corresponds to a character in the +implementation-defined character set, return that character and true. +Otherwise return u and false. + + +

+ +See: +A.10.6.2.1306 EKEY>CHAR + +

+ + +


+ + +10.6.2.1307 EKEY? + + +
+e-key-question FACILITY EXT +
+
+	( -- flag )
+
+

+ +If a keyboard event is available, return true. Otherwise return false. +The event shall be returned by the next execution of +EKEY. +

+ +After EKEY? returns with a value of true, subsequent executions of EKEY? +prior to the execution of +KEY, +KEY? +or EKEY also return true, referring +to the same event. + +

+ + +


+ + +10.6.2.1325 EMIT? + + +
+emit-question FACILITY EXT +
+
+	( -- flag )
+
+

+ +flag is true if the user output device is ready to accept data and the +execution of +EMIT +in place of EMIT? would not have suffered an +indefinite delay. If the device status is indeterminate, flag is true. + +

+ +See: +A.10.6.2.1325 EMIT? + +

+ + +


+ + +10.6.2.1905 MS + + +
+FACILITY EXT +
+
+	( u -- )
+
+

+ +Wait at least u milliseconds. + +

+Note: The actual length and variability of the time period depends +upon the implementation-defined resolution of the system clock and +upon other system and computer characteristics beyond the scope of +this Standard. + + +

+ +See: +A.10.6.2.1905 MS + +

+ + +


+ + +10.6.2.2292 TIME&DATE + + +
+time-and-date FACILITY EXT +
+
+	( -- +n1 +n2 +n3 +n4 +n5 +n6 )
+
+

+ +Return the current time and date. +n1 is the second {0...59}, +n2 is +the minute {0...59}, +n3 is the hour {0...23}, +n4 is the day {1...31} ++n5 is the month {1...12}, and +n6 is the year (e.g., 1991). + +

+ +See: +A.10.6.2.2292 TIME&DATE + +

+ + + +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpans11.htm b/docs/reference/standards/ans94/dpans11.htm new file mode 100644 index 00000000..e71ea012 --- /dev/null +++ b/docs/reference/standards/ans94/dpans11.htm @@ -0,0 +1,1343 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

11. The optional File-Access word set

+ +

+ +See: +A.11 The optional File-Access word set + +

+ +


+ +

11.1 Introduction

+
+ +These words provide access to mass storage in the form of files +under the following assumptions: + +
    +
  • files are provided by a host operating system; +
  • file names are represented as character strings; +
  • the format of file names is determined by the host operating system; +
  • an open file is identified by a single-cell file identifier (fileid); +
  • file-state information (e.g., position, size) is managed by the +host operating system; +
  • file contents are accessed as a sequence of characters; +
  • file read operations return an actual transfer count, which can +differ from the requested transfer count. +
+ +

+ +


+ +

11.2 Additional terms

+
+ +
+
file-access method: +
A permissible means of accessing a file, such as read/write or read only. + +
file position: +
The character offset from the start of the file. + +
input file: +
The file, containing a sequence of lines, that is the input source. +
+ + +
+ +

11.3 Additional usage requirements

+
+ + + +
+ +

11.3.1 Data types

+
+ +Append table 11.1 to +table 3.1. +

+ +Table 11.1 - Data types +

+ + + +

+Symbol  Data type               Size on stack
+------  ---------               -------------
+ior     I/O results             1 cell
+fam     file access method      1 cell
+fileid  file identifiers        1 cell
+
+ +

+ +


+ +

11.3.1.1 File identifiers

+
+ +File identifiers are implementation-dependent single-cell values that +are passed to file operators to designate specific files. Opening a +file assigns a file identifier, which remains valid until closed. + + +

+ +


+ +

11.3.1.2 I/O results

+
+ +I/O results are single-cell numbers indicating the result of I/O +operations. A value of zero indicates that the I/O operation completed +successfully; other values and their meanings are +implementation-defined. Reaching the end of a file shall be reported as +zero. + +

+ +An I/O exception in the execution of a File-Access word that can return +an I/O result shall not cause a +THROW; exception indications are +returned in the ior. + +

+ +


+ +

11.3.1.3 File access methods

+
+ +File access methods are implementation-defined single-cell +values. + +

+ +


+ +

11.3.1.4 File names

+
+ +A character string containing the name of the file. The file name may +include an implementation-dependent path name. The format of file names +is implementation defined. + +

+ +


+ +

11.3.2 Blocks in files

+
+ +If the File-Access word set is implemented, the +Block word set shall be +implemented. + +

+ +Blocks may, but need not, reside in files. When they do: +

+ +

    +
  • Block numbers may be mapped to one or more files by +implementation-defined means. An ambiguous condition exists if a +requested block number is not currently mapped; +
  • An +UPDATEd +block that came from a file shall be transferred back +to the same file. +
+ +

+ +See: +A.11.3.2 Blocks in files + +

+ + +


+ +

11.3.3 Environmental queries

+
+ +Append table 11.2 to +table 3.5. + +

+ + +See: +3.2.6 Environmental queries + +

+ +Table 11.2 - Environmental query strings +

+ + + +

+String         Value data type   Constant?  Meaning
+------         ---------------   ---------  -------
+FILE            flag             no         file word set present
+FILE-EXT        flag             no         file extensions word set present
+
+ +

+ +


+ +

11.3.4 Input source

+
+ +The File-Access word set creates another input source for the text +interpreter. When the input source is a text file, +BLK shall contain +zero, +SOURCE-ID +shall contain the fileid of that text file, and the +input buffer shall contain one line of the text file. + +

+ +Input with +INCLUDED, +INCLUDE-FILE, +LOAD and +EVALUATE shall be nestable +in any order to at least eight levels. + +

+ +A program that uses more than eight levels of input-file nesting has an +environmental dependency. + +

+ + +See: +3.3.3.5 Input buffers, +9. Optional Exception word set. + +

+ + +


+ +

11.3.5 Other transient regions

+
+ +The list of words using memory in transient regions is extended to +include 11.6.1.2165 S". + +

+ + +See: +3.3.3.6 Other transient regions + +

+ + +

+ +


+ +

11.3.6 Parsing

+
+ +When parsing from a text file using a space delimiter, control +characters shall be treated the same as the space character. + +

+ +Lines of at least 128 characters shall be supported. A program that +requires lines of more than 128 characters has an environmental +dependency. + +

+ +A program may reposition the parse area within the input buffer by +manipulating the contents of +>IN. +More extensive repositioning can be +accomplished using +SAVE-INPUT and +RESTORE-INPUT. + +

+ + +See: +3.4.1 Parsing + +

+ +


+ +

11.4 Additional documentation requirements

+
+ + +
+ +

11.4.1 System documentation

+
+ + +
+ +

11.4.1.1 Implementation-defined options

+
+ + + + + +
+ +

11.4.1.2 Ambiguous conditions

+
+ + + +
+ +

11.4.1.3 Other system documentation

+
+
    +
  • no additional requirements. +
+ +
+ +

11.4.2 Program documentation

+
+ + +
+ +

11.4.2.1 Environmental dependencies

+
+ +
    +
  • requiring lines longer than 128 characters +(11.3.6 Parsing); +
  • using more than eight levels of input-file nesting +(11.3.4 Input source). +
+ +

+ +


+ +

11.4.2.2 Other program documentation

+
+ +
    +
  • no additional requirements. +
+ + +
+ +

11.5 Compliance and labeling

+
+ + +
+ +

11.5.1 ANS Forth systems

+
+ +The phrase Providing the File Access word set shall be appended +to the label of any Standard System that provides all of the File Access +word set. + +

+ +The phrase Providing name(s) from the File Access Extensions word +set shall be appended to the label of any Standard System that +provides portions of the File Access Extensions word set. + +

+ +The phrase Providing the File Access Extensions word set shall be +appended to the label of any Standard System that provides all of the +File Access and File Access Extensions word sets. + + +

+ +


+ +

11.5.2 ANS Forth programs

+
+ +The phrase Requiring the File Access word set shall be appended +to the label of Standard Programs that require the system to provide the +File Access word set. + +

+ +The phrase Requiring name(s) from the File Access Extensions word +set shall be appended to the label of Standard Programs that require +the system to provide portions of the File Access Extensions word set. + +

+ +The phrase Requiring the File Access Extensions word set shall be +appended to the label of Standard Programs that require the system to +provide all of the File Access and File Access Extensions word sets. + +

+ +


+ +

11.6 Glossary

+
+ + +
+ +

11.6.1 File Access words

+
+ + +
+ + +11.6.1.0080 ( + + +
+paren FILE +
+
+	( "ccc<paren>" -- )
+
+

+ +Extend the semantics of +6.1.0080 ( to include: +

+ +When parsing from a text file, if the end of the parse area is reached +before a right parenthesis is found, refill the input buffer from the +next line of the file, set +>IN +to zero, and resume parsing, repeating +this process until either a right parenthesis is found or the end of the +file is reached. + +

+ +


+ + +11.6.1.0765 BIN + + +
+FILE +
+
+	( fam1 -- fam2 )
+
+

+ +Modify the implementation-defined file access method fam1 to +additionally select a binary, i.e., not line oriented, file +access method, giving access method fam2. +

+ + +See: +A.11.6.1.0765 BIN , +11.6.1.2054 R/O , +11.6.1.2056 R/W , +11.6.1.2425 W/O + + +

+ +


+ + +11.6.1.0900 CLOSE-FILE + + +
+FILE +
+
+	( fileid -- ior )
+
+

+ +Close the file identified by fileid. ior is the implementation-defined +I/O result code. + +

+ +


+ + +11.6.1.1010 CREATE-FILE + + +
+FILE +
+
+	( c-addr u fam -- fileid ior )
+
+

+ +Create the file named in the character string specified by c-addr and u, +and open it with file access method fam. The meaning of values of fam +is implementation defined. If a file with the same name already exists, +recreate it as an empty file. + +

+ +If the file was successfully created and opened, ior is zero, fileid is +its identifier, and the file has been positioned to the start of the +file. + +

+ +Otherwise, ior is the implementation-defined I/O result code and fileid +is undefined. + +

+ +See: +A.11.6.1.1010 CREATE-FILE + +

+ + +


+ + +11.6.1.1190 DELETE-FILE + + +
+FILE +
+
+	( c-addr u -- ior )
+
+

+ +Delete the file named in the character string specified by c-addr u. +ior is the implementation-defined I/O result code. + +

+ +


+ + +11.6.1.1520 FILE-POSITION + + +
+FILE +
+
+	( fileid -- ud ior )
+
+

+ +ud is the current file position for the file identified by fileid. ior +is the implementation-defined I/O result code. ud is undefined if ior +is non-zero. + +

+ +


+ + +11.6.1.1522 FILE-SIZE + + +
+FILE +
+
+	( fileid -- ud ior )
+
+

+ +ud is the size, in characters, of the file identified by fileid. ior is +the implementation-defined I/O result code. This operation does not +affect the value returned by +FILE-POSITION. +ud is undefined if ior is +non-zero. + +

+ +


+ + +11.6.1.1717 INCLUDE-FILE + + +
+FILE +
+
+	( i*x fileid -- j*x )
+
+

+ +Remove fileid from the stack. Save the current input source +specification, including the current value of +SOURCE-ID. Store fileid +in SOURCE-ID. Make the file specified by fileid the input source. +Store zero in +BLK. +Other stack effects are due to the words included. + +

+ +Repeat until end of file: read a line from the file, fill the input +buffer from the contents of that line, set +>IN to zero, and interpret. + +

+ +Text interpretation begins at the file position where the next file read +would occur. + +

+ +When the end of the file is reached, close the file and restore the +input source specification to its saved value. + +

+ +An ambiguous condition exists if fileid is invalid, if there is an I/O +exception reading fileid, or if an I/O exception occurs while closing +fileid. When an ambiguous condition exists, the status (open or closed) +of any files that were being interpreted is implementation-defined. +

+ + +See: +11.3.4 Input source, +A.11.6.1.1717 INCLUDE-FILE + +

+ + +


+ + +11.6.1.1718 INCLUDED + + +
+FILE +
+
+	( i*x c-addr u -- j*x )
+
+

+ +Remove c-addr u from the stack. Save the current input source +specification, including the current value of +SOURCE-ID. Open the file +specified by c-addr u, store the resulting fileid in SOURCE-ID, and make +it the input source. Store zero in +BLK. Other stack effects are due to +the words included. + +

+ +Repeat until end of file: read a line from the file, fill the input +buffer from the contents of that line, set +>IN to zero, and interpret. + +

+ +Text interpretation begins at the file position where the next file read +would occur. + +

+ +When the end of the file is reached, close the file and restore the +input source specification to its saved value. + +

+ +An ambiguous condition exists if the named file can not be opened, if an +I/O exception occurs reading the file, or if an I/O exception occurs +while closing the file. When an ambiguous condition exists, the status +(open or closed) of any files that were being interpreted is +implementation-defined. + +

+ + +See: +A.11.6.1.1718 INCLUDED , +11.6.1.1717 INCLUDE-FILE + + +

+ +


+ + +11.6.1.1970 OPEN-FILE + + +
+FILE +
+
+	( c-addr u fam -- fileid ior )
+
+

+ +Open the file named in the character string specified by c-addr u, with +file access method indicated by fam. The meaning of values of fam is +implementation defined. + +

+ +If the file is successfully opened, ior is zero, fileid is its +identifier, and the file has been positioned to the start of the file. + +

+ +Otherwise, ior is the implementation-defined I/O result code and fileid +is undefined. + +

+ +See: +A.11.6.1.1970 OPEN-FILE + +

+ + +


+ + +11.6.1.2054 R/O + + +
+r-o FILE +
+
+	( -- fam )
+
+

+ +fam is the implementation-defined value for selecting the read +only file access method. +

+ + +See: +11.6.1.1010 CREATE-FILE , +11.6.1.1970 OPEN-FILE + + +

+ +


+ + +11.6.1.2056 R/W + + +
+r-w FILE +
+
+	( -- fam )
+
+

+ +fam is the implementation-defined value for selecting the +read/write file access method. +

+ + +See: +11.6.1.1010 CREATE-FILE , +11.6.1.1970 OPEN-FILE + + +

+ +


+ + +11.6.1.2080 READ-FILE + + +
+FILE +
+
+	( c-addr u1 fileid -- u2 ior )
+
+

+ +Read u1 consecutive characters to c-addr from the current position of +the file identified by fileid. + +

+ +If u1 characters are read without an exception, ior is zero and u2 is +equal to u1. + +

+ +If the end of the file is reached before u1 characters are read, ior is +zero and u2 is the number of characters actually read. + +

+ +If the operation is initiated when the value returned by +FILE-POSITION +is equal to the value returned by +FILE-SIZE for the file identified by +fileid, ior is zero and u2 is zero. + +

+ +If an exception occurs, ior is the implementation-defined I/O result +code, and u2 is the number of characters transferred to c-addr without +an exception. + +

+ +An ambiguous condition exists if the operation is initiated when the +value returned by FILE-POSITION is greater than the value returned by +FILE-SIZE for the file identified by fileid, or if the requested +operation attempts to read portions of the file not written. + +

+ +At the conclusion of the operation, FILE-POSITION returns the next file +position after the last character read. + +

+ +See: +A.11.6.1.2080 READ-FILE + +

+ + +


+ + +11.6.1.2090 READ-LINE + + +
+FILE +
+
+	( c-addr u1 fileid -- u2 flag ior )
+
+

+ +Read the next line from the file specified by fileid into memory at the +address c-addr. At most u1 characters are read. Up to two +implementation-defined line-terminating characters may be read into +memory at the end of the line, but are not included in the count u2. +The line buffer provided by c-addr should be at least u1+2 characters +long. + +

+ +If the operation succeeded, flag is true and ior is zero. If a line +terminator was received before u1 characters were read, then u2 is the +number of characters, not including the line terminator, actually read +(0 <= u2 <= u1). When u1 = u2, the line terminator has yet to be +reached. + +

+ +If the operation is initiated when the value returned by +FILE-POSITION +is equal to the value returned by +FILE-SIZE for the file identified by +fileid, flag is false, ior is zero, and u2 is zero. If ior is non-zero, +an exception occurred during the operation and ior is the +implementation-defined I/O result code. + +

+ +An ambiguous condition exists if the operation is initiated when the +value returned by FILE-POSITION is greater than the value returned by +FILE-SIZE for the file identified by fileid, or if the requested +operation attempts to read portions of the file not written. + +

+ +At the conclusion of the operation, FILE-POSITION returns the next file +position after the last character read. + +

+ +See: +A.11.6.1.2090 READ-LINE , +RFI 0001. + +

+ + +


+ + +11.6.1.2142 REPOSITION-FILE + + +
+FILE +
+
+	( ud fileid -- ior )
+
+

+ +Reposition the file identified by fileid to ud. ior is the +implementation-defined I/O result code. An ambiguous condition exists +if the file is positioned outside the file boundaries. + +

+ +At the conclusion of the operation, +FILE-POSITION returns the +value ud. + +

+ +


+ + +11.6.1.2147 RESIZE-FILE + + +
+FILE +
+
+	( ud fileid -- ior )
+
+

+ +Set the size of the file identified by fileid to ud. ior is the +implementation-defined I/O result code. + +

+ +If the resultant file is larger than the file before the operation, the +portion of the file added as a result of the operation might not have +been written. + +

+ +At the conclusion of the operation, +FILE-SIZE returns the value ud and +FILE-POSITION +returns an unspecified value. +

+ + +See: +11.6.1.2080 READ-FILE , +11.6.1.2090 READ-LINE + + +

+ +


+ + +11.6.1.2165 S" + + +
+s-quote FILE +
+

+ +Extend the semantics of +6.1.2165 S" to be: + +

+        Interpretation: ( "ccc<quote>" -- c-addr u )
+
+

+ +Parse ccc delimited by " (double quote). Store the resulting string +c-addr u at a temporary location. The maximum length of the temporary +buffer is implementation-dependent but shall be no less than 80 +characters. Subsequent uses of S" may overwrite the temporary buffer. +At least one such buffer shall be provided. + + +

+        Compilation: ( "ccc<quote>" -- )
+
+ +

+ +Parse ccc delimited by " (double quote). Append the run-time semantics +given below to the current definition. + +

+        Run-time: ( -- c-addr u )
+
+

+ +Return c-addr and u that describe a string consisting of the characters +ccc. + +

+ + +See: +3.4.1 Parsing, +6.2.0855 C" , +A.11.6.1.2165 S" , +11.3.5 Other transient regions. + + +

+ +


+ + +11.6.1.2218 SOURCE-ID + + +
+source-i-d FILE +
+
+	( -- 0 | -1 | fileid )
+
+

+ +Extend +6.2.2218 +SOURCE-ID to include text-file input as follows: + + +

+SOURCE-ID       Input source
+---------       ------------
+fileid          Text file fileid
+-1              String (via EVALUATE)
+0               User input device
+
+

+ +An ambiguous condition exists if SOURCE-ID is used when +BLK contains a +non-zero value. + +

+ +


+ + +11.6.1.2425 W/O + + +
+w-o FILE +
+
+	( -- fam )
+
+

+ +fam is the implementation-defined value for selecting the write +only file access method. +

+ + +See: +11.6.1.1010 CREATE-FILE , +11.6.1.1970 OPEN-FILE + + +

+ +


+ + +11.6.1.2480 WRITE-FILE + + +
+FILE +
+
+	( c-addr u fileid -- ior )
+
+

+ +Write u characters from c-addr to the file identified by fileid starting +at its current position. ior is the implementation-defined I/O result +code. + +

+ +At the conclusion of the operation, +FILE-POSITION returns the next file +position after the last character written to the file, and +FILE-SIZE +returns a value greater than or equal to the value returned by +FILE-POSITION. +

+ + +See: +11.6.1.2080 READ-FILE , +11.6.1.2090 READ-LINE + + +

+ +


+ + +11.6.1.2485 WRITE-LINE + + +
+FILE +
+
+	( c-addr u fileid -- ior )
+
+

+ +Write u characters from c-addr followed by the implementation-dependent +line terminator to the file identified by fileid starting at its current +position. ior is the implementation-defined I/O result code. + +

+ +At the conclusion of the operation, +FILE-POSITION returns the next file +position after the last character written to the file, and +FILE-SIZE +returns a value greater than or equal to the value returned by +FILE-POSITION. +

+ + +See: +11.6.1.2080 READ-FILE , +11.6.1.2090 READ-LINE + + +

+ +


+ +

11.6.2 File-Access extension words

+
+ + +
+ + +11.6.2.1524 FILE-STATUS + + +
+FILE EXT +
+
+	( c-addr u -- x ior )
+
+

+ +Return the status of the file identified by the character string c-addr +u. If the file exists, ior is zero; otherwise ior is the +implementation-defined I/O result code. x contains +implementation-defined information about the file. + +

+ +


+ + +11.6.2.1560 FLUSH-FILE + + +
+FILE EXT +
+
+	( fileid -- ior )
+
+

+ +Attempt to force any buffered information written to the file referred +to by fileid to be written to mass storage, and the size information for +the file to be recorded in the storage directory if changed. If the +operation is successful, ior is zero. Otherwise, it is an +implementation-defined I/O result code. + + +

+ +


+ + +11.6.2.2125 REFILL + + +
+FILE EXT +
+
+	( -- flag )
+
+

+ +Extend the execution semantics of +6.2.2125 REFILL with the +following: + +

+ +When the input source is a text file, attempt to read the next line from +the text-input file. If successful, make the result the current input +buffer, set +>IN +to zero, and return true. Otherwise return false. +

+ + +See: +7.6.2.2125 REFILL + +

+ +


+ + +11.6.2.2130 RENAME-FILE + + +
+FILE EXT +
+
+	( c-addr1 u1 c-addr2 u2 -- ior )
+
+

+ +Rename the file named by the character string c-addr1 u1 to the name in +the character string c-addr2 u2. ior is the implementation-defined I/O +result code. + + +


+ Table of Contents +
+ +Next Section +

+ + + diff --git a/docs/reference/standards/ans94/dpans12.htm b/docs/reference/standards/ans94/dpans12.htm new file mode 100644 index 00000000..92bd9e98 --- /dev/null +++ b/docs/reference/standards/ans94/dpans12.htm @@ -0,0 +1,2395 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

12. The optional Floating-Point word set

+ +
+ +

12.1 Introduction

+
+ +

+ +See: +A.12 The optional Floating-Point word set + +

+ +


+ +

12.2 Additional terms and notation

+
+ + +
+ +

12.2.1 Definition of terms

+
+ + +
+
float-aligned address: +
The address of a memory location at which a +floating-point number can be accessed. + +
double-float-aligned address: +
The address of a memory location at which +a 64-bit IEEE double-precision floating-point number can be accessed. + +
single-float-aligned address: +
The address of a memory location at which +a 32-bit IEEE single-precision floating-point number can be accessed. + +
IEEE floating-point number: +
A single- or double-precision floating-point +number as defined in ANSI/IEEE 754-1985.
+ + +

+ +


+ +

12.2.2 Notation

+
+ + +
+ +

12.2.2.1 Numeric notation

+
+ +The following notation is used to define the syntax of the external +representation of floating-point numbers: + +
    +
  • Each component of a floating-point number is defined with a rule +consisting of the name of the component (italicized in angle-brackets, +e.g.,<sign> characters := and a concatenation of tokens and +metacharacters; +
  • Tokens may be literal characters (in bold face, e.g.,E) or rule +names in angle brackets (e.g.,<digit>); +
  • The metacharacter * is used to specify zero or more occurrences +of the preceding token (e.g.,<digit>*); +
  • Tokens enclosed with [ and ] are optional (e.g.,[<sign>]); +
  • Vertical bars separate choices from a list of tokens enclosed +with braces (e.g.,{ + | - }). +
+ +

+ +


+ +

12.2.2.2 Stack notation

+
+ +Floating-point stack notation when the floating-point stack is separate +from the data stack is: +

+ +( F: before -- after ) +

+ + +


+ +

12.3 Additional usage requirements

+
+ + +
+ +

12.3.1 Data types

+
+ +Append table 12.1 to +table 3.1. + +

+ +Table 12.1 - Data Types +

+ + + +

+Symbol    Data type                       Size on stack
+------    ---------                       -------------
+r         floating-point number           implementation-defined
+f-addr    float-aligned address           1 cell
+sf-addr   single-float-aligned address    1 cell
+df-addr   double-float-aligned address    1 cell
+
+ + +

+ +


+ +

12.3.1.1 Addresses

+
+ +The set of float-aligned addresses is an implementation-defined subset +of the set of aligned addresses. Adding the size of a floating-point +number to a float-aligned address shall produce a float-aligned address. + +

+ +The set of double-float-aligned addresses is an implementation-defined +subset of the set of aligned addresses. Adding the size of a 64-bit +IEEE double-precision floating-point number to a double-float-aligned +address shall produce a double-float-aligned address. + +

+ +The set of single-float-aligned addresses is an implementation-defined +subset of the set of aligned addresses. Adding the size of a 32-bit +IEEE single-precision floating-point number to a single-float-aligned +address shall produce a single-float-aligned address. + +

+ +


+ +

12.3.1.2 Floating-point numbers

+
+ +The internal representation of a floating-point number, including the +format and precision of the significand and the format and range of the +exponent, is implementation defined. + +

+ +Any rounding or truncation of floating-point numbers is implementation +defined. + +

+ +


+ +

12.3.2 Floating-point operations

+
+ +Round to nearest means round the result of a floating-point +operation to the representable value nearest the result. If the two +nearest representable values are equally near the result, the one having +zero as its least significant bit shall be delivered. + +

+ +Round toward negative infinity means round the result of a +floating-point operation to the representable value nearest to and no +greater than the result. + +

+ +


+ +

12.3.3 Floating-point stack

+
+ +A last in, first out list that shall be used by all floating-point +operators. + +

+ +The width of the floating-point stack is implementation-defined. By +default the floating-point stack shall be separate from the data and +return stacks. A program may determine whether floating-point numbers +are kept on the data stack by passing the string +FLOATING-STACK +to +ENVIRONMENT?. + +

+ +The size +of a floating-point stack shall be at least 6 items. + +

+ +A program that depends on the floating-point stack being larger than six +items has an environmental dependency. + +

+ +


+ +

12.3.4 Environmental queries

+
+ +Append table 12.2 to +table 3.5. + +

+ + +See: +3.2.6 Environmental queries + +

+ +Table 12.2 - Environmental query strings +

+ + + +

+String          Value data type  Constant?  Meaning
+------          ---------------  ---------  -------
+FLOATING        flag             no         floating-point word set present
+FLOATING-EXT    flag             no         floating-point extensions word set present
+FLOATING-STACK  n                yes        If n = zero, floating-point numbers are 
+                                            kept on the data stack; otherwise n is 
+                                            the maximum depth of the separate 
+                                            floating-point stack.
+MAX-FLOAT       r                yes        largest usable floating-point number
+
+
+ +

+ +


+ +

12.3.5 Address alignment

+
+ +Since the address returned by a +CREATEd word is not necessarily aligned +for any particular class of floating-point data, a program shall align +the address (to be float aligned, single-float aligned, or double-float +aligned) before accessing floating-point data at the address. + +

+ + +See: +3.3.3.1 Address alignment, +A.12.3.5 Address alignment, +12.3.1.1 Addresses. + +

+ +


+ +

12.3.6 Variables

+
+ +A program may address memory in data space regions made available by +FVARIABLE. +These regions may be non-contiguous with regions +subsequently allocated with , +(comma) or +ALLOT. + +

+ + +See: +3.3.3.3 Variables + +

+ + +


+ +

12.3.7 Text interpreter input number conversion

+
+ +If the Floating-Point word set is present in the dictionary and the +current base is +DECIMAL, +the input number-conversion algorithm shall be +extended to recognize floating-point numbers in this form: + +

+ +Convertible string := <significand><exponent> + + +

+<significand> := [<sign>]<digits>[.<digits0>]
+<exponent>    := E[<sign>]<digits0>
+<sign>        := { + | - }
+<digits>      := <digit><digits0>
+<digits0>     := <digit>*
+<digit>       := { 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 }
+
+

+ +These are examples of valid representations of floating-point numbers in +program source: + +

+	1E   1.E   1.E0   +1.23E-1   -1.23E+1
+
+

+ + +See: +3.4.1.3 Text interpreter input number +conversion, +A.12.3.7 Text interpreter input number conversion, +12.6.1.0558 >FLOAT + + +

+ +


+ +

12.4 Additional documentation requirements

+
+ + +
+ +

12.4.1 System documentation

+
+ + +
+ +

12.4.1.1 Implementation-defined options

+
+ + +
    +
  • format and range of floating-point numbers +(12.3.1 Data types, +12.6.1.2143 REPRESENT); +
  • results of +12.6.1.2143 REPRESENT +when float is out of range; +
  • rounding or truncation of floating-point numbers +(12.3.1.2 +Floating-point numbers); +
  • size of floating-point stack +(12.3.3 Floating-point stack); +
  • width of floating-point stack +(12.3.3 Floating-point stack). +
+ +

+ +


+ +

12.4.1.2 Ambiguous conditions

+
+

+ +

+ +

+ +


+ +

12.4.1.3 Other system documentation

+
+ +
    +
  • no additional requirements. +
+

+ +


+ +

12.4.2 Program documentation

+
+ + +
+ +

12.4.2.1 Environmental dependencies

+
+ +
    +
  • requiring the floating-point stack to be larger than six items +(12.3.3 Floating-point stack). +
+ +

+ +


+ +

12.4.2.2 Other program documentation

+
+ +
    +
  • no additional requirements. +
+ +

+ +


+ +

12.5 Compliance and labeling

+
+ + +
+ +

12.5.1 ANS Forth systems

+
+ +The phrase Providing the Floating-Point word set shall be +appended to the label of any Standard System that provides all of the +Floating-Point word set. + +

+ +The phrase Providing name(s) from the Floating-Point Extensions word +set shall be appended to the label of any Standard System that +provides portions of the Floating-Point Extensions word set. + +

+ +The phrase Providing the Floating-Point Extensions word set shall +be appended to the label of any Standard System that provides all of the +Floating-Point and Floating-Point Extensions word sets. + +

+ +


+ +

12.5.2 ANS Forth programs

+
+ +The phrase Requiring the Floating-Point word set shall be +appended to the label of Standard Programs that require the system to +provide the Floating-Point word set. + +

+ +The phrase Requiring name(s) from the Floating-Point Extensions word +set shall be appended to the label of Standard Programs that require +the system to provide portions of the Floating-Point Extensions word +set. + +

+ +The phrase Requiring the Floating-Point Extensions word set shall +be appended to the label of Standard Programs that require the system to +provide all of the Floating-Point and Floating-Point Extensions word +sets. + +

+ +


+ +

12.6 Glossary

+
+ + +
+ +

12.6.1 Floating-Point words

+
+ + + +
+ + +12.6.1.0558 >FLOAT + + +
+to-float FLOATING +
+
+	( c-addr u -- true | false ) ( F: -- r |  )  
+	or ( c-addr u -- r true | false)
+
+ +

+ +An attempt is made to convert the string specified by c-addr and u to +internal floating-point representation. If the string represents a +valid floating-point number in the syntax below, its value r and true +are returned. If the string does not represent a valid floating-point +number only false is returned. + +

+ +A string of blanks should be treated as a special case representing +zero. + +

+ +The syntax of a convertible string := <significand>[<exponent>] + +

+<significand> := [<sign>]{<digits>[.<digits0>] |
+.<digits> }
+<exponent>    := <marker><digits0>
+<marker>      := {<e-form> | <sign-form>}
+<e-form>      := <e-char>[<sign-form>]
+<sign-form>   := { + | - }
+<e-char>      := { D | d | E | e }
+
+ +

+ +See: +A.12.6.1.0558 >FLOAT + +

+ + +


+ + +12.6.1.1130 D>F + + +
+d-to-f FLOATING +
+
+	( d -- ) ( F: -- r ) 
+        or ( d -- r )
+
+ +

+ +r is the floating-point equivalent of d. An ambiguous condition exists +if d cannot be precisely represented as a floating-point value. + +

+ +


+ + +12.6.1.1400 F! + + +
+f-store FLOATING +
+
+	( f-addr -- ) ( F: r -- ) 
+        or ( r f-addr -- )
+
+ +

+ +Store r at +f-addr. + +

+ +


+ + +12.6.1.1410 F* + + +
+f-star FLOATING +
+
+	( F: r1 r2 -- r3 ) 
+	or ( r1 r2 -- r3 )
+
+ +

+ +Multiply r1 +by r2 giving r3. + +

+ +


+ + +12.6.1.1420 F+ + + +
+f-plus FLOATING +
+
+	( F: r1 r2 -- r3 ) 
+	or ( r1 r2 -- r3 )
+
+ +

+ +Add r1 to r2 +giving the sum r3. + +

+ +


+ + +12.6.1.1425 F- + + +
+f-minus FLOATING +
+
+	( F: r1 r2 -- r3 ) 
+	or ( r1 r2 -- r3 )
+
+ +

+ +Subtract r2 from r1, +giving r3. + +

+ +


+ + +12.6.1.1430 F/ + + +
+f-slash FLOATING +
+
+	( F: r1 r2 -- r3 ) 
+	or ( r1 r2 -- r3 )
+
+ +

+ +Divide r1 by r2, giving the quotient r3. An ambiguous condition exists +if r2 is zero, or the quotient lies outside of the range of a +floating-point number. + +

+ +


+ + +12.6.1.1440 F0< + + +
+f-zero-less-than FLOATING +
+
+	( -- flag ) ( F: r -- ) 
+	or ( r -- flag )
+
+ +

+ +flag is true +if and only if r is less than zero. + +

+ +


+ + +12.6.1.1450 F0= + + +
+f-zero-equals FLOATING +
+
+	( -- flag ) ( F: r -- ) 
+	or ( r -- flag )
+
+ +

+ +flag is true +if and only if r is equal to zero. + +

+ +


+ + +12.6.1.1460 F< + + +
+f-less-than FLOATING +
+
+	( -- flag ) ( F: r1 r2 -- ) 
+	or ( r1 r2 -- flag )
+
+ +

+ +flag is true +

+if and only if r1 is less than +

+ +


+ + +12.6.1.1460 F>D + + +
+f-to-d FLOATING +
+
+	( -- d ) ( F: r -- ) 
+	or ( r -- d )
+
+ +

+ +d is the double-cell signed-integer equivalent of the integer portion of +r. The fractional portion of r is discarded. An ambiguous condition +exists if the integer portion of r cannot be precisely represented as a +double-cell signed integer. + +

+ +


+ + +12.6.1.1472 F@ + + +
+f-fetch FLOATING +
+
+	( f-addr -- ) ( F: -- r )  
+	or  ( f-addr -- r )
+
+ +

+ +r is +the value stored at f-addr. + +

+ +


+ + +12.6.1.1479 FALIGN + + +
+f-align FLOATING +
+
+	( -- )
+
+ +

+ +If the data-space pointer is not float aligned, reserve enough data +space to make it so. + +

+ +


+ + +12.6.1.1483 FALIGNED + + +
+f-aligned FLOATING +
+
+	( addr -- f-addr )
+
+

+ +f-addr is the first float-aligned address greater than or equal to addr. +

+ +


+ + +12.6.1.1492 FCONSTANT + + +
+f-constant FLOATING +
+
+	( "<spaces>name" -- ) ( F: r -- ) 
+	or ( r "<spaces>name" -- )
+
+ +

+ +Skip leading space delimiters. Parse name delimited by a space. Create +a definition for name with the execution semantics defined below. + +

+ +name is +referred to as an f-constant. + +

+        name Execution: ( -- ) ( F: -- r ) 
+			       or ( -- r )
+
+

+ +Place r +on the floating-point stack. +

+ + +See: +A.12.6.1.1492 FCONSTANT , +3.4.1 Parsing. + + +

+ +


+ + +12.6.1.1497 FDEPTH + + +
+f-depth FLOATING +
+
+	( -- +n )
+
+ +

+ ++n is the number of values contained on the default separate +floating-point stack. If floating-point numbers are kept on the data +stack, +n is the current number of possible floating-point values +contained on the data stack. + +

+ +


+ + +12.6.1.1500 FDROP + + +
+f-drop +
+FLOATING +
+	( F: r -- ) 
+	or ( r -- )
+
+ +

+ +Remove r +from the floating-point stack. + +

+ +


+ + +12.6.1.1510 FDUP + + +
+f-dupe FLOATING +
+
+	( F: r -- r r ) 
+	or ( r -- r r )
+
+ +

+ +Duplicate +r. + +

+ +


+ + +12.6.1.1552 FLITERAL + + +
+f-literal FLOATING +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+
+        Compilation: ( F: r -- ) 
+	or ( r -- )
+
+

+ +Append the run-time +semantics given below to the current definition. + +

+        Run-time: ( F: -- r ) 
+	or ( -- r )
+
+

+ +Place r +on the floating-point stack. + +

+ +See: +A.12.6.1.1552 FLITERAL + +

+ + +


+ + +12.6.1.1555 FLOAT+ + + +
+FLOAT-plus FLOATING +
+
+	( f-addr1 -- f-addr2 )
+
+ +

+ +Add the size in address units of a floating-point number to f-addr1, +giving f-addr2. + +

+ +


+ + +12.6.1.1556 FLOATS + + +
+FLOATING +
+
+	( n1 -- n2 )
+
+ +

+ +n2 is the +size in address units of n1 floating-point numbers. + +

+ +


+ + +12.6.1.1558 FLOOR + + +
+FLOATING +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +Round r1 to an integral value using the round toward negative +infinity rule, giving r2. + +

+ +


+ + +12.6.1.1562 FMAX + + +
+f-max FLOATING +
+
+	( F: r1 r2 -- r3 ) 
+	or ( r1 r2 -- r3 )
+
+ +

+ +r3 is +the greater of r1 and r2. + +

+ +


+ + +12.6.1.1565 FMIN + + +
+f-min FLOATING +
+
+	( F: r1 r2 -- r3 ) 
+	or ( r1 r2 -- r3 )
+
+ +

+ +r3 is +the lesser of r1 and r2. + +

+ +


+ + +12.6.1.1567 FNEGATE + + +
+f-negate FLOATING +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +r2 is +the negation of r1. + +

+ +


+ + +12.6.1.1600 FOVER + + +
+f-over FLOATING +
+
+	( F: r1 r2 -- r1 r2 r1 ) 
+	or ( r1 r2 -- r1 r2 r1 )
+
+ +

+ +Place a +copy of r1 on top of the floating-point stack. + +

+ +


+ + +12.6.1.1610 FROT + + +
+f-rote FLOATING +
+
+	( F: r1 r2 r3 -- r2 r3 r1 ) 
+	or ( r1 r2 r3 -- r2 r3 r1 )
+
+ +

+ +Rotate the +top three floating-point stack entries. + +

+ +


+ + +12.6.1.1612 FROUND + + +
+f-round FLOATING +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +Round r1 to +an integral value using the round to nearest rule, giving r2. +

+ + +See: +12.3.2 Floating-point operations + + +

+ +


+ + +12.6.1.1620 FSWAP + + +
+f-swap FLOATING +
+
+	( F: r1 r2 -- r2 r1 ) 
+	or ( r1 r2 -- r2 r1 )
+
+ +

+ +Exchange the +top two floating-point stack items. + +

+ +


+ + +12.6.1.1630 FVARIABLE + + +
+f-variable FLOATING +
+
+	( "<spaces>name" -- )
+
+ +

+ +Skip leading space delimiters. Parse name delimited by a space. Create +a definition for name with the execution semantics defined below. +Reserve 1 +FLOATS +address units of data space at a float-aligned address. + +

+ +name is +referred to as an f-variable. + +

+        name Execution: ( -- f-addr )
+
+

+ +f-addr is the address of the data space reserved by FVARIABLE when it +created name. A program is responsible for initializing the contents of +the reserved space. +

+ + +See: +A.12.6.1.1630 FVARIABLE , +3.4.1 Parsing. + + +

+ +


+ + +12.6.1.2143 REPRESENT + + +
+FLOATING +
+
+	( c-addr u -- n flag1 flag2 )  (F: r -- )  
+	or ( r c-addr u -- n flag1 flag2 )
+
+ +

+ +At c-addr, place the character-string external representation of the +significand of the floating-point number r. Return the decimal-base +exponent as n, the sign as flag1 and valid result as flag2. The +character string shall consist of the u most significant digits of the +significand represented as a decimal fraction with the implied decimal +point to the left of the first digit, and the first digit zero only if +all digits are zero. The significand is rounded to u digits following +the round to nearest rule; n is adjusted, if necessary, to +correspond to the rounded magnitude of the significand. If flag2 is +true then r was in the implementation-defined range of floating-point +numbers. If flag1 is true then r is negative. + +

+ +An ambiguous condition exists +if the value of +BASE is not decimal ten. + +

+ +When flag2 is false, n and flag1 are implementation defined, as are the +contents of c-addr. Under these circumstances, the string at c-addr +shall consist of graphic characters. + +

+ + +See: +3.2.1.2 Digit conversion, +12.3.2 Floating-point operations, +A.12.6.1.2143 REPRESENT + +

+ + +


+ +

12.6.2 Floating-Point extension words

+
+ + +
+ + +12.6.2.1203 DF! + + +
+d-f-store FLOATING EXT +
+
+	( df-addr -- ) ( F: r -- ) 
+	or ( r df-addr -- )
+
+ +

+ +Store the floating-point number r as a 64-bit IEEE double-precision +number at df-addr. If the significand of the internal representation of +r has more precision than the IEEE double-precision format, it will be +rounded using the round to nearest rule. An ambiguous condition +exists if the exponent of r is too large to be accommodated in IEEE +double-precision format. +

+ + +See: +12.3.1.1 Addresses, +12.3.2 Floating-point operations. + + +

+ +


+ + +12.6.2.1204 DF@ + + +
+d-f-fetch FLOATING EXT +
+
+	( df-addr -- ) ( F: -- r ) 
+	or ( df-addr -- r )
+
+ +

+ +Fetch the 64-bit IEEE double-precision number stored at df-addr to the +floating-point stack as r in the internal representation. If the IEEE +double-precision significand has more precision than the internal +representation it will be rounded to the internal representation using +the round to nearest rule. An ambiguous condition exists if the +exponent of the IEEE double-precision representation is too large to be +accommodated by the internal representation. +

+ + +See: +12.3.1.1 Addresses, +12.3.2 Floating-point operations. + + +

+ +


+ + +12.6.2.1205 DFALIGN + + +
+d-f-align FLOATING EXT +
+
+	( -- )
+
+ +

+ +If the data-space pointer is not double-float aligned, reserve enough +data space to make it so. +

+ + +See: +12.3.1.1 Addresses + + +

+ +


+ + +12.6.2.1207 DFALIGNED + + +
+d-f-aligned FLOATING EXT +
+
+	( addr -- df-addr )
+
+ +

+ +df-addr is the first double-float-aligned address greater than or equal +to addr. +

+ + +See: +12.3.1.1 Addresses + + +

+ +


+ + +12.6.2.1208 DFLOAT+ + + +
+d-float-plus FLOATING EXT +
+
+	( df-addr1 -- df-addr2 )
+
+ +

+ +Add the size in address units of a 64-bit IEEE double-precision number +to df-addr1, giving df-addr2. +

+ + +See: +12.3.1.1 Addresses + + +

+ +


+ + +2.6.2.1209 DFLOATS + + +
+d-floats FLOATING EXT +
+
+	( n1 -- n2 )
+
+ +

+ +n2 is the size in address units of n1 64-bit IEEE double-precision +numbers. + +

+ +


+ + +12.6.2.1415 F** + + +
+f-star-star FLOATING EXT +
+
+	( F: r1 r2 -- r3 ) 
+	or ( r1 r2 -- r3 )
+
+ +

+ +Raise r1 to +the power r2, giving the product r3. + +

+ +


+ + +12.6.2.1427 F. + + +
+f-dot FLOATING EXT +
+
+	( -- ) ( F: r -- ) 
+	or ( r -- )
+
+ +

+ +Display, with a trailing space, the top number on the floating-point +stack using fixed-point notation: + +

+	[-] <digits>.<digits0>
+
+

+ +An ambiguous condition exists if the value of +BASE is not (decimal) ten +or if the character string representation exceeds the size of the +pictured numeric output string buffer. +

+ + +See: +12.6.1.0558 >FLOAT , +A.12.6.1.1427 F. + + +

+ +


+ + +12.6.2.1474 FABS + + +
+f-abs FLOATING EXT +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +r2 is +the absolute value of r1. + +

+ +


+ + +12.6.2.1476 FACOS + + +
+f-a-cos FLOATING EXT +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +r2 is the principal radian angle whose cosine is r1. An ambiguous +condition exists if |r1| is greater than one. + +

+ +


+ + +12.6.2.1477 FACOSH + + +
+f-a-cosh FLOATING EXT +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +r2 is the floating-point value whose hyperbolic cosine is r1. An +ambiguous condition exists if r1 is less than one. + +

+ +


+ + +12.6.2.1484 FALOG + + +
+f-a-log FLOATING EXT +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +Raise ten +to the power r1, giving r2. + +

+ +


+ + +12.6.2.1486 FASIN + + +
+f-a-sine FLOATING EXT +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +r2 is the principal radian angle whose sine is r1. An ambiguous +condition exists if |r1| is greater than one. + +

+ +


+ + +12.6.2.1487 FASINH + + +
+f-a-cinch FLOATING EXT +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +r2 is the floating-point value whose hyperbolic sine is r1. An +ambiguous condition exists if r1 is less than zero. + +

+ +


+ + +12.6.2.1488 FATAN + + +
+f-a-tan FLOATING EXT +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +r2 is +the principal radian angle whose tangent is r1. + +

+ +


+ + +12.6.2.1489 FATAN2 + + +
+f-a-tan-two FLOATING EXT +
+
+	( F: r1 r2 -- r3 ) 
+	or ( r1 r2 -- r3 )
+
+ +

+ +r3 is the radian angle whose tangent is r1/r2. An ambiguous condition +exists if r1 and r2 are zero. + +

+ +See: +A.12.6.2.1489 FATAN2 + +

+ + +


+ + +12.6.2.1491 FATANH + + +
+f-a-tan-h FLOATING EXT +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +r2 is the floating-point value whose hyperbolic tangent is r1. An +ambiguous condition exists if r1 is outside the range of -1E0 to 1E0. + +

+ +


+ + +12.6.2.1493 FCOS + + +
+f-cos FLOATING EXT +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +r2 is the +cosine of the radian angle r1. + +

+ +


+ + +12.6.2.1494 FCOSH + + +
+f-cosh FLOATING EXT +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +r2 is +the hyperbolic cosine of r1. + +

+ +


+ + +12.6.2.1513 FE. + + +
+f-e-dot FLOATING EXT +
+
+	( -- ) ( F: r -- ) 
+	or ( r -- )
+
+ +

+ +Display, with a trailing space, the top number on the floating-point +stack using engineering notation, where the significand is greater than +or equal to 1.0 and less than 1000.0 and the decimal exponent is a +multiple of three. + +

+ +An ambiguous condition exists if the value of +BASE is not (decimal) ten +or if the character string representation exceeds the size of the +pictured numeric output string buffer. + +

+ + +See: +12.3.2 Floating-point operations, +12.6.1.2143 REPRESENT + + +

+ +


+ + +12.6.2.1515 FEXP + + +
+f-e-x-p FLOATING EXT +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +Raise e to the power r1, giving r2. + +

+ +


+ + +12.6.2.1516 FEXPM1 + + +
+f-e-x-p-m-one FLOATING EXT +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +Raise e +to the power r1 and subtract one, giving r2. + +

+ +See: +A.12.6.2.1516 FEXPM1 + +

+ + +


+ + +12.6.2.1553 FLN + + +
+f-l-n FLOATING EXT +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +r2 is the natural logarithm of r1. An ambiguous condition exists if r1 +is less than or equal to zero. + +

+ +


+ + +12.6.2.1554 FLNP1 + + +
+f-l-n-p-one FLOATING EXT +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +r2 is the natural logarithm of the quantity r1 plus one. An ambiguous +condition exists if r1 is less than or equal to negative one. + +

+ +See: +A.12.6.2.1554 FLNP1 + +

+ + +


+ + +12.6.2.1557 FLOG + + +
+f-log FLOATING EXT +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +r2 is the base-ten logarithm of r1. An ambiguous condition exists if r1 +is less than or equal to zero. + +

+ +


+ + +12.6.2.1613 FS. + + +
+f-s-dot FLOATING EXT +
+
+	( -- ) ( F: r -- ) 
+	or ( r -- )
+
+ +

+ +Display, with a trailing space, the top number on the floating-point +stack in scientific notation: + +

+	<significand><exponent>
+
+

+ +where: +

+ + +

+	<significand>  :=  [-]<digit>.<digits0>
+	<exponent>     :=  E[-]<digits>
+
+

+ +An ambiguous condition exists if the value of +BASE is not (decimal) ten +or if the character string representation exceeds the size of the +pictured numeric output string buffer. + +

+ + +See: +12.3.2 Floating-point operations, +12.6.1.2143 REPRESENT + + +

+ +


+ + +12.6.2.1614 FSIN + + +
+f-sine FLOATING EXT +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +r2 is +the sine of the radian angle r1. + +

+ +


+ + +12.6.2.1616 FSINCOS + + +
+f-sine-cos FLOATING EXT +
+
+	( F: r1 -- r2 r3 ) 
+	or ( r1 -- r2 r3 )
+
+ +

+ +r2 is the sine of the radian angle r1. r3 is the cosine of the radian +angle r1. + +

+ +See: +A.12.6.2.1489 FATAN2 + +

+ + +


+ + +12.6.2.1617 FSINH + + +
+f-cinch FLOATING EXT +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +r2 is +the hyperbolic sine of r1. + +

+ +


+ + +12.6.2.1618 FSQRT + + +
+f-square-root FLOATING EXT +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +r2 is the square root of r1. An ambiguous condition exists if r1 is +less than zero. + +

+ +


+ + +12.6.2.1625 FTAN + + +
+f-tan FLOATING EXT +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +r2 is the tangent of the radian angle r1. An ambiguous condition exists +if cos(r1) is zero. + +

+ +


+ + +12.6.2.1626 FTANH + + +
+f-tan-h FLOATING EXT +
+
+	( F: r1 -- r2 ) 
+	or ( r1 -- r2 )
+
+ +

+ +r2 is +the hyperbolic tangent of r1. + +

+ +


+ + +12.6.2.1640 F~ + + +
+f-proximate FLOATING EXT +
( +
+	( -- flag ) ( F: r1 r2 r3 -- ) 
+	or ( r1 r2 r3 -- flag )
+
+ +

+ +If r3 is positive, flag is true if the absolute value of (r1 minus r2) +is less than r3. + +

+ +If r3 is zero, flag is true if the implementation-dependent encoding of +r1 and r2 are exactly identical (positive and negative zero are unequal +if they have distinct encodings). + +

+ +If r3 is negative, flag is true if the absolute value of (r1 minus r2) +is less than the absolute value of r3 times the sum of the absolute +values of r1 and r2. + +

+ +See: +A.12.6.2.1640 F~ + +

+ + +


+ + +12.6.2.2035 PRECISION + + +
+FLOATING EXT +
+
+	( -- u )
+
+ +

+ +Return the number of significant digits currently used by +F., +FE., or +FS. as u. + +

+ +


+ + +12.6.2.2200 SET-PRECISION + + +
+FLOATING EXT +
+
+	( u -- )
+
+ +

+ +Set the number of significant digits currently used by +F., +FE., or +FS. to u. + +

+ +


+ + +12.6.2.2202 SF! + + +
+s-f-store FLOATING EXT +
+
+	( sf-addr -- ) ( F: r -- ) 
+	or ( r sf-addr -- )
+
+ +

+ +Store the floating-point number r as a 32-bit IEEE single-precision +number at sf-addr. If the significand of the internal representation of +r has more precision than the IEEE single-precision format, it will be +rounded using the round to nearest rule. An ambiguous condition +exists if the exponent of r is too large to be accommodated by the IEEE +single-precision format. +

+ + +See: +12.3.1.1 Addresses, +12.3.2 Floating-point operations. + + +

+ +


+ + +12.6.2.2203 SF@ + + +
+s-f-fetch FLOATING EXT +
+
+	( sf-addr -- ) ( F: -- r ) 
+	or ( sf-addr -- r )
+
+ +

+ +Fetch the 32-bit IEEE single-precision number stored at sf-addr to the +floating-point stack as r in the internal representation. If the IEEE +single-precision significand has more precision than the internal +representation, it will be rounded to the internal representation using +the round to nearest rule. An ambiguous condition exists if the +exponent of the IEEE single-precision representation is too large to be +accommodated by the internal representation. +

+ + +See: +12.3.1.1 Addresses, +12.3.2 Floating-point operations. + + +

+ +


+ + +12.6.2.2204 SFALIGN + + +
+s-f-align FLOATING EXT +
+
+	( -- )
+
+ +

+ +If the data-space pointer is not single-float aligned, reserve enough +data space to make it so. +

+ + +See: +12.3.1.1 Addresses + + +

+ +


+ + +12.6.2.2206 SFALIGNED + + +
+s-f-aligned FLOATING EXT +
+
+	( addr -- sf-addr )
+
+ +

+ +sf-addr is the first single-float-aligned address greater than or equal +to addr. +

+ + +See: +12.3.1.1 Addresses + + +

+ +


+ + +12.6.2.2207 SFLOAT+ + + +
+s-float-plus FLOATING EXT +
+
+	( sf-addr1 -- sf-addr2 )
+
+ +

+ +Add the size in address units of a 32-bit IEEE single-precision number +to sf-addr1, giving sf-addr2. +

+ + +See: +12.3.1.1 Addresses + + +

+ +


+ + +12.6.2.2208 SFLOATS + + +
+s-floats FLOATING EXT +
+
+	( n1 -- n2 )
+
+ +

+ +n2 is the size in address units of n1 32-bit IEEE single-precision +numbers. +

+ + +See: +12.3.1.1 Addresses + + + +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpans13.htm b/docs/reference/standards/ans94/dpans13.htm new file mode 100644 index 00000000..3bc30884 --- /dev/null +++ b/docs/reference/standards/ans94/dpans13.htm @@ -0,0 +1,606 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

13. The optional Locals word set

+ + +
+ +

13.1 Introduction

+
+ +

+ +See: +Annex A.13 The Locals Word Set + +

+ +


+ +

13.2 Additional terms and notation

+
+ +None. +

+ +


+ +

13.3 Additional usage requirements

+
+ +

+ +See: +A.13.3 Additional usage requirements + +

+ +


+ +

13.3.1 Locals

+
+ +A local is a data object whose execution semantics shall return its +value, whose scope shall be limited to the definition in which it is +declared, and whose use in a definition shall not preclude reentrancy or +recursion. + +

+ +


+ +

13.3.2 Environmental queries

+
+ +Append table 13.1 to table 3.5. +

+ + +See: +3.2.6 Environmental queries + + +

+ +Table 13.1 - Environmental query strings +

+ + + +

+String          Value data type  Constant?  Meaning
+------          ---------------  ---------  -------
+#LOCALS         n                yes        maximum number of local variables in a definition
+LOCALS          flag             no         locals word set present
+LOCALS-EXT      flag             no         locals extensions word set present
+
+ + +

+ +


+ +

13.3.3 Processing locals

+
+ +To support the locals word set, a system shall provide a mechanism to +receive the messages defined by +(LOCAL) +and respond as described here. + +

+ +During the compilation of a definition after : +(colon), +:NONAME, or +DOES>, +a program may begin sending local identifier messages to the +system. The process shall begin when the first message is sent. The +process shall end when the last local message is sent. The +system shall keep track of the names, order, and number of identifiers +contained in the complete sequence. + +

+ +


+ +

13.3.3.1 Compilation semantics

+
+ +The system, upon receipt of a sequence of local-identifier messages, +shall take the following actions at compile time: + +

+ +a) Create temporary dictionary entries for each of the identifiers +passed to +(LOCAL), +such that each identifier will behave as a local. +These temporary dictionary entries shall vanish at the end of the +definition, denoted by ; +(semicolon), +;CODE, or +DOES>. The system need +not maintain these identifiers in the same way it does other dictionary +entries as long as they can be found by normal dictionary searching +processes. Furthermore, if the Search-Order word set is present, local +identifiers shall always be searched before any of the word lists in any +definable search order, and none of the Search-Order words shall change +the locals' privileged position in the search order. Local identifiers +may reside in mass storage. + +

+ +b) For each identifier passed to (LOCAL), the system shall generate an +appropriate code sequence that does the following at execution time: + +

+ +

    +
  1. Allocate a storage resource adequate to contain the value of a local. +The storage shall be allocated in a way that does not preclude +re-entrancy or recursion in the definition using the local. +
  2. Initialize the value using the top item on the data stack. If more +than one local is declared, the top item on the stack shall be moved +into the first local identified, the next item shall be moved into the +second, and so on. +
+ +The storage resource may be the return stack or may be implemented in +other ways, such as in registers. The storage resource shall not be +the data stack. Use of locals shall not restrict use of the data +stack before or after the point of declaration. +

+ +c) Arrange that any of the legitimate methods of terminating execution +of a definition, specifically ; (semicolon), ;CODE, DOES> or +EXIT, will +release the storage resource allocated for the locals, if any, declared +in that definition. +ABORT +shall release all local storage resources, +and +CATCH / +THROW +(if implemented) shall release such resources for all +definitions whose execution is being terminated. + +

+ +d) Separate sets of locals may be declared in defining words before +DOES> for use by the defining word, and after DOES> for use by the word +defined. + +

+ +A system implementing the Locals word set shall support the declaration +of at least eight locals in a definition. + +

+ +


+ +

13.3.3.2 Syntax restrictions

+
+ +Immediate words in a program may use +(LOCAL) to implement syntaxes for +local declarations with the following restrictions: + +

+ +a) A program shall not compile any executable code into the current +definition between the time (LOCAL) is executed to identify the first +local for that definition and the time of sending the single required +last local message; + +

+ +b) The position in program source at which the sequence of (LOCAL) +messages is sent, referred to here as the point at which locals are +declared, shall not lie within the scope of any control structure; + +

+ +c) Locals shall not be declared until values previously placed on the +return stack within the definition have been removed; + +

+ +d) After a definition's locals have been declared, a program may place +data on the return stack. However, if this is done, locals shall not be +accessed until those values have been removed from the return stack; + +

+ +e) Words that return execution tokens, such as ' +(tick), +['], or +FIND, +shall not be used with local names; + +

+ +f) A program that declares more than eight locals in a single definition +has an environmental dependency; + +

+ +g) Locals may be accessed or updated within control structures, +including do-loops; + +

+ +h) Local names shall not be referenced by +POSTPONE and +[COMPILE]. +

+ + +See: +3.4 The Forth text interpreter + + +

+ +


+ +

13.4 Additional documentation requirements

+
+ + +
+ +

13.4.1 System documentation

+
+ + +
+ +

13.4.1.1 Implementation-defined options

+
+ +
    +
  • maximum number of locals in a definition +(13.3.3 Processing locals, +13.6.2.1795 LOCALS|). +
+ +

+ +


+ +

13.4.1.2 Ambiguous conditions

+
+ +
    +
  • executing a named local while in interpretation state +(13.6.1.0086 +(LOCAL)); +
  • name not defined by +VALUE or +LOCAL +(13.6.1.2295 TO). +
+ +
+ +

13.4.1.3 Other system documentation

+
+
    +
  • no additional requirements. +
+

+ +


+ +

13.4.2 Program documentation

+
+ + +
+ +

13.4.2.1 Environmental dependencies

+
+ +
    +
  • declaring more than eight locals in a single definition +(13.3.3 Processing locals). +
+ +

+ +


+ +

13.4.2.2 Other program documentation

+
+ +
    +
  • no additional requirements. +
+ +

+ +


+ +

13.5 Compliance and labeling

+
+ + +
+ +

13.5.1 ANS Forth systems

+
+ +The phrase Providing the Locals word set shall be appended to the +label of any Standard System that provides all of the Locals word set. + +

+ +The phrase Providing name(s) from the Locals Extensions word set +shall be appended to the label of any Standard System that provides +portions of the Locals Extensions word set. + +

+ +The phrase Providing the Locals Extensions word set shall be +appended to the label of any Standard System that provides all of the +Locals and Locals Extensions word sets. + +

+ +


+ +

13.5.2 ANS Forth programs

+
+ +The phrase Requiring the Locals word set shall be appended to the +label of Standard Programs that require the system to provide the Locals +word set. + +

+ +The phrase Requiring name(s) from the Locals Extensions word set +shall be appended to the label of Standard Programs that require the +system to provide portions of the Locals Extensions word set. + +

+ +The phrase Requiring the Locals Extensions word set shall be +appended to the label of Standard Programs that require the system to +provide all of the Locals and Locals Extensions word sets. + +

+ +


+ +

13.6 Glossary

+
+ + +
+ +

13.6.1 Locals words

+
+ + +
+ + +13.6.1.0086 (LOCAL) + + +
+paren-local-paren LOCAL +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Execution: ( c-addr u -- )
+
+

+ +When executed during compilation, (LOCAL) passes a message to the system +that has one of two meanings. If u is non-zero, the message identifies +a new local whose definition name is given by the string of characters +identified by c-addr u. If u is zero, the message is last local +and c-addr has no significance. + +

+ +The result of executing (LOCAL) during compilation of a definition is to +create a set of named local identifiers, each of which is a definition +name, that only have execution semantics within the scope of that +definition's source. + +

+        local Execution: ( -- x )
+
+

+ +Push the local's value, x, onto the stack. The local's value is +initialized as described in +13.3.3 Processing locals and may be changed +by preceding the local's name with +TO. An ambiguous condition exists +when local is executed while in interpretation state. +

+ +Note: This word does not have special compilation semantics in +the +usual sense because it provides access to a system capability for use +by other user-defined words that do have them. However, the locals +facility as a whole and the sequence of messages passed defines +specific usage rules with semantic implications that are described in +detail in section +13.3.3 Processing locals. + +

+ +Note: This word is not intended for direct use in a definition to +declare that definition's locals. It is instead used by system or +user compiling words. These compiling words in turn define their own +syntax, and may be used directly in definitions to declare locals. In +this context, the syntax for (LOCAL) is defined in terms of a sequence +of compile-time messages and is described in detail in section +13.3.3 Processing locals. + +

+ +Note: The Locals word set modifies the syntax and semantics of +6.2.2295 TO +as defined in the Core Extensions word set. + +

+ + +See: +3.4 The Forth text interpreter + + +

+ +


+ + +13.6.1.2295 TO + + +
+LOCAL +
+

+ +Extend the semantics of +6.2.2295 TO to be: +

+ + +

+        Interpretation: ( x "<spaces>name" -- )
+
+

+ +Skip leading spaces and parse name delimited by a space. Store x in +name. An ambiguous condition exists if name was not defined by +VALUE. + + +

+        Compilation: ( "<spaces>name" -- )
+
+

+ +Skip leading spaces and parse name delimited by a space. Append the +run-time semantics given below to the current definition. An ambiguous +condition exists if name was not defined by either VALUE or +(LOCAL). + + +

+        Run-time:       ( x -- )
+
+

+ +Store x in name. + +

+ +Note: An ambiguous condition exists if either +POSTPONE or +[COMPILE] +is applied to TO. + + +

+ + +See: +3.4.1 Parsing, +A.13.6.1.2295 TO + + +

+ +


+ +

13.6.2 Locals extension words

+
+ + +
+ + +13.6.2.1795 LOCALS| + + +
+locals-bar LOCAL EXT +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( "<spaces>name1" "<spaces>name2" ... "<spaces>namen" | -- )
+
+

+ +Create up to eight local identifiers by repeatedly skipping leading +spaces, parsing name, and executing +13.6.1.0086 (LOCAL). The list of +locals to be defined is terminated by |. Append the run-time semantics +given below to the current definition. + +

+        Run-time:       ( xn ... x2 x1 -- )
+
+

+ +Initialize up to eight local identifiers as described in +13.6.1.0086 (LOCAL), +each of which takes as its initial value the top stack item, +removing it from the stack. Identifier name1 is initialized with x1, +identifier name2 with x2, etc. When invoked, each local will return its +value. The value of a local may be changed using +13.6.1.2295 TO. + +

+ +See: +A.13.6.2.1795 LOCALS| + +

+ + +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpans14.htm b/docs/reference/standards/ans94/dpans14.htm new file mode 100644 index 00000000..9bda7077 --- /dev/null +++ b/docs/reference/standards/ans94/dpans14.htm @@ -0,0 +1,378 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

14. The optional Memory-Allocation word set

+ + +
+ +

14.1 Introduction

+
+ +

+ +See: +A.14 The optional Memory-Allocation word set + +

+ +


+ +

14.2 Additional terms and notation

+
+ +None. +

+ +


+ +

14.3 Additional usage requirements

+
+ + +
+ +

14.3.1 I/O Results data type

+
+ +I/O results are single-cell numbers indicating the result of I/O +operations. A value of zero indicates that the I/O operation completed +successfully; other values and their meanings are +implementation-defined. + +

+ +Append table 14.1 to +table 3.1. +

+ +Table 14.1 - Data types + +

+Symbol  Data type       Size on stack
+------  ---------       -------------
+ior     I/O results     1 cell
+
+ + +

+ +


+ +

14.3.2 Environmental queries

+
+ +Append table 14.2 to table 3.5. +

+ + +See: +3.2.6 Environmental queries + +

+ +Table 14.2 - Environmental query strings + +

+String             Value data type  Constant?  Meaning
+------             ---------------  ---------  -------
+MEMORY-ALLOC       flag             no         memory-allocation word set present
+MEMORY-ALLOC-EXT   flag             no         memory-allocation extensions word set present
+
+
+ +

+ +


+ +

14.3.3 Allocated regions

+
+ +A program may address memory in data space regions made available by +ALLOCATE or +RESIZE and not yet released by +FREE. + +

+ + +See: +3.3.3 Data space + +

+ + +


+ +

14.4 Additional documentation requirements

+
+ + +
+ +

14.4.1 System documentation

+
+ + +
+ +

14.4.1.1 Implementation-defined options

+
+ + + +

+ +


+ +

14.4.1.2 Ambiguous conditions

+
+ +
    +
  • no additional requirements. +
+ +
+ +

14.4.1.3 Other system documentation

+
+
    +
  • no additional requirements. +
+ +
+ +

14.4.2 Program documentation

+
+
    +
  • no additional requirements. +
+ +
+ +

14.5 Compliance and labeling

+
+ + +

+ +


+ +

14.5.1 ANS Forth systems

+
+ +The phrase Providing the Memory-Allocation word set shall be +appended to the label of any Standard System that provides all of the +Memory-Allocation word set. + +

+ +The phrase Providing name(s) from the Memory-Allocation Extensions +word set shall be appended to the label of any Standard System that +provides portions of the Memory-Allocation Extensions word set. + +

+ +The phrase Providing the Memory-Allocation Extensions word set +shall be appended to the label of any Standard System that provides all +of the Memory-Allocation and Memory-Allocation Extensions word sets. + +

+ +


+ +

14.5.2 ANS Forth programs

+
+ +The phrase Requiring the Memory-Allocation word set shall be +appended to the label of Standard Programs that require the system to +provide the Memory-Allocation word set. + +

+ +The phrase Requiring name(s) from the Memory-Allocation Extensions +word set shall be appended to the label of Standard Programs that +require the system to provide portions of the Memory-Allocation +Extensions word set. + +

+ +The phrase Requiring the Memory-Allocation Extensions word set +shall be appended to the label of Standard Programs that require the +system to provide all of the Memory-Allocation and Memory-Allocation +Extensions word sets. + +

+ +


+ +

14.6 Glossary

+
+ +
+ +

14.6.1 Memory-Allocation words

+
+ +
+ + +14.6.1.0707 ALLOCATE + + +
+MEMORY +
+
+	( u -- a-addr ior )
+
+

+ +Allocate u address units of contiguous data space. The data-space +pointer is unaffected by this operation. The initial content of the +allocated space is undefined. + +

+ +If the allocation succeeds, a-addr is the aligned starting address of +the allocated space and ior is zero. + +

+ +If the operation fails, a-addr does not represent a valid address and +ior is the implementation-defined I/O result code. + +

+ + +See: +6.1.1650 HERE , +14.6.1.1605 FREE , +14.6.1.2145 RESIZE + + +

+ +


+ + +14.6.1.1605 FREE + + +
+MEMORY +
+
+	( a-addr -- ior )
+
+

+ +Return the contiguous region of data space indicated by a-addr to the +system for later allocation. a-addr shall indicate a region of data +space that was previously obtained by +ALLOCATE or +RESIZE. The +data-space pointer is unaffected by this operation. +

+ +If the operation succeeds, ior is zero. If the operation fails, ior is +the implementation-defined I/O result code. +

+ + +See: +6.1.1650 HERE + + +

+ +


+ + +14.6.1.2145 RESIZE + + +
+MEMORY +
+
+	( a-addr1 u -- a-addr2 ior )
+
+

+ +Change the allocation of the contiguous data space starting at the +address a-addr1, previously allocated by +ALLOCATE or RESIZE, to u +address units. u may be either larger or smaller than the current size +of the region. The data-space pointer is unaffected by this operation. + +

+ +If the operation succeeds, a-addr2 is the aligned starting address of u +address units of allocated memory and ior is zero. a-addr2 may be, but +need not be, the same as a-addr1. If they are not the same, the values +contained in the region at a-addr1 are copied to a-addr2, up to the +minimum size of either of the two regions. If they are the same, the +values contained in the region are preserved to the minimum of u or the +original size. If a-addr2 is not the same as a-addr1, the region of +memory at a-addr1 is returned to the system according to the operation +of +FREE. + +

+ +If the operation fails, a-addr2 equals a-addr1, the region of memory at +a-addr1 is unaffected, and ior is the implementation-defined I/O result +code. +

+ + +See: +6.1.1650 HERE + + +

+ +


+ +

14.6.2 Memory-Allocation extension words

+
+

+ +None +

+ +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpans15.htm b/docs/reference/standards/ans94/dpans15.htm new file mode 100644 index 00000000..96c02064 --- /dev/null +++ b/docs/reference/standards/ans94/dpans15.htm @@ -0,0 +1,918 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

15. The optional Programming-Tools word set

+ +

+ +See: +15. The optional Programming-Tools word set + +

+ +


+ +

15.1 Introduction

+
+ +This optional word set contains words most often used during the development +of applications. +

+ +


+ +

15.2 Additional terms and notation

+
+ +None. +

+ +


+ +

15.3 Additional usage requirements

+
+ + +
+ +

15.3.1 Environmental queries

+
+ +Append table 15.1 to table 3.5. +

+ + +See: +3.2.6 Environmental queries + +

+ +Table 15.1 - Environmental query strings +

+ + +

+String      Value data type   Constant?  Meaning
+------      ---------------   ---------  -------
+TOOLS       flag              no         programming-tools word set present
+TOOLS-EXT   flag              no         programming-tools extensions word set present
+
+ + +

+ +


+ +

15.3.2 The Forth dictionary

+
+ +A program using the words +CODE or +;CODE +associated with assembler code has an +environmental dependency on that particular instruction set and assembler +notation. + +

+ +Programs using the words +EDITOR or +ASSEMBLER +require the +Search Order word set +or an equivalent implementation-defined capability. + +

+ + +See: +3.3 The Forth dictionary + + +

+ +


+ +

15.4 Additional documentation requirements

+
+ +
+ +

15.4.1 System documentation

+
+ +
+ +

15.4.1.1 Implementation-defined options

+
+ + + +
+ +

15.4.1.2 Ambiguous conditions

+
+ + +

+ +


+ +

15.4.1.3 Other system documentation

+
+ +
    +
  • no additional requirements. +
+

+ +


+ +

15.4.2 Program documentation

+
+ +
+ +

15.4.2.1 Environmental dependencies

+
+ + + +
+ +

15.4.2.2 Other program documentation

+
+
    +
  • no additional requirements. +
+ +

+ +


+ +

15.5 Compliance and labeling

+
+ + +
+ +

15.5.1 ANS Forth systems

+
+ +The phrase Providing the Programming-Tools word set shall be +appended to the label of any Standard System that provides all of the +Programming-Tools word set. + +

+ +The phrase Providing name(s) from the Programming-Tools Extensions +word set shall be appended to the label of any Standard System that +provides portions of the Programming-Tools Extensions word set. + +

+ +The phrase Providing the Programming-Tools Extensions word set +shall be appended to the label of any Standard System that provides all +of the Programming-Tools and Programming-Tools Extensions word sets. + +

+ +


+ +

15.5.2 ANS Forth programs

+
+ +The phrase Requiring the Programming-Tools word set shall be +appended to the label of Standard Programs that require the system to +provide the Programming-Tools word set. + +

+ +The phrase Requiring name(s) from the Programming-Tools Extensions +word set shall be appended to the label of Standard Programs that +require the system to provide portions of the Programming-Tools +Extensions word set. + +

+ +The phrase Requiring the Programming-Tools Extensions word set +shall be appended to the label of Standard Programs that require the +system to provide all of the Programming-Tools and Programming-Tools +Extensions word sets. + +

+ +


+ +

15.6 Glossary

+
+ + +
+ +

15.6.1 Programming-Tools words

+
+ + +
+ + +15.6.1.0220 .S + + +
+dot-s TOOLS +
+
+	( -- )
+
+

+ +Copy and display the values currently on the data stack. The format of +the display is implementation-dependent. + +

+ +.S may be implemented using pictured numeric output words. +Consequently, its use may corrupt the transient region identified by +#>. +

+ + +See: +A.15.6.1.0220 .S , +3.3.3.6 Other transient regions. + + +

+ +


+ + +15.6.1.0600 ? + + +
+question TOOLS +
+
+	( a-addr -- )
+
+

+ +Display the value stored at a-addr. +

+ +? may be implemented using pictured numeric output words. Consequently, +its use may corrupt the transient region identified by +#>. +

+ + +See: +3.3.3.6 Other transient regions + + +

+ +


+ + +15.6.1.1280 DUMP + + +
+TOOLS +
+
+	( addr u -- )
+
+

+ +Display the contents of u consecutive addresses starting at addr. The +format of the display is implementation dependent. + +

+ +DUMP may be implemented using pictured numeric output words. +Consequently, its use may corrupt the transient region identified by +#>. + +

+ + +See: +3.3.3.6 Other transient regions + + +

+ +


+ + +15.6.1.2194 SEE + + +
+TOOLS +
+
+	( "<spaces>name" -- )
+
+

+ +Display a human-readable representation of the named word's definition. +The source of the representation (object-code decompilation, source +block, etc.) and the particular form of the display is implementation +defined. + +

+ +SEE may be implemented using pictured numeric output words. +Consequently, its use may corrupt the transient region identified by +#>. + +

+ + +See: +3.3.3.6 Other transient regions, +A.15.6.1.2194 SEE + + +

+ +


+ + +15.6.1.2465 WORDS + + +
+TOOLS +
+
+	( -- )
+
+

+ +List the definition names in the first word list of the search order. +The format of the display is implementation-dependent. + +

+ +WORDS may be implemented using pictured numeric output words. +Consequently, its use may corrupt the transient region identified by +#>. +

+ + +See: +3.3.3.6 Other transient regions, +A.15.6.1.2465 WORDS + + +

+ +


+ +

15.6.2 Programming-Tools extension words

+
+ + +
+ + +15.6.2.0470 ;CODE + + +
+semicolon-code TOOLS EXT +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+
+        Compilation: ( C: colon-sys -- )
+
+

+ +Append the run-time semantics below to the current definition. End the +current definition, allow it to be found in the dictionary, and enter +interpretation state, consuming colon-sys. + +

+ +Subsequent characters in the parse area typically represent source code +in a programming language, usually some form of assembly language. +Those characters are processed in an implementation-defined manner, +generating the corresponding machine code. The process continues, +refilling the input buffer as needed, until an implementation-defined +ending sequence is processed. + + +

+        Run-time: ( -- ) ( R: nest-sys -- )
+
+ +

+ +Replace the execution semantics of the most recent definition with the +name execution semantics given below. Return control to the calling +definition specified by nest-sys. An ambiguous condition exists if the +most recent definition was not defined with +CREATE or a user-defined +word that calls CREATE. + +

+        name Execution: ( i*x -- j*x )
+
+

+ +Perform the machine code sequence that was generated following ;CODE. +

+ + +See: +A.15.6.2.0470 ;CODE , +6.1.1250 DOES> + + +

+ +


+ + +15.6.2.0702 AHEAD + + +
+TOOLS EXT +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+ +
+        Compilation: ( C: -- orig )
+
+ +Put the location of a new unresolved forward reference orig onto the +control flow stack. Append the run-time semantics given below to the +current definition. The semantics are incomplete until orig is resolved +(e.g., by +THEN). + + +
+        Run-time: ( -- )
+
+

+ +Continue execution at the location specified by the resolution of orig. + +

+ +


+ + +15.6.2.0740 ASSEMBLER + + +
+TOOLS EXT +
+
+	( -- )
+
+

+ +Replace the first word list in the search order with the ASSEMBLER word +list. +

+ + +See: +16. The optional Search-Order word set + + +

+ +


+ + +15.6.2.0830 BYE + + +
+TOOLS EXT +
+
+	( -- )
+
+

+ +Return control to the host operating system, if any. +

+ + +


+ + +15.6.2.0930 CODE + + +
+TOOLS EXT +
+
+	( "<spaces>name" -- )
+
+

+ +Skip leading space delimiters. Parse name delimited by a space. Create +a definition for name, called a code definition, with the +execution semantics defined below. + +

+ +Subsequent characters in the parse area typically represent source code +in a programming language, usually some form of assembly language. +Those characters are processed in an implementation-defined manner, +generating the corresponding machine code. The process continues, +refilling the input buffer as needed, until an implementation-defined +ending sequence is processed. + + +

+        name Execution: ( i*x -- j*x )
+
+

+ +Execute the machine code sequence that was generated following CODE. +

+ + +See: +A.15.6.2.0930 CODE , +3.4.1 Parsing. + + +

+ +


+ + +15.6.2.1015 CS-PICK + + +
+c-s-pick TOOLS EXT +
+

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Execution: ( C: destu ... orig0|dest0 -- destu ... orig0|dest0 destu )( S: u -- )
+
+

+ +Remove u. Copy destu to the top of the control-flow stack. An +ambiguous condition exists if there are less than u+1 items, each of +which shall be an orig or dest, on the control-flow stack before CS-PICK +is executed. + +

+ +If the control-flow stack is implemented using the data stack, u shall +be the topmost item on the data stack. + +

+ +See: +A.15.6.2.1015 CS-PICK + +

+ + +


+ + +15.6.2.1020 CS-ROLL + + +
+c-s-roll TOOLS EXT +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Execution: ( C: origu|destu origu-1|destu-1 ... orig0|dest0 --
+                          origu-1|destu-1 ... orig0|dest0 origu|destu )( S: u -- )
+
+

+ +Remove u. Rotate u+1 elements on top of the control-flow stack so that +origu|destu is on top of the control-flow stack. An ambiguous condition +exists if there are less than u+1 items, each of which shall be an orig +or dest, on the control-flow stack before CS-ROLL is executed. + +

+ +If the control-flow stack is implemented using the data stack, u shall +be the topmost item on the data stack. + +

+ +See: +A.15.6.2.1020 CS-ROLL + +

+ + +


+ + +15.6.2.1300 EDITOR + + +
+TOOLS EXT +
+
+	( -- )
+
+

+ +Replace the first word list in the search order with the EDITOR word +list. + +

+ + +See: +16. The Optional Search-Order Word Set + + +

+ +


+ + +15.6.2.1580 FORGET + + +
+TOOLS EXT +
+
+	( "<spaces>name" -- )
+
+

+ +Skip leading space delimiters. Parse name delimited by a space. Find +name, then delete name from the dictionary along with all words added to +the dictionary after name. An ambiguous condition exists if name cannot +be found. + +

+ +If the Search-Order word set is present, FORGET searches the compilation +word list. An ambiguous condition exists if the compilation word list +is deleted. + +

+ +An ambiguous condition exists if FORGET removes a word required for +correct execution. + +

+ +Note: This word is obsolescent and is included as a concession to +existing implementations. + +

+ + +See: +A.15.6.2.1580 FORGET , +3.4.1 Parsing, +6.2.1850 MARKER + +

+ +


+ + +15.6.2.2250 STATE + + +
+TOOLS EXT +
+
+	( -- a-addr )
+
+

+ +Extend the semantics of +6.1.2250 STATE to allow +;CODE to change the +value in STATE. A program shall not directly alter the contents of +STATE. + +

+ + +See: +3.4 The Forth text interpreter, +6.1.0450 : , +6.1.0460 ; , +6.1.0670 ABORT , +6.1.2050 QUIT , +6.1.2500 [ , +6.1.2540 ] , +6.2.0455 :NONAME + + +

+ +


+ + +15.6.2.2531 [ELSE] + + +
+bracket-else TOOLS EXT +
+

+

+	Compilation: Perform the execution semantics given below.
+
+
+        Execution: ( "<spaces>name" ... -- )
+
+

+ +Skipping leading spaces, parse and discard space-delimited words from +the parse area, including nested occurrences of +[IF] ... +[THEN] and +[IF] ... [ELSE] ... [THEN], until the word [THEN] has been parsed and +discarded. If the parse area becomes exhausted, it is refilled as with +REFILL. +[ELSE] is an immediate word. + +

+ + +See: +3.4.1 Parsing, +A.15.6.2.2531 [ELSE] + + +

+ +


+ + +15.6.2.2532 [IF] + + +
+bracket-if TOOLS EXT +
+

+

+	Compilation: Perform the execution semantics given below.
+
+

+

+	Execution: ( flag | flag "<spaces>name" ... -- )
+
+

+ +If flag is true, do nothing. Otherwise, skipping leading spaces, parse +and discard space-delimited words from the parse area, including nested +occurrences of [IF] ... +[THEN] and [IF] ... +[ELSE] ... [THEN], until +either the word [ELSE] or the word [THEN] has been parsed and discarded. +If the parse area becomes exhausted, it is refilled as with +REFILL. +[IF] is an immediate word. + +

+ +An ambiguous condition exists if [IF] is +POSTPONEd, or if the end of the +input buffer is reached and cannot be refilled before the terminating +[ELSE] or [THEN] is parsed. + +

+ + +See: +3.4.1 Parsing, +A.15.6.2.2532 [IF] + + +

+ +


+ + +15.6.2.2533 [THEN] + + +
+bracket-then TOOLS EXT +
+

+

+	Compilation: Perform the execution semantics given below.
+
+

+

+	Execution: ( -- )
+
+

+ +Does nothing. [THEN] is an immediate word. +

+ +See: +A.15.6.2.2533 [THEN] + +

+ +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpans16.htm b/docs/reference/standards/ans94/dpans16.htm new file mode 100644 index 00000000..92369e39 --- /dev/null +++ b/docs/reference/standards/ans94/dpans16.htm @@ -0,0 +1,681 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

16. The optional Search-Order word set

+ +

+ +See: +A.16 The optional Search-Order word set + +

+ +


+ +

16.1 Introduction

+
+ +
+ +

16.2 Additional terms and notation

+
+ +
compilation word list: +
The word list into which new definition names are +placed. + +
search order: +
A list of word lists specifying the order in which the +dictionary will be searched.
+ +

+ +See: +A.16.2 Additional terms + +

+ +


+ +

16.3 Additional usage requirements

+
+ +
+ +

16.3.1 Data types

+
+ +Word list identifiers are implementation-dependent single-cell values +that identify word lists. +

+ +Append table 16.1 to +table 3.1. +

+ +Table 16.1 - Data types +

+ +

+Symbol  Data type               Size on stack
+------  ---------               -------------
+wid     word list identifiers   1 cell
+
+

+ + +See: +3.1 Data types, +3.4.2 Finding definition names, +3.4 The Forth text interpreter. + +

+ +


+ +

16.3.2 Environmental queries

+
+ +Append table 16.2 to table 3.5. +

+ + +See: +3.2.6 Environmental queries + +

+ +Table 16.2 - Environmental query strings +

+ +

+String            Value data type  Constant?  Meaning
+------            ---------------  ---------  -------
+SEARCH-ORDER      flag             no         search-order word set present
+SEARCH-ORDER-EXT  flag             no         search-order extensions word set present
+WORDLISTS         n                yes        maximum number of word lists usable
+                                                in the search order
+
+
+ +

+ +


+ +

16.3.3 Finding definition names

+
+ +When searching a word list for a definition name, the system shall +search each word list from its last definition to its first. The search +may encompass only a single word list, as with +SEARCH-WORDLIST, or all +the word lists in the search order, as with the text interpreter and +FIND. + +

+ +Changing the search order shall only affect the subsequent finding of +definition names in the dictionary. + +

+ +A system with the Search-Order word set shall allow at least eight word +lists in the search order. + +

+ +An ambiguous condition exists if a program changes the compilation word +list during the compilation of a definition or before modification of +the behavior of the most recently compiled definition with +;CODE, +DOES>, +or +IMMEDIATE. + +

+ +A program that requires more than eight word lists in the search order +has an environmental dependency. + +

+ + +See: +3.4.2 Finding definition names, +A.16.3.3 Finding definition names. + +

+ +


+ +

16.3.4 Contiguous regions

+
+ +The regions of data space produced by the operations described in +3.3.3.2 +Contiguous regions may be non-contiguous if +WORDLIST is executed +between allocations. + +

+ +


+ +

16.4 Additional documentation requirements

+
+ +
+ +

16.4.1 System documentation

+
+ +
+ +

16.4.1.1 Implementation-defined options

+
+ + +

+ +


+ +

16.4.1.2 Ambiguous conditions

+
+ +
    +
  • changing the compilation word list +(16.3.3 Finding definition names); +
  • search order empty +(16.6.2.2037 PREVIOUS); +
  • too many word lists in search order +(16.6.2.0715 ALSO). +
+ +
+ +

16.4.1.3 Other system documentation

+
+
    +
  • no additional requirements. +
+ + +
+ +

16.4.2 Program documentation

+
+ + +
+ +

16.4.2.1 Environmental dependencies

+
+ +
    +
  • requiring more than eight word-lists in the search order +(16.3.3 Finding definition names). +
+ + +
+ +

16.4.2.2 Other program documentation

+
+ +
    +
  • no additional requirements. +
+ +
+ +

16.5 Compliance and labeling

+
+ +
+ +

16.5.1 ANS Forth systems

+
+ +The phrase Providing the Search-Order word set shall be appended +to the label of any Standard System that provides all of the +Search-Order word set. + +

+ +The phrase Providing name(s) from the Search-Order Extensions word +set shall be appended to the label of any Standard System that +provides portions of the Search-Order Extensions word set. + +

+ +The phrase Providing the Search-Order Extensions word set shall +be appended to the label of any Standard System that provides all of the +Search-Order and Search-Order Extensions word sets. + +

+ +


+ +

16.5.2 ANS Forth programs

+
+ +The phrase Requiring the Search-Order word set shall be appended +to the label of Standard Programs that require the system to provide the +Search-Order word set. + +

+ +The phrase Requiring name(s) from the Search-Order Extensions word +set shall be appended to the label of Standard Programs that require +the system to provide portions of the Search-Order Extensions word set. + +

+ +The phrase Requiring the Search-Order Extensions word set shall +be appended to the label of Standard Programs that require the system to +provide all of the Search-Order and Search-Order Extensions word sets. + +

+ +


+ +

16.6 Glossary

+
+ +
+ +

16.6.1 Search-Order words

+
+ +
+ + +16.6.1.1180 DEFINITIONS + + +
+SEARCH +
+
+	( -- )
+
+

+ +Make the compilation word list the same as the first word list in the +search order. Specifies that the names of subsequent definitions will +be placed in the compilation word list. Subsequent changes in the +search order will not affect the compilation word list. + +

+ + +See: +16.3.3 Finding Definition Names + + +

+ +


+ + +16.6.1.1550 FIND + + +
+SEARCH +
+

+ +Extend the semantics of +6.1.1550 FIND to be: +

+ +

+	( c-addr -- c-addr 0  |  xt 1  |  xt -1 )
+
+

+ +Find the definition named in the counted string at c-addr. If the +definition is not found after searching all the word lists in the search +order, return c-addr and zero. If the definition is found, return xt. +If the definition is immediate, also return one (1); otherwise also +return minus-one (-1). For a given string, the values returned by FIND +while compiling may differ from those returned while not compiling. + +

+ + +See: +3.4.2 Finding definition names, +6.1.0070 ' , +6.1.2033 POSTPONE , +6.1.2510 ['] , +D.6.7 Immediacy. + + +

+ +


+ + +16.6.1.1595 FORTH-WORDLIST + + +
+SEARCH +
+
+	( -- wid )
+
+

+ +Return wid, the identifier of the word list that includes all standard +words provided by the implementation. This word list is initially the +compilation word list and is part of the initial search order. + +

+ +


+ + +16.6.1.1643 GET-CURRENT + + +
+SEARCH +
+
+	( -- wid )
+
+

+ +Return wid, the identifier of the compilation word list. +

+ +


+ + +16.6.1.1647 GET-ORDER + + +
+SEARCH +
+
+	( -- widn ... wid1 n )
+
+

+ +Returns the number of word lists n in the search order and the word list +identifiers widn ... wid1 identifying these word lists. wid1 +identifies the word list that is searched first, and widn the word list +that is searched last. The search order is unaffected. + +

+ +See: +RFI 0002 + +

+ +


+ + +16.6.1.2192 SEARCH-WORDLIST + + +
+SEARCH +
+
+	( c-addr u wid -- 0 | xt 1 | xt -1 )
+
+

+ +Find the definition identified by the string c-addr u in the word list +identified by wid. If the definition is not found, return zero. If the +definition is found, return its execution token xt and one (1) if the +definition is immediate, minus-one (-1) otherwise. + +

+ +See: +A.16.6.1.2192 SEARCH-WORDLIST + +

+ +


+ + +16.6.1.2195 SET-CURRENT + + +
+SEARCH +
+
+	( wid -- )
+
+

+ +Set the compilation word list to the word list identified by wid. + +

+ +


+ + +16.6.1.2197 SET-ORDER + + +
+SEARCH +
+
+	( widn ... wid1 n -- )
+
+

+ +Set the search order to the word lists identified by widn ... wid1. +Subsequently, word list wid1 will be searched first, and word list widn +searched last. If n is zero, empty the search order. If n is minus +one, set the search order to the implementation-defined minimum search +order. The minimum search order shall include the words +FORTH-WORDLIST +and SET-ORDER. A system shall allow n to be at least eight. + +

+ +See: +RFI 0002 + +

+ +


+ + +16.6.1.2460 WORDLIST + + +
+SEARCH +
+
+	( -- wid )
+
+

+ +Create a new empty word list, returning its word list identifier wid. +The new word list may be returned from a pool of preallocated word lists +or may be dynamically allocated in data space. A system shall allow the +creation of at least 8 new word lists in addition to any provided as +part of the system. + +

+ +


+ +

16.6.2 Search-Order extension words

+
+ + +
+ + +16.6.2.0715 ALSO + + +
+SEARCH EXT +
+
+	( -- )
+
+

+ +Transform the search order consisting of widn, ... wid2, wid1 (where +wid1 is searched first) into widn, ... wid2, wid1, wid1. An ambiguous +condition exists if there are too many word lists in the search order. + +

+ +See: +A.16.6.2.0715 ALSO , +RFI 0002 + +

+ + +


+ + +16.6.2.1590 FORTH + + +
+SEARCH EXT +
+
+	( -- )
+
+

+ +Transform the search order consisting of widn, ... wid2, wid1 (where +wid1 is searched first) into widn, ... wid2, +wid FORTH-WORDLIST. + +

+ +


+ + +16.6.2.1965 ONLY + + +
+SEARCH EXT +
+
+	( -- )
+
+

+ +Set the search order to the implementation-defined minimum search order. +The minimum search order shall include the words +FORTH-WORDLIST and +SET-ORDER. + +

+ +See: +RFI 0002 + +

+ +


+ + +16.6.2.1985 ORDER + + +
+SEARCH EXT +
+
+	( -- )
+
+

+ +Display the word lists in the search order in their search order +sequence, from first searched to last searched. Also display the word +list into which new definitions will be placed. The display format is +implementation dependent. + +

+ +ORDER may be implemented using pictured numeric output words. +Consequently, its use may corrupt the transient region identified by +#>. +

+ + +See: +3.3.3.6 Other Transient Regions + +

+ +


+ + +16.6.2.2037 PREVIOUS + + +
+SEARCH EXT +
+
+	( -- )
+
+

+ +Transform the search order consisting of widn, ... wid2, wid1 (where +wid1 is searched first) into widn, ... wid2. An ambiguous condition +exists if the search order was empty before PREVIOUS was executed. + +

+ +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpans17.htm b/docs/reference/standards/ans94/dpans17.htm new file mode 100644 index 00000000..1c96ae87 --- /dev/null +++ b/docs/reference/standards/ans94/dpans17.htm @@ -0,0 +1,372 @@ + + +DPANS94 + + + + + + + +
+ + + + +Table of Contents +
+

+


+ + +

17. The optional String word set

+ + +
+ +

17.1 Introduction

+
+ + +
+ +

17.2 Additional terms and notation

+
+ +None. +

+ + +


+ +

17.3 Additional usage requirements

+
+ +Append table 17.1 to table 3.5. +

+ + +See: +3.2.6 Environmental queries + +

+ +Table 17.1 - Environmental query strings + + +

+String         Value data type    Constant?   Meaning
+------         ---------------    ---------   -------
+STRING          flag              no          string word set present
+STRING-EXT      flag              no          string extensions word set present
+
+

+ + +


+ +

17.4 Additional documentation requirements

+
+ +None. +

+ +


+ +

17.5 Compliance and labeling

+
+ +
+ +

17.5.1 ANS Forth systems

+
+ +The phrase Providing the String word set shall be appended to the +label of any Standard System that provides all of the String word set. +

+ +The phrase Providing name(s) from the String Extensions word set +shall be appended to the label of any Standard System that provides +portions of the String Extensions word set. +

+ +The phrase Providing the String Extensions word set shall be +appended to the label of any Standard System that provides all of the +String and String Extensions word sets. +

+ + +


+ +

17.5.2 ANS Forth programs

+
+ +The phrase Requiring the String word set shall be appended to the +label of Standard Programs that require the system to provide the String +word set. + +

+ +The phrase Requiring name(s) from the String Extensions word set +shall be appended to the label of Standard Programs that require the +system to provide portions of the String Extensions word set. + +

+ +The phrase Requiring the String Extensions word set shall be +appended to the label of Standard Programs that require the system to +provide all of the String and String Extensions word sets. + + +

+ +


+ +

17.6 Glossary

+
+ + +
+ +

17.6.1 String words

+
+ + +
+ + +17.6.1.0170 -TRAILING + + +
+dash-trailing STRING +
+
+	( c-addr u1 -- c-addr u2 )
+
+

+ +If u1 is greater than zero, u2 is equal to u1 less the number of spaces +at the end of the character string specified by c-addr u1. If u1 is +zero or the entire string consists of spaces, u2 is zero. + +

+ +


+ + +17.6.1.0245 /STRING + + +
+slash-string STRING +
+
+	( c-addr1 u1 n -- c-addr2 u2 )
+
+

+ +Adjust the character string at c-addr1 by n characters. The resulting +character string, specified by c-addr2 u2, begins at c-addr1 plus n +characters and is u1 minus n characters long. + +

+ +See: +A.17.6.1.0245 /STRING + +

+ +


+ + +17.6.1.0780 BLANK + + +
+STRING +
+
+	( c-addr u -- )
+
+

+ +If u is greater than zero, store the character value for space in u +consecutive character positions beginning at c-addr. +

+ +


+ + +17.6.1.0910 CMOVE + + +
+c-move STRING +
+
+	( c-addr1 c-addr2 u -- )
+
+

+ +If u is greater than zero, copy u consecutive characters from the data +space starting at c-addr1 to that starting at c-addr2, proceeding +character-by-character from lower addresses to higher addresses. + +

+ +See: +A.17.6.1.0910 CMOVE , +17.6.1.0920 CMOVE> + +

+ + +


+ + +17.6.1.0920 CMOVE> + + +
+c-move-up STRING +
+
+	( c-addr1 c-addr2 u -- )
+
+

+ +If u is greater than zero, copy u consecutive characters from the data +space starting at c-addr1 to that starting at c-addr2, proceeding +character-by-character from higher addresses to lower addresses. + +

+ +See: +17.6.1.0910 CMOVE , +A.17.6.1.0920 CMOVE> + +

+ + +


+ + +17.6.1.0935 COMPARE + + +
+STRING +
+
+	( c-addr1 u1 c-addr2 u2 -- n )
+
+

+ +Compare the string specified by c-addr1 u1 to the string specified by +c-addr2 u2. The strings are compared, beginning at the given addresses, +character by character, up to the length of the shorter string or until +a difference is found. If the two strings are identical, n is zero. If +the two strings are identical up to the length of the shorter string, n +is minus-one (-1) if u1 is less than u2 and one (1) otherwise. If the +two strings are not identical up to the length of the shorter string, n +is minus-one (-1) if the first non-matching character in the string +specified by c-addr1 u1 has a lesser numeric value than the +corresponding character in the string specified by c-addr2 u2 and one +(1) otherwise. + +

+ +See: +A.17.6.1.0935 COMPARE + +

+ + +


+ + +17.6.1.2191 SEARCH + + +
+STRING +
+
+	( c-addr1 u1 c-addr2 u2 -- c-addr3 u3 flag )
+
+

+ +Search the string specified by c-addr1 u1 for the string specified by +c-addr2 u2. If flag is true, a match was found at c-addr3 with u3 +characters remaining. If flag is false there was no match and c-addr3 +is c-addr1 and u3 is u1. + +

+ +See: +A.17.6.1.2191 SEARCH + +

+ + +


+ + +17.6.1.2212 SLITERAL + + +
+STRING +
+

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+
+        Compilation: ( c-addr1 u -- )
+
+ +

+ +Append the run-time semantics given below to the current definition. +

+ + +

+        Run-time:       ( -- c-addr2 u )
+
+

+ +Return c-addr2 u describing a string consisting of the characters +specified by c-addr1 u during compilation. A program shall not alter +the returned string. + +

+ +See: +A.17.6.1.2212 SLITERAL + +

+ + +


+ +

17.6.2 String extension words

+
+ +None +

+ + + +Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpans2.htm b/docs/reference/standards/ans94/dpans2.htm new file mode 100644 index 00000000..d1605950 --- /dev/null +++ b/docs/reference/standards/ans94/dpans2.htm @@ -0,0 +1,534 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

2. Terms, notation, and references

+ +The phrase See: is used throughout this Standard to direct the reader to +other sections of the Standard that have a direct bearing on the current +section. + +

+ +In this Standard, shall states a requirement on a system or +program; conversely, shall not is a prohibition; need not +means is not required to; should describes a +recommendation of the Standard; and may, depending on context, +means is allowed to or might happen. + +

+ +Throughout the Standard, +typefaces are used in the following manner: + +

    +
  • This proportional +serif typeface is used for text, with italic used +for symbols and the first appearance of new terms; +
  • A bold +proportional sans-serif typeface is used for headings; +
  • A bold +monospaced serif typeface is used for Forth-language text. +
+ +

+ +


+ +

2.1 Definitions of terms

+
+ +Terms defined in this section are used generally throughout this Standard. +Additional terms specific to individual word sets are defined in those word +sets. Other terms are defined at their first appearance, indicated by italic +type. Terms not defined in this Standard are to be construed according to the +Dictionary for Information Systems, ANSI X3.172-1990. + +

+ +

address unit:
Depending on context, either 1) the units +into which a Forth +address space is divided for the purposes of locating data objects such as +characters and variables; 2) the physical memory storage elements +corresponding to those units; 3) the contents of such a memory storage +element; or 4) the units in which the length of a region of memory is +expressed. + +
aligned address:
The address of a memory location at which a +character, cell, +cell pair, or double-cell integer can be accessed. + +
ambiguous condition:
A circumstance for which this Standard +does not +prescribe a specific behavior for Forth systems and programs. + +

+ +Ambiguous conditions include such things as the absence of a needed delimiter +while parsing, attempted access to a nonexistent file, or attempted use of a +nonexistent word. An ambiguous condition also exists when a Standard word is +passed values that are improper or out of range. + +

cell: +
The primary unit of information in the architecture of a Forth system. + +
cell pair: +
Two cells that are treated as a single unit. + +
character: +
Depending on context, either 1) a storage unit capable of holding +a character; or 2) a member of a character set. + +
character-aligned address: +
The address of a memory location at which a +character can be accessed. + +
character string: +
Data space that is associated with a sequence of +consecutive character-aligned addresses. Character strings usually +contain text. Unless otherwise indicated, the term string means +character string. + +
code space: +
The logical area of the dictionary in which word semantics are +implemented. + +
compile: +
To transform +source code into dictionary definitions. + +
compilation semantics: +
The behavior of a Forth definition when its name is +encountered by the text interpreter in compilation state. + +
counted string: +
A data structure consisting of one character containing a +length followed by zero or more contiguous data characters. Normally, counted +strings contain text. + +
cross compiler: +
A system that compiles a program for later execution in +an environment that may be physically and logically different from the +compiling environment. In a cross compiler, the term host +applies to the compiling environment, and the term target applies +to the run-time environment. + +
current definition: +
The definition whose compilation has been started but not +yet ended. + +
data field: +
The data space +associated with a word defined via +CREATE. + +
data space: +
The logical +area of the dictionary that can be accessed. + +
data-space pointer: +
The address of the next available data space location, +i.e., the value returned by +HERE. + +
data stack: +
A stack that may be used for passing parameters between +definitions. When there is no possibility of confusion, the data stack is +referred to as the stack. Contrast with return stack. + +
data type: +
An identifier +for the set of values that a data object may have. + +
defining word: +
A Forth word +that creates a new definition when executed. + +
definition: +
A Forth execution +procedure compiled into the dictionary. + +
dictionary: +
An extensible structure that contains definitions and associated +data space. + +
display: +
To send one or more +characters to the user output device. + +
environmental dependencies: +
A program's implicit assumptions about a Forth +system's implementation options or underlying hardware. For example, a +program that assumes a cell size greater than 16 bits is said to have an +environmental dependency. + +
execution semantics: +
The behavior +of a Forth definition when it is executed. + +
execution token: +
A value that identifies the execution semantics of a +definition. + +
find: +
To search the +dictionary for a definition name matching a given string. + +
immediate word: +
A Forth word whose compilation semantics are to perform its +execution semantics. + +
implementation defined: +
Denotes system behaviors or features that must be +provided and documented by a system but whose further details are not +prescribed by this Standard. + +
implementation dependent: +
Denotes system behaviors or features that must be +provided by a system but whose further details are not prescribed by this +Standard. + +
input buffer: +
A region of memory containing the sequence of characters from +the input source that is currently accessible to a program. + +
input source: +
The device, file, block, or other entity that supplies +characters to refill the input buffer. + +
input source specification: +
A set of information describing a particular +state of the input source, input buffer, and parse area. This information is +sufficient, when saved and restored properly, to enable the nesting of parsing +operations on the same or different input sources. + +
interpretation semantics: +
The behavior of a Forth definition when its name is +encountered by the text interpreter in interpretation state. + +
initiation semantics: +
The behavior of a Forth definition, or of the portion of a Forth definition +following DOES>, when it begins execution. + +
keyboard event: +
A value received by the system denoting a user action at the +user input device. The term keyboard in this document does not exclude +other types of user input devices. + +
line: +
A sequence of characters followed by an actual or implied line +terminator. + +
name space: +
The logical area of the dictionary in which definition names are +stored. + +
number: +
In this Standard, number used without other qualification +means integer. Similarly, double number means +double-cell integer. + +
parse: +
To select and exclude a character string from the parse area using a +specified set of delimiting characters, called delimiters. + +
parse area: +
The portion of the input buffer that has not yet been parsed, and +is thus available to the system for subsequent processing by the text +interpreter and other parsing operations. + +
pictured-numeric output: +
A number display format in which the number is +converted using Forth words that resemble a symbolic picture of +the desired output. + +
program: +
A complete specification of execution to achieve a specific function +(application task) expressed in Forth source code form. + +
receive: +
To obtain characters +from the user input device. + +
return stack: +
A stack that may be used for program execution nesting, do-loop +execution, temporary storage, and other purposes. + +
standard word: +
A named Forth +procedure, formally specified in this Standard. + +
user input device: +
The input device currently selected as the source of +received data, typically a keyboard. + +
user output device: +
The output device currently selected as the destination +of display data. + +
variable: +
A named region of data space located and accessed by its memory +address. + +
word: +
Depending on context, either 1) the name of a Forth definition; or 2) a +parsed sequence of non-space characters, which could be the name of a Forth +definition. + +
word list: +
A list of associated Forth definition names that may be examined +during a dictionary search. + +
word set: +
A set of Forth definitions grouped together in this Standard under +a name indicating some shared aspect, typically their common functional +area.
+ +

+ +See: +A.2.1 Definition of terms, +RFI 0005 Initiation semantics, +RFI 0007 Distinction between immediacy and special compilation semantics. + +

+ +


+ +

2.2 Notation

+
+ + + +
+ +

2.2.1 Numeric notation

+
+ +Unless otherwise stated, all references to numbers apply to signed single-cell +integers. The inclusive range of values is shown as {from...to}. The +allowable range for the contents of an address is shown in double braces, +particularly for the contents of variables, e.g., +BASE {{2...36}}. + +

+ +


+ +

2.2.2 Stack notation

+
+ +Stack parameters input to and output from a definition are described using the +notation: + + +
+
+( stack-id  before -- after )
+
+
+ +

+ +where stack-id specifies which stack is being described, before represents the +stack-parameter data types before execution of the definition and after +represents them after execution. The symbols used in before and after are +shown in +table 3.1. + +

+ +The control-flow-stack stack-id is C:, the data-stack stack-id is +S:, and the return-stack stack-id is R:. When there is no +confusion, the data-stack stack-id may be omitted. + +

+ +When there are alternate after representations, they are described by +after1 | after2. The top of the stack is to the right. Only +those stack items required for or provided by execution of the +definition are shown. + +

+ +See: +A.2.2.2 Stack notation + +

+ + +


+ +

2.2.3 Parsed-text notation

+
+ +If, in addition to using stack parameters, a definition parses text, +that text is specified by an abbreviation from table 2.1, shown +surrounded by double-quotes and placed between the before parameters and +the -- separator in the first stack described, e.g., + + +
+( S: before "parsed-text-abbreviation" -- after ).
+
+ +

+ + +Table 2.1 - Parsed text abbreviations + + +

+ + +

+Abbreviation    Description
+------------    -----------
+<char>          the delimiting character marking the end of the
+                string being parsed
+<chars>         zero or more consecutive occurrences of the
+                character char
+<space>         a delimiting space character
+<spaces>        zero or more consecutive occurrences of the
+                character space
+<quote>         a delimiting double quote
+<paren>         a delimiting right parenthesis
+<eol>           an implied delimiter marking the end of a line
+ccc             a parsed sequence of arbitrary characters,
+                excluding the delimiter character
+name            a token delimited by space, equivalent to
+                ccc<space> or ccc<eol>
+
+ +

+ +


+ +

2.2.4 Glossary notation

+
+ +The glossary entries for each word set are listed in the standard ASCII +collating sequence. Each glossary entry specifies an ANS Forth word and +consists of two parts: an index line and the semantic description of the +definition. + +

+ +


+ +

2.2.4.1 Glossary index line

+
+ +The index line is a single-line entry containing, from left to right: +

+ +

    +
  • Section number, +the last four digits of which assign a unique +sequential number to all words included in this Standard; +
  • DEFINITION-NAME +in upper-case, mono-spaced, bold-face letters; +
  • Natural-language +pronunciation in quotes if it differs from English; +
  • Word-set +designator from table 2.2. The designation for extensions +word sets includes EXT. +
+ +

+ + +Table 2.2 - Word set designators + +

+ + +

+Word set                        Designator
+--------                        ----------
+Core word set                   CORE
+Block word set                  BLOCK
+Double-Number word set          DOUBLE
+Exception word set              EXCEPTION
+Facility word set               FACILITY
+File-Access word set            FILE
+Floating-Point word set         FLOATING
+Locals word set                 LOCALS
+Memory-Allocation word set      MEMORY
+Programming-Tools word set      TOOLS
+Search-Order word set           SEARCH
+String-Handling word set        STRING
+
+ +

+ +


+ +

2.2.4.2 Glossary semantic description

+
+ +The first paragraph of the semantic description contains a stack notation for +each stack affected by execution of the word. The remaining paragraphs +contain a text description of the semantics. See +3.4.3 Semantics. + +

+ +


+ +

2.3 References

+
+ +The following national and international standards are referenced in this +Standard: + +

+ +ANSI X3.172-1990, Dictionary for information systems +(2.1 Definition of terms); + +

+ +ANSI X3.4-1974, American Standard Code for Information Interchange +(ASCII) +(3.1.2.1 Graphic characters); + +

+ +ISO 646-1983, ISO 7-bit coded characterset for information +interchange, International Reference Version (IRV) +(3.1.2.1 Graphic characters); + +

+ +ANSI/IEEE 754-1985, Floating-point standard +(12.2.1 Definition of terms). + + +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpans3.htm b/docs/reference/standards/ans94/dpans3.htm new file mode 100644 index 00000000..4025fe09 --- /dev/null +++ b/docs/reference/standards/ans94/dpans3.htm @@ -0,0 +1,1779 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

3. Usage requirements

+ +A system shall provide all of the words defined in +6.1 Core Words. It +may also provide any words defined in the optional word sets and +extensions word sets. No standard word provided by a system shall alter +the system state in a way that changes the effect of execution of any +other standard word except as provided in this Standard. A system may +contain non-standard extensions, provided that they are consistent with +the requirements of this Standard. + +

+ +The implementation of a system may use words and techniques outside the +scope of this Standard. + +

+ +A system need not provide all words in executable form. The +implementation may provide definitions, including definitions of words +in the Core word set, in source form only. If so, the mechanism for +adding the definitions to the dictionary is implementation defined. + +

+ +A program that requires a system to provide words or techniques not +defined in this Standard has an environmental dependency. + +

+ +See: +A.3 Usage requirements + +

+ +


+ +

3.1 Data types

+
+ +A data type identifies the set of permissible values for a data object. +It is not a property of a particular storage location or position on a +stack. Moving a data object shall not affect its type. + +

+ +No data-type checking is required of a system. An ambiguous condition +exists if an incorrectly typed data object is encountered. + +

+ +Table 3.1 summarizes the data types used throughout this Standard. +Multiple instances of the same type in the description of a definition +are suffixed with a sequence digit subscript to distinguish them. + +

+ +See: +A.3.1 Date-types + +

+ +


+ +

3.1.1 Data-type relationships

+
+ +Some of the data types are subtypes of other data types. A data type i +is a subtype of type j if and only if the members of i are a subset of +the members of j. The following list represents the subtype +relationships using the phrase i => j to denote i is a subtype +of j. The subtype relationship is transitive; if i => j and j => k +then i => k: + +
+	+n => u => x;
+	+n => n => x;
+	char => +n;
+	a-addr => c-addr => addr => u;
+	flag => x;
+	xt => x;
+	+d => d => xd;
+	+d => ud => xd.
+
+

+ +Any Forth definition that accepts an argument of type i shall also accept an +argument that is a subtype of i. + +

+ +


+ +

3.1.2 Character types

+
+ +Characters shall be at least one address unit wide, contain at least eight +bits, and have a size less than or equal to cell size. + +

+ +The characters provided by a system shall include the graphic characters +{32..126}, which represent graphic forms as shown in +table 3.2. + +

+ +See: +A.3.1.2 Character types + +

+ +


+ +

3.1.2.1 Graphic characters

+
+ +A graphic character is one that is normally displayed (e.g., A, #, &, 6). +These values and graphics, shown in +table 3.2, are taken directly from ANS +X3.4-1974 (ASCII) and ISO 646-1983, International Reference Version (IRV). +The graphic forms of characters outside the hex range {20..7E} are +implementation-defined. Programs that use the graphic hex 24 (the currency +sign) have an environmental dependency. + +

+ +The graphic representation of characters is not restricted to particular type +fonts or styles. The graphics here are examples. + +

+ +


+ +

3.1.2.2 Control characters

+
+ +All non-graphic characters included in the implementation-defined character +set are defined in this Standard as control characters. In particular, the +characters {0..31}, which could be included in the implementation-defined +character set, are control characters. + +

+ +Programs that require the ability to send or receive control characters have +an environmental dependency. + +

+ +


+

Table 3.1 - Data types

+

+ + +

+Symbol          Data type                         Size on stack
+------          ---------                         -------------
+flag            flag                              1 cell
+true            true flag                         1 cell
+false           false flag                        1 cell
+char            character                         1 cell
+n               signed number                     1 cell
++n              non-negative number               1 cell
+u               unsigned number                   1 cell
+n|u 1           number                            1 cell
+x               unspecified cell                  1 cell
+xt              execution token                   1 cell
+addr            address                           1 cell
+a-addr          aligned address                   1 cell
+c-addr          character-aligned address         1 cell
+d               double-cell signed number         2 cells
++d              double-cell non-negative number   2 cells
+ud              double-cell unsigned number       2 cells
+d|ud 2          double-cell number                2 cells
+xd              unspecified cell pair             2 cells
+colon-sys       definition compilation            implementation dependent
+do-sys          do-loop structures                implementation dependent
+case-sys        CASE structures                   implementation dependent
+of-sys          OF structures                     implementation dependent
+orig            control-flow origins              implementation dependent
+dest            control-flow destinations         implementation dependent
+loop-sys        loop-control parameters           implementation dependent
+nest-sys        definition calls                  implementation dependent
+i*x, j*x, k*x 3 any data type                     0 or more cells
+
+ +

+ +1 May be either a signed number or an unsigned number depending +on context. + +

+ +2 May be either a double-cell signed number or a double-cell +unsigned number depending on context. + +

+ +3 May be an undetermined number of stack entries of unspecified +type. For examples of use, see +6.1.1370 EXECUTE, +6.1.2050 QUIT. + +

+ +See: +11.3.1 Data types, +12.3.1 Data types, +14.3.1 Data types, +16.3.1 Data types. + +

+ +


+

Table 3.2 - Standard graphic characters

+ + +
+Hex     IRV     ASCII
+---     ---     -----
+20
+21      !       !
+22      "       "
+23      #       #
+24      °       $
+25      %       %
+26      &       &
+27      '       '
+28      (       (
+29      )       )
+2A      *       *
+2B      +       +
+2C      ,       ,
+2D      -       -
+2E      .       .
+2F      /       /
+30      0       0
+31      1       1
+32      2       2
+33      3       3
+34      4       4
+35      5       5
+36      6       6
+37      7       7
+38      8       8
+39      9       9
+3A      :       :
+3B      ;       ;
+3C      <       <
+3D      =       =
+3E      >       >
+3F      ?       ?
+40      @       @
+41      A       A
+42      B       B
+43      C       C
+44      D       D
+45      E       E
+46      F       F
+47      G       G
+48      H       H
+49      I       I
+4A      J       J
+4B      K       K
+4C      L       L
+4D      M       M
+4E      N       N
+4F      O       O
+50      P       P
+51      Q       Q
+52      R       R
+53      S       S
+54      T       T
+55      U       U
+56      V       V
+57      W       W
+58      X       X
+59      Y       Y
+5A      Z       Z
+5B      [       [
+5C      \       \
+5D      ]       ]
+5E      ^       ^
+5F      _       _
+60      `       `
+61      a       a
+62      b       b
+63      c       c
+64      d       d
+65      e       e
+66      f       f
+67      g       g
+68      h       h
+69      i       i
+6A      j       j
+6B      k       k
+6C      l       l
+6D      m       m
+6E      n       n
+6F      o       o
+70      p       p
+71      q       q
+72      r       r
+73      s       s
+74      t       t
+75      u       u
+76      v       v
+77      w       w
+78      x       x
+79      y       y
+7A      z       z
+7B      {       {
+7C      |       |
+7D      }       }
+7E      ~       ~
+
+ +

+ +


+ +

3.1.3 Single-cell types

+
+ +The implementation-defined fixed size of a cell is specified in address units +and the corresponding number of bits. See +E.2 Hardware peculiarities. + +

+ +Cells shall be at least one address unit wide and contain at least sixteen +bits. The size of a cell shall be an integral multiple of the size of a +character. Data-stack elements, return-stack elements, addresses, execution +tokens, flags, and integers are one cell wide. + +

+ +See: +A.3.1.3 Single-cell types + +

+ +


+ +

3.1.3.1 Flags

+
+ +Flags may have one of two logical states, true or false. Programs that use +flags as arithmetic operands have an environmental dependency. + +

+ +A true flag returned by a standard word shall be a single-cell value with all +bits set. A false flag returned by a standard word shall be a single-cell +value with all bits clear. + +

+ +See: +A.3.1.3.1 Flags + +

+ +


+ +

3.1.3.2 Integers

+
+ +The implementation-defined range of signed integers shall include +{-32767..+32767}. + +

+ +The implementation-defined range of non-negative integers shall include +{0..32767}. + +

+ +The implementation-defined range of unsigned integers shall include +{0..65535}. + +

+ +See: +A.3.1.3.2 Integers + +

+ +


+ +

3.1.3.3 Addresses

+
+ +An address identifies a location in data space with a size of one address +unit, which a program may fetch from or store into except for the restrictions +established in this Standard. The size of an address unit is specified in +bits. Each distinct address value identifies exactly one such storage +element. See +3.3.3 Data space. + +

+ +The set of character-aligned addresses, addresses at which a character can be +accessed, is an implementation-defined subset of all addresses. Adding the +size of a character to a character-aligned address shall produce another +character-aligned address. + +

+ +The set of aligned addresses is an implementation-defined subset of +character-aligned addresses. Adding the size of a cell to an aligned address +shall produce another aligned address. + +

+ +See: +A.3.1.3.3 Addresses + +

+ +


+ +

3.1.3.4 Counted strings

+
+ +A counted string in memory is identified by the address (c-addr) of its length +character. + +

+ +The length character of a counted string shall contain a binary +representation of the number of data characters, between zero and the +implementation-defined maximum length for a counted string. The maximum +length of a counted string shall be at least 255. + +

+ +See: +A.3.1.3.4 Counted strings + +

+ +


+ +

3.1.3.5 Execution tokens

+
+ +Different definitions may have the same execution token if the +definitions are equivalent. + +

+ +See: +A.3.1.3.5 Execution tokens + +

+ +


+ +

3.1.4 Cell-pair types

+
+ +A cell pair in memory consists of a sequence of two contiguous cells. The +cell at the lower address is the first cell, and its address is used to +identify the cell pair. Unless otherwise specified, a cell pair on a stack +consists of the first cell immediately above the second cell. + +

+ +See: +A.3.1.4 Cell-pair types + +

+ +


+ +

3.1.4.1 Double-cell integers

+
+ +On the stack, the cell containing the most significant part of a +double-cell integer shall be above the cell containing the least +significant part. + +

+ +The implementation-defined range of double-cell signed integers shall +include {-2147483647..+2147483647}. + +

+ +The implementation-defined range of double-cell non-negative integers +shall include {0..2147483647}. + +

+ +The implementation-defined range of double-cell unsigned integers shall +include {0..4294967295}. Placing the single-cell integer zero on the +stack above a single-cell unsigned integer produces a double-cell +unsigned integer with the same value. See +3.2.1.1 Internal number +representation. + +

+ +See: +A.3.1.4.1 Double-cell integers + +

+ +


+ +

3.1.4.2 Character strings

+
+ +A string is specified by a cell pair (c-addr u) representing its +starting address and length in characters. + +

+ +See: +A.3.1.3.4 Counted strings + +

+ +


+ +

3.1.5 System types

+
+ +The system data types specify permitted word combinations during +compilation and execution. + +

+ +


+ +

3.1.5.1 System-compilation types

+
+ +These data types denote zero or more items on the control-flow stack +(see +3.2.3.2). +The possible presence of such items on the data stack +means that any items already there shall be unavailable to a program +until the control-flow-stack items are consumed. + +

+ +The implementation-dependent data generated upon beginning to compile a +definition and consumed at its close is represented by the symbol +colon-sys throughout this Standard. + +

+ +The implementation-dependent data generated upon beginning to compile a +do-loop structure such as +DO ... +LOOP +and consumed at its close is +represented by the symbol do-sys throughout this Standard. + +

+ +The implementation-dependent data generated upon beginning to compile a +CASE ... +ENDCASE +structure and consumed at its close is represented by +the symbol case-sys throughout this Standard. + +

+ +The implementation-dependent data generated upon beginning to compile an +OF ... +ENDOF +structure and consumed at its close is represented by the +symbol of-sys throughout this Standard. + +

+ +The implementation-dependent data generated and consumed by executing +the other standard control-flow words is represented by the symbols orig +and dest throughout this Standard. + +

+ +


+ +

3.1.5.2 System-execution types

+
+ +These data types denote zero or more items on the return stack. Their +possible presence means that any items already on the return stack shall +be unavailable to a program until the system-execution items are +consumed. + +

+ +The implementation-dependent data generated upon beginning to execute a +definition and consumed upon exiting it is represented by the symbol +nest-sys throughout this Standard. + +

+ +The implementation-dependent loop-control parameters used to control the +execution of do-loops are represented by the symbol loop-sys throughout +this Standard. Loop-control parameters shall be available inside the +do-loop for words that use or change these parameters, words such as +I, +J, +LEAVE and +UNLOOP. + +

+ +


+ +

3.2 The implementation environment

+
+ +

+ + +


+ +

3.2.1 Numbers

+
+ +

+ +See: +A.3.2.1 Numbers + +

+ + +


+ +

3.2.1.1 Internal number representation

+
+ +This Standard allows one's complement, two's complement, or +sign-magnitude number representations and arithmetic. Arithmetic zero +is represented as the value of a single cell with all bits clear. +

+ +The representation of a number as a compiled literal or in memory is +implementation dependent. + +

+ +


+ +

3.2.1.2 Digit conversion

+
+ +Numbers shall be represented externally by using characters from the +standard character set. + +

+ +Conversion between the internal and external forms of a digit shall +behave as follows: + +

+ +The value in +BASE +is the radix for number conversion. A digit has a +value ranging from zero to one less than the contents of BASE. The +digit with the value zero corresponds to the character 0. This +representation of digits proceeds through the character set to the +decimal value nine corresponding to the character 9. For digits +beginning with the decimal value ten the graphic characters beginning +with the character A are used. This correspondence continues up +to and including the digit with the decimal value thirty-five which is +represented by the character Z. The conversion of digits outside +this range is implementation defined. + +

+ +See: +A.3.2.1.2 Digit conversion + +

+ +


+ +

3.2.1.3 Free-field number display

+
+ +Free-field number display uses the characters described in digit +conversion, without leading zeros, in a field the exact size of the +converted string plus a trailing space. If a number is zero, the least +significant digit is not considered a leading zero. If the number is +negative, a leading minus sign is displayed. + +

+ +Number display may use the pictured numeric output string buffer to hold +partially converted strings (see +3.3.3.6 Other transient regions). + +

+ +


+ +

3.2.2 Arithmetic

+
+ +

+ + +


+ +

3.2.2.1 Integer division

+
+ +Division produces a quotient q and a remainder r by dividing operand a +by operand b. Division operations return q, r, or both. The identity +b*q + r = a shall hold for all a and b. + +

+ +When unsigned integers are divided and the remainder is not zero, q is +the largest integer less than the true quotient. + +

+ +When signed integers are divided, the remainder is not zero, and a and b +have the same sign, q is the largest integer less than the true +quotient. If only one operand is negative, whether q is rounded toward +negative infinity (floored division) or rounded towards zero (symmetric +division) is implementation defined. + +

+ +Floored division is integer division in which the remainder carries the +sign of the divisor or is zero, and the quotient is rounded to its +arithmetic floor. Symmetric division is integer division in which the +remainder carries the sign of the dividend or is zero and the quotient +is the mathematical quotient rounded towards zero or +truncated. Examples of each are shown in tables +3.3 and +3.4. + +

+ +In cases where the operands differ in sign and the rounding direction +matters, a program shall either include code generating the desired form +of division, not relying on the implementation-defined default result, +or have an environmental dependency on the desired rounding direction. + +

+ +See: +A.3.2.2.1 Integer division + +

+ +


+

Table 3.3 - Floored Division Example

+

+ + +

+Dividend        Divisor Remainder       Quotient
+--------        ------- ---------       --------
+10                 7       3                1
+-10                7       4               -2
+10                -7      -4               -2
+-10               -7      -3                1
+
+

+ + +


+

Table 3.4 - Symmetric Division Example

+ + +
+Dividend        Divisor Remainder       Quotient
+--------        ------- ---------       --------
+10                 7       3                1
+-10                7      -3               -1
+10                -7       3               -1
+-10               -7      -3                1
+
+
+

+ + +

+ +


+ +

3.2.2.2 Other integer operations

+
+ +In all integer arithmetic operations, both overflow and underflow shall +be ignored. The value returned when either overflow or underflow occurs +is implementation defined. + +

+ +See: +A.3.2.2.2 Other integer operations + +

+ +


+ +

3.2.3 Stacks

+
+ +

+ +See: +A.3.2.3 Stacks + +

+ +


+ +

3.2.3.1 Data stack

+
+ +Objects on the data stack +shall be one cell wide. + +

+ +


+ +

3.2.3.2 Control-flow stack

+
+ +The control-flow stack is a last-in, first out list whose elements +define the permissible matchings of control-flow words and the +restrictions imposed on data-stack usage during the compilation of +control structures. + +

+ +The elements of the control-flow stack are system-compilation data +types. + +

+ +The control-flow stack may, but need not, physically exist in an +implementation. If it does exist, it may be, but need not be, +implemented using the data stack. The format of the control-flow stack +is implementation defined. Since the control-flow stack may be +implemented using the data stack, items placed on the data stack are +unavailable to a program after items are placed on the control-flow +stack and remain unavailable until the control-flow stack items are +removed. + +

+ +See: +A.3.2.3.2 Control-flow stack + +

+ +


+ +

3.2.3.3 Return stack

+
+ +Items on the return stack shall consist of one or more cells. A system +may use the return stack in an implementation-dependent manner during +the compilation of definitions, during the execution of do-loops, and +for storing run-time nesting information. + +

+ +A program may use the return stack for temporary storage during the +execution of a definition subject to the following restrictions: + +

    +
  • A program shall not access values on the return stack (using +R@, +R>, +2R@ or +2R>) +that it did not place there using +>R or +2>R; +
  • A program shall not access from within a do-loop values placed +on the return stack before the loop was entered; +
  • All values placed on the return stack within a do-loop shall be +removed before +I, +J, +LOOP, ++LOOP, +UNLOOP, or +LEAVE is executed; +
  • All values placed on the return stack within a definition shall +be removed before the definition is terminated or before +EXIT is +executed. +
+ +

+ +See: +A.3.2.3.3 Return stack + +

+ +


+ +

3.2.4 Operator terminal

+
+ + +See: +1.2.2 Exclusions + +

+ +


+ +

3.2.4.1 User input device

+
+ +The method of selecting the user input +device is implementation defined. + +

+ +The method of indicating the end of an input line of text is +implementation defined. + +

+ +


+ +

3.2.4.2 User output device

+
+ +The method of selecting the user output device is implementation +defined. + +

+ +


+ +

3.2.5 Mass storage

+
+ +A system need not provide any standard words for accessing mass storage. +If a system provides any standard word for accessing mass storage, it +shall also implement the Block word set. + +

+ +


+ +

3.2.6 Environmental queries

+
+ +The name spaces for +ENVIRONMENT? +and definitions are disjoint. Names of +definitions that are the same as ENVIRONMENT? strings shall not impair +the operation of ENVIRONMENT?. +Table 3.5 contains the valid input +strings and corresponding returned value for inquiring about the +programming environment with ENVIRONMENT?. + +

+ + +Table 3.5 - Environmental Query Strings + +

+ + + +

+String                Value  Constant?       Meaning
+                    data type
+/COUNTED-STRING         n       yes     maximum size of a counted string,
+                                        in characters
+/HOLD                   n       yes     size of the pictured numeric output
+                                        string buffer, in characters
+/PAD                    n       yes     size of the scratch area pointed to
+                                        by PAD, in characters
+ADDRESS-UNIT-BITS       n       yes     size of one address unit, in bits
+CORE                    flag    no      true if complete core word set
+                                        present (i.e., not a subset as
+                                        defined in 5.1.1)
+CORE-EXT                flag    no      true if core extensions word
+                                        set present
+FLOORED                 flag    yes     true if floored division is the default
+MAX-CHAR                u       yes     maximum value of any character in the
+                                        implementation-defined character set
+MAX-D                   d       yes     largest usable signed double number
+MAX-N                   n       yes     largest usable signed integer
+MAX-U                   u       yes     largest usable unsigned integer
+MAX-UD                  ud      yes     largest usable unsigned double number
+RETURN-STACK-CELLS      n       yes     maximum size of the return stack,
+                                        in cells
+STACK-CELLS             n       yes     maximum size of the data stack,
+                                        in cells
+
+

+ +If an environmental query (using ENVIRONMENT?) returns false (i.e., +unknown) in response to a string, subsequent queries using the same +string may return true. If a query returns true (i.e., known) in +response to a string, subsequent queries with the same string shall also +return true. If a query designated as constant in the above table +returns true and a value in response to a string, subsequent queries +with the same string shall return true and the same value. + +

+ +See: +A.3.2.6 Environmental queries, +7.3.1 Environmental queries, +8.3.1 Environmental queries, +9.3.4 Environmental queries, +10.3.2 Environmental queries, +11.3.3 Environmental queries, +12.3.4 Environmental queries, +13.3.2 Environmental queries, +14.3.2 Environmental queries, +15.3.1 Environmental queries, +16.3.2 Environmental queries, +17.3 Additional usage requirements. + +

+ +


+ +

3.3 The Forth dictionary

+
+ +Forth words are organized into a structure called the dictionary. While +the form of this structure is not specified by the Standard, it can be +described as consisting of three logical parts: a name space, a code +space, and a data space. The logical separation of these parts does not +require their physical separation. + +

+ +A program shall not fetch from or store into locations outside data +space. An ambiguous condition exists if a program addresses name space +or code space. + +

+ +See: +A.3.3 The Forth dictionary + +

+ +


+ +

3.3.1 Name space

+
+ +The relationship between name space and data space is implementation +dependent. + +

+ +


+ +

3.3.1.1 Word lists

+
+ +The structure of a word list is implementation dependent. When +duplicate names exist in a word list, the latest-defined duplicate shall +be the one found during a search for the name. + +

+ +


+ +

3.3.1.2 Definition names

+
+ +Definition names shall contain {1..31} characters. A system may allow +or prohibit the creation of definition names containing non-standard +characters. + +

+ +Programs that use lower case for standard definition names or depend on +the case-sensitivity properties of a system have an environmental +dependency. + +

+ +A program shall not create definition names containing non-graphic +characters. + +

+ +See: +A.3.3.1.2 Definition names + +

+ +


+ +

3.3.2 Code space

+
+ +The relationship between code space and data space is implementation +dependent. + +

+ +


+ +

3.3.3 Data space

+
+ +Data space is the only logical area of the dictionary for which standard +words are provided to allocate and access regions of memory. These +regions are: contiguous regions, variables, text-literal regions, input +buffers, and other transient regions, each of which is described in the +following sections. A program may read from or write into these regions +unless otherwise specified. + +

+ +See: +A.3.3.3 Data space + +

+ +


+ +

3.3.3.1 Address alignment

+
+ +Most addresses used in ANS Forth are aligned addresses (indicated by +a-addr) or character-aligned (indicated by c-addr). +ALIGNED, +CHAR+, and +arithmetic operations can alter the alignment state of an address on the +stack. CHAR+ applied to an aligned address returns a character-aligned +address that can only be used to access characters. Applying CHAR+ to a +character-aligned address produces the succeeding character-aligned +address. Adding or subtracting an arbitrary number to an address can +produce an unaligned address that shall not be used to fetch or store +anything. The only way to find the next aligned address is with +ALIGNED. An ambiguous condition exists when +@, +!, , +(comma), ++!, +2@, or +2! +is used with an address that is not aligned, or when +C@, +C!, or +C, is +used with an address that is not character-aligned. + +

+ +The definitions of +6.1.1000 CREATE and +6.1.2410 VARIABLE require that +the definitions created by them return aligned addresses. + +

+ +After definitions are compiled or the word +ALIGN +is executed the +data-space pointer is guaranteed to be aligned. + +

+ +See: +A.3.3.3.1 Address alignment + +

+ +


+ +

3.3.3.2 Contiguous regions

+
+ +A system guarantees that a region of data space allocated using +ALLOT, , +(comma), C, +(c-comma), and +ALIGN +shall be contiguous with the last +region allocated with one of the above words, unless the restrictions in +the following paragraphs apply. The data-space pointer +HERE +always +identifies the beginning of the next data-space region to be allocated. +As successive allocations are made, the data-space pointer increases. A +program may perform address arithmetic within contiguously allocated +regions. The last region of data space allocated using the above +operators may be released by allocating a corresponding negatively-sized +region using ALLOT, subject to the restrictions of the following +paragraphs. + +

+ +CREATE +establishes the beginning of a contiguous region of data space, +whose starting address is returned by the CREATEd definition. This +region is terminated by compiling the next definition. + +

+ +Since an implementation is free to allocate data space for use by code, +the above operators need not produce contiguous regions of data space if +definitions are added to or removed from the dictionary between +allocations. An ambiguous condition exists if deallocated memory +contains definitions. + +

+ +See: +A.3.3.3.2 Contiguous regions + +

+ +


+ +

3.3.3.3 Variables

+
+ +The region allocated for a variable may be non-contiguous with regions +subsequently allocated with , +(comma) or +ALLOT. +For example, in: + + +
+        VARIABLE X  1 CELLS ALLOT
+
+

+ +the region X and the region +ALLOTted could be non-contiguous. + +

+ +Some system-provided variables, such as +STATE, +are restricted to read-only +access. + +

+ +


+ +

3.3.3.4 Text-literal regions

+
+ +The text-literal regions, specified by strings compiled with +S" and +C", +may be read-only. + +

+ +A program shall not store into the text-literal regions created by S" +and C" nor into any read-only system variable or read-only transient +regions. An ambiguous condition exists when a program attempts to store +into read-only regions. + +

+ +


+ +

3.3.3.5 Input buffers

+
+ +The address, length, and content of the input buffer may be transient. +A program shall not write into the input buffer. In the absence of any +optional word sets providing alternative input sources, the input buffer +is either the terminal-input buffer, used by +QUIT to hold one line from +the user input device, or a buffer specified by +EVALUATE. In all cases, +SOURCE returns the beginning +address and length in characters of the +current input buffer. + +

+ +The minimum size of the terminal-input +buffer shall be 80 characters. + +

+ +The address and length returned by SOURCE, the string returned by +PARSE, +and directly computed input-buffer addresses are valid only until the +text interpreter does I/O to refill the input buffer or the input source +is changed. + +

+ +A program may modify the size of the parse area by changing the contents +of +>IN +within the limits imposed by this Standard. For example, if the +contents of >IN are saved before a parsing operation and restored +afterwards, the text that was parsed will be available again for +subsequent parsing operations. The extent of permissible repositioning +using this method depends on the input +source (see 7.3.3 Block buffer +regions and 11.3.4 Input source). + +

+ +A program may directly examine the input buffer using its address and +length as returned by SOURCE; the beginning of the parse area within the +input buffer is indexed by the number in >IN. The values are valid for +a limited time. An ambiguous condition exists if a program modifies the +contents of the input buffer. + +

+ +See: +RFI 0006 Writing to Input Buffers + +

+ +


+ +

3.3.3.6 Other transient regions

+
+ +The data space regions identified by +PAD, +WORD, and +#> +(the pictured +numeric output string buffer) may be transient. Their addresses and +contents may become invalid after: + +
    +
  • a definition is created via a defining word; +
  • definitions are compiled with +: or +:NONAME; +
  • data space is allocated using +ALLOT, , +(comma), +C, +(c-comma), or +ALIGN. +
+

+ +The previous contents of the regions identified by WORD and #> may be +invalid after each use of these words. Further, the regions returned by +WORD and #> may overlap in memory. Consequently, use of one of these +words can corrupt a region returned earlier by a different word. The +other words that construct pictured numeric output strings +(<#, +#, +#S, +and +HOLD) +may also modify the contents of these regions. Words that +display numbers may be implemented using pictured numeric output words. +Consequently, . +(dot), +.R, +.S, +?, +D., +D.R, +U., and +U.R +could also +corrupt the regions. + +

+ +The size of the scratch area whose address is returned by PAD shall be +at least 84 characters. The contents of the region addressed by PAD are +intended to be under the complete control of the user: no words defined +in this Standard place anything in the region, although changing +data-space allocations as described in +3.3.3.2 Contiguous regions may +change the address returned by PAD. Non-standard words provided by an +implementation may use PAD, but such use shall be documented. + +

+ +The size of the region identified by WORD shall be at least 33 +characters. + +

+ +The size of the pictured numeric output string buffer shall be at least +(2*n) + 2 characters, where n is the number of bits in a cell. Programs +that consider it a fixed area with unchanging access parameters have an +environmental dependency. + +

+ +See: +A.3.3.3.6 Other transient regions, +11.3.5 Other transient regions. + +

+ +


+ +

3.4 The Forth text interpreter

+
+ +Upon start-up, a system shall be able to interpret, as described by +6.1.2050 QUIT, Forth source code +received interactively from a user +input device. + +

+ +Such interactive systems usually furnish a prompt indicating that +they have accepted a user request and acted on it. The +implementation-defined Forth prompt should contain the word OK in +some combination of upper or lower case. + +

+ +Text interpretation (see +6.1.1360 EVALUATE and +6.1.2050 QUIT) shall +repeat the following steps until either the parse area is empty or an +ambiguous condition exists: + +

+a) Skip leading spaces and parse a name (see +3.4.1); +

+b) Search the dictionary name space (see +3.4.2). If a definition name +matching the string is found: +

    +
  1. if interpreting, perform the interpretation semantics of the +definition (see +3.4.3.2), and continue at a); +
  2. if compiling, perform the compilation semantics of the definition (see +3.4.3.3), and continue at a). +
+

+c) If a definition name matching the string is not found, attempt to +convert the string to a number (see +3.4.1.3). If successful: +

    +
  1. if interpreting, place the number on the data stack, and continue at a); +
  2. if compiling, compile code that when executed will place the number on +the stack (see +6.1.1780 LITERAL), and continue at a); +
+

+d) If unsuccessful, an ambiguous condition exists (see +3.4.4). + +

+ + +


+ +

3.4.1 Parsing

+
+ +Unless otherwise noted, the number of characters parsed may be from zero +to the implementation-defined maximum length of a counted string. + +

+ +If the parse area is empty, i.e., when the number in +>IN +is equal to the +length of the input buffer, or contains no characters other than +delimiters, the selected string is empty. Otherwise, the selected +string begins with the next character in the parse area, which is the +character indexed by the contents of >IN. An ambiguous condition exists +if the number in >IN is greater than the size of the input buffer. + +

+ +If delimiter characters are present in the parse area after the +beginning of the selected string, the string continues up to and +including the character just before the first such delimiter, and the +number in >IN is changed to index immediately past that delimiter, thus +removing the parsed characters and the delimiter from the parse area. +Otherwise, the string continues up to and including the last character +in the parse area, and the number in >IN is changed to the length of the +input buffer, thus emptying the parse area. + +

+ +Parsing may change the contents of >IN, but shall not affect the +contents of the input buffer. Specifically, if the value in >IN is +saved before starting the parse, resetting >IN to that value immediately +after the parse shall restore the parse area without loss of data. + +

+ +


+ +

3.4.1.1 Delimiters

+
+ +If the delimiter is the space character, hex 20 +(BL), +control characters +may be treated as delimiters. The set of conditions, if any, under +which a space delimiter matches control characters is +implementation defined. + +

+ +To skip leading delimiters is to pass by zero or more contiguous +delimiters in the parse area before parsing. + +

+ +


+ +

3.4.1.2 Syntax

+
+ +Forth has a simple, operator-ordered syntax. The phrase A B C returns +values as if A were executed first, then B and finally C. Words that +cause deviations from this linear flow of control are called +control-flow words. Combinations of control-flow words whose stack +effects are compatible form control-flow structures. Examples of +typical use are given for each control-flow word in +Annex A. + +

+ +Forth syntax is extensible; for example, new control-flow words can be +defined in terms of existing ones. + +

+ +This Standard does not require a +syntax or program-construct checker. + +

+ +


+ +

3.4.1.3 Text interpreter input number conversion

+
+ +When converting input numbers, the text interpreter shall recognize both +positive and negative numbers, with a negative number represented by a +single minus sign, the character -, preceding the digits. The +value in +BASE +is the radix for number conversion. + +

+ +


+ +

3.4.2 Finding definition names

+
+ +A string matches a definition name if each character in the string +matches the corresponding character in the string used as the definition +name when the definition was created. The case sensitivity (whether or +not the upper-case letters match the lower-case letters) is +implementation defined. A system may be either case sensitive, treating +upper- and lower-case letters as different and not matching, or case +insensitive, ignoring differences in case while searching. + +

+ +The matching of upper- and lower-case letters with alphabetic characters +in character set extensions such as accented international characters is +implementation defined. + +

+ +A system shall be capable of finding the definition names defined by +this Standard when they are spelled with upper-case letters. + +

+ +


+ +

3.4.3 Semantics

+
+ +The semantics of a Forth definition are implemented by machine code or a +sequence of execution tokens or other representations. They are largely +specified by the stack notation in the glossary entries, which shows +what values shall be consumed and produced. The prose in each glossary +entry further specifies the definition's behavior. + +

+ +Each Forth definition may have several behaviors, described in the +following sections. The terms initiation semantics and +run-time semantics refer to definition fragments, and have +meaning only within the individual glossary entries where they appear. + +

+ +See: +A.3.4.3 Semantics, +RFI 0005. + +

+ +


+ +

3.4.3.1 Execution semantics

+
+ +The execution semantics of each Forth definition are specified in an +Execution: section of its glossary entry. When a definition has +only one specified behavior, the label is omitted. + +

+ +Execution may occur implicitly, when the definition into which it has +been compiled is executed, or explicitly, when its execution token is +passed to +EXECUTE. +The execution semantics of a syntactically correct +definition under conditions other than those specified in this Standard +are implementation dependent. + +

+ +Glossary entries for defining words include the execution semantics for +the new definition in a name Execution: section. + +

+ +


+ +

3.4.3.2 Interpretation semantics

+
+ +Unless otherwise specified in an Interpretation: section of the +glossary entry, the interpretation semantics of a Forth definition are +its execution semantics. + +

+ +A system shall be capable of executing, in interpretation state, all of +the definitions from the Core word set and any definitions included from +the optional word sets or word set extensions whose interpretation +semantics are defined by this Standard. + +

+ +A system shall be capable of executing, in interpretation state, any new +definitions created in accordance with +3. Usage requirements. + +

+ +See: +A.3.4.3.2 Interpretation semantics + +

+ +


+ +

3.4.3.3 Compilation semantics

+
+ +Unless otherwise specified in a Compilation: section of the +glossary entry, the compilation semantics of a Forth definition shall be +to append its execution semantics to the execution semantics of the +current definition. + +

+ +See: +RFI 0007 Distinction between immediacy and special compilation semantics. + +

+ +


+ +

3.4.4 Possible actions on an ambiguous condition

+
+ +When an ambiguous condition exists, a system may take one or more of the +following actions: + +
    +
  • ignore and continue; +
  • display a message; +
  • execute a particular word; +
  • set interpretation state and begin text interpretation; +
  • take other implementation-defined actions; +
  • take implementation-dependent actions. +
+

+ +The response to a particular ambiguous condition need not be the same +under all circumstances. + +

+ +


+ +

3.4.5 Compilation

+
+ +A program shall not attempt to +nest compilation of definitions. + +

+ +During the compilation of the current definition, a program shall not +execute any defining word, +:NONAME, +or any definition that allocates +dictionary data space. The compilation of the current definition may be +suspended using [ +(left-bracket) +and resumed using ] +(right-bracket). +While the compilation of the current definition is suspended, a program +shall not execute any defining word, :NONAME, or any definition that +allocates dictionary data space. + +

+ +See: +A.3.4.5 Compilation + +

+ +


+ Table of Contents +
+ Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpans4.htm b/docs/reference/standards/ans94/dpans4.htm new file mode 100644 index 00000000..c6959f7d --- /dev/null +++ b/docs/reference/standards/ans94/dpans4.htm @@ -0,0 +1,370 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

4. Documentation requirements

+ +When it is impossible or infeasible for a system or program to define a +particular behavior itself, it is permissible to state that the behavior +is unspecifiable and to explain the circumstances and reasons why this is so. + +

+ +


+ +

4.1 System documentation

+
+ + +
+ +

4.1.1 Implementation-defined options

+
+ +The implementation-defined items in the following list represent +characteristics and choices left to the discretion of the implementor, +provided that the requirements of this Standard are met. A system shall +document the values for, or behaviors of, each item. + +
    +
  • aligned address requirements +(3.1.3.3 Addresses); +
  • behavior of +6.1.1320 EMIT for non-graphic characters; +
  • character editing of +6.1.0695 ACCEPT and +6.2.1390 EXPECT; +
  • character set +(3.1.2 Character types, +6.1.1320 EMIT, +6.1.1750 KEY); +
  • character-aligned address requirements +(3.1.3.3 Addresses); +
  • character-set-extensions matching characteristics +(3.4.2 Finding +definition names); +
  • conditions under which control characters match a space delimiter +(3.4.1.1 Delimiters); +
  • format of the control-flow stack +(3.2.3.2 Control-flow stack); +
  • conversion of digits larger than thirty-five +(3.2.1.2 Digit +conversion); +
  • display after input terminates in +6.1.0695 ACCEPT and +6.2.1390 EXPECT; +
  • exception abort sequence (as in +6.1.0680 ABORT"); +
  • input line terminator +(3.2.4.1 User input device); +
  • maximum size of a counted string, in characters +(3.1.3.4 Counted +strings, +6.1.2450 WORD); +
  • maximum size of a parsed string +(3.4.1 Parsing); +
  • maximum size of a definition name, in characters +(3.3.1.2 Definition +names); +
  • maximum string length for +6.1.1345 ENVIRONMENT?, in characters; +
  • method of selecting +3.2.4.1 User input device; +
  • method of selecting +3.2.4.2 User output device; +
  • methods of dictionary compilation +(3.3 The Forth dictionary); +
  • number of bits in one address unit +(3.1.3.3 Addresses); +
  • number representation and arithmetic +(3.2.1.1 Internal number +representation); +
  • ranges for n, +n, u, d, +d, and ud +(3.1.3 Single-cell types, +3.1.4 Cell-pair types); +
  • read-only data-space regions +(3.3.3 Data space); +
  • size of buffer at +6.1.2450 WORD +(3.3.3.6 Other transient regions); +
  • size of one cell in address units +(3.1.3 Single-cell types); +
  • size of one character in address units +(3.1.2 Character types); +
  • size of the keyboard terminal input buffer +(3.3.3.5 Input buffers); +
  • size of the pictured numeric output string buffer +(3.3.3.6 Other +transient regions); +
  • size of the scratch area whose address is returned by +6.2.2000 PAD +(3.3.3.6 Other transient regions); +
  • system case-sensitivity characteristics +(3.4.2 Finding definition +names); +
  • system prompt +(3.4 The Forth text interpreter, +6.1.2050 QUIT); +
  • type of division rounding +(3.2.2.1 Integer division, +6.1.0100 */, +6.1.0110 */MOD, +6.1.0230 /, +6.1.0240 /MOD, +6.1.1890 MOD); +
  • values of +6.1.2250 STATE when true; +
  • values returned after arithmetic overflow +(3.2.2.2 Other integer +operations); +
  • whether the current definition can be found after +6.1.1250 DOES> +(6.1.0450 :). +
+ +

+ +


+ +

4.1.2 Ambiguous conditions

+
+ +A system shall document the system action taken upon each of the general or +specific ambiguous conditions identified in this Standard. See +3.4.4 Possible +actions on an ambiguous condition. + +

+ +The following general ambiguous conditions could occur because of a +combination of factors: + +

    +
  • a name is neither a valid definition name nor a valid number during +text interpretation +(3.4 The Forth text interpreter); +
  • a definition name exceeded the maximum length allowed +(3.3.1.2 +Definition names); +
  • addressing a region not listed in +3.3.3 Data Space; +
  • argument type incompatible with specified input parameter, e.g., +passing a flag to a word expecting an n +(3.1 Data types); +
  • attempting to obtain the execution token, (e.g., with +6.1.0070 ', +6.1.1550 FIND, +etc.) of a definition with undefined interpretation semantics; +
  • dividing by zero +(6.1.0100 */, +6.1.0110 */MOD, +6.1.0230 /, +6.1.0240 /MOD, +6.1.1561 FM/MOD, +6.1.1890 MOD, +6.1.2214 SM/REM, +6.1.2370 UM/MOD, +8.6.1.1820 M*/); +
  • insufficient data-stack space or return-stack space (stack overflow); +
  • insufficient space for loop-control parameters; +
  • insufficient space in the dictionary; +
  • interpretating a word with undefined interpretation semantics; +
  • modifying the contents of the input buffer or a string literal +(3.3.3.4 Text-literal regions, +3.3.3.5 Input buffers); +
  • overflow of a pictured numeric output string; +
  • parsed string overflow; +
  • producing a result out of range, e.g., multiplication (using *) +results in a value too big to be represented by a single-cell integer +(6.1.0090 *, +6.1.0100 */, +6.1.0110 */MOD, +6.1.0570 >NUMBER, +6.1.1561 FM/MOD, +6.1.2214 SM/REM, +6.1.2370 UM/MOD, +6.2.0970 CONVERT, +8.6.1.1820 M*/); +
  • reading from an empty data stack or return stack (stack underflow); +
  • unexpected end of input buffer, resulting in an attempt to use a +zero-length string as a name; +
+

+ +The following specific ambiguous conditions are noted in the glossary entries +of the relevant words: + +

+ +

+ +


+ +

4.1.3 Other system documentation

+
+ +A system shall provide the following information: +

+ +

    +
  • list of non-standard words using +6.2.2000 PAD +(3.3.3.6 Other transient +regions); +
  • operator's terminal facilities available; +
  • program data space available, in address units; +
  • return stack space available, in cells; +
  • stack space available, in cells; +
  • system dictionary space required, in address units. +
+ +

+ +


+ +

4.2 Program documentation

+
+ + +
+ +

4.2.1 Environmental dependencies

+
+ +A program shall document the following environmental dependencies, where they +apply, and should document other known environmental dependencies: + +
    +
  • considering the pictured numeric output string buffer a fixed area +with unchanging access parameters +(3.3.3.6 Other transient regions); +
  • depending on the presence or absence of non-graphic characters in a +received string +(6.1.0695 ACCEPT, +6.2.1390 EXPECT); +
  • relying on a particular rounding direction +(3.2.2.1 Integer division); +
  • requiring a particular number representation and arithmetic +(3.2.1.1 +Internal number representation); +
  • requiring non-standard words or techniques +(3. Usage requirements); +
  • requiring the ability to send or receive control characters +(3.1.2.2 Control characters, +6.1.1750 KEY); +
  • using control characters to perform specific functions +(6.1.1320 EMIT, +6.1.2310 TYPE); +
  • using flags as arithmetic operands +(3.1.3.1 Flags); +
  • using lower case for standard definition names or depending on the +case sensitivity of a system +(3.3.1.2 Definition names); +
  • using the graphic character with a value of hex 24 +(3.1.2.1 Graphic +characters). +
+ +

+ +


+ +

4.2.2 Other program documentation

+
+ +A program shall also document: +

+ +

    +
  • minimum operator's terminal facilities required; +
  • whether a Standard System exists after the program is loaded. +
+ + +
+ Table of Contents +
+ Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpans5.htm b/docs/reference/standards/ans94/dpans5.htm new file mode 100644 index 00000000..e1cead5e --- /dev/null +++ b/docs/reference/standards/ans94/dpans5.htm @@ -0,0 +1,145 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

5. Compliance and labeling

+ + +
+ +

5.1 ANS Forth systems

+
+ +

+ +See: +A.5.1 ANS Forth systems + +

+ +


+ +

5.1.1 System compliance

+
+ +A system that complies with all the system requirements given in +sections +3. Usage requirements and +4.1 System documentation and their +sub-sections is a Standard System. An otherwise Standard System that +provides only a portion of the Core words is a Standard System Subset. +An otherwise Standard System (Subset) that fails to comply with one or +more of the minimum values or ranges specified in +3. Usage requirements +and its sub-sections has environmental restrictions. + +

+ +


+ +

5.1.2 System labeling

+
+ +A Standard System (Subset) shall be labeled an ANS Forth System +(Subset). That label, by itself, shall not be applied to Standard +Systems or Standard System Subsets that have environmental restrictions. + +

+ +The phrase with Environmental Restrictions shall be appended to +the label of a Standard System (Subset) that has environmental +restrictions. + +

+ +The phrase Providing name(s) from the Core Extensions word set +shall be appended to the label of any Standard System that provides +portions of the Core Extensions word set. + +

+ +The phrase Providing the Core Extensions word set shall be +appended to the label of any Standard System that provides all of the +Core Extensions word set. + +

+ +


+ +

5.2 ANS Forth programs

+
+ + +
+ +

5.2.1 Program compliance

+
+ +A program that complies with all the program requirements given in +sections +3. Usage requirements and +4.2 Program documentation and their +sub-sections is a Standard Program. + +

+ +


+ +

5.2.2 Program labeling

+
+ +A Standard Program shall be labeled an ANS Forth Program. That +label, by itself, shall not be applied to Standard Programs that require +the system to provide standard words outside the Core word set or that +have environmental dependencies. + +

+ +The phrase with Environmental Dependencies shall be appended to +the label of Standard Programs that have environmental dependencies. + +

+ +The phrase Requiring name(s) from the Core Extensions word set +shall be appended to the label of Standard Programs that require the +system to provide portions of the Core Extensions word set. + +

+ +The phrase Requiring the Core Extensions word set shall be +appended to the label of Standard Programs that require the system to +provide all of the Core Extensions word set. + +

+ +See: +A.5.2.2 Program labeling + +

+ +


+ Table of Contents +
+ Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpans6.htm b/docs/reference/standards/ans94/dpans6.htm new file mode 100644 index 00000000..6a340dc6 --- /dev/null +++ b/docs/reference/standards/ans94/dpans6.htm @@ -0,0 +1,5776 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

6. Glossary

+ +

+See: +A.6 Glossary +

+ + +


+ +

6.1 Core words

+ + + + +
+ + +6.1.0010 ! + + +
+store CORE +
+
+	( x a-addr -- )
+
+

+ +Store x at +a-addr. + +

+ + +See: +3.3.3.1 Address alignment + + +

+ +


+ + +6.1.0030 # + + +
+number-sign CORE +
+
+	( ud1 -- ud2 )
+
+

+ +Divide ud1 by the number in +BASE +giving the quotient ud2 and the +remainder n. (n is the least-significant digit of ud1.) Convert n to +external form and add the resulting character to the beginning of the +pictured numeric output string. An ambiguous condition exists if # +executes outside of a +<# +#> +delimited number conversion. + +

+ + +See: +6.1.0050 #S + + +

+ +


+ + +6.1.0040 #> + + +
+number-sign-greater CORE +
+
+	( xd -- c-addr u )
+
+ +

+ +Drop xd. Make the pictured numeric output string available as a +character string. c-addr and u specify the resulting character string. +A program may replace characters within the string. + +

+ + +See: +6.1.0030 # , +6.1.0050 #S , +6.1.0490 <# + + +

+ +


+ + +6.1.0050 #S + + +
+number-sign-s CORE +
+
+	( ud1 -- ud2 )
+
+ +

+ +Convert one digit of ud1 according to the rule for +#. Continue +conversion until the quotient is zero. ud2 is zero. An ambiguous +condition exists if #S executes outside of a +<# +#> +delimited number +conversion. + +

+ + +


+ + +6.1.0070 ' + + +
+tick CORE +
+
+	( "<spaces>name" -- xt )
+
+ +

+ +Skip leading space delimiters. Parse name delimited by a space. Find +name and return xt, the execution token for name. An ambiguous +condition exists if name is not found. + +

+ +When interpreting, ' xyz EXECUTE is equivalent to xyz. + +

+ + +See: +3.4 The Forth text interpreter, +3.4.1 Parsing, +A.6.1.2033 POSTPONE , +6.1.2510 ['] , +A.6.1.0070 ' , +D.6.7 Immediacy. + + +

+ +


+ + +6.1.0080 ( + + +
+paren CORE +
+ +

+

+	Compilation: Perform the execution semantics given below.
+
+

+

+	Execution: ( "ccc<paren>" -- )
+
+

+ +Parse ccc delimited by ) +(right parenthesis). ( is an immediate word. + +

+ +The number of characters in ccc may be zero to the number of characters +in the parse area. + +

+ + +See: +3.4.1 Parsing, +11.6.1.0080 ( , +A.6.1.0080 ( + + +

+ +


+ + +6.1.0090 * + + +
+star CORE +
+
+	( n1|u1 n2|u2 -- n3|u3 )
+
+ +

+ +Multiply n1|u1 by n2|u2 +giving the product n3|u3. + +

+ +


+ + +6.1.0100 */ + + +
+star-slash CORE +
+
+	( n1 n2 n3 -- n4 )
+
+ +

+ +Multiply n1 by n2 producing the intermediate double-cell result d. +Divide d by n3 giving the single-cell quotient n4. An ambiguous +condition exists if n3 is zero or if the quotient n4 lies outside the +range of a signed number. If d and n3 differ in sign, the +implementation-defined result returned will be the same as that returned +by either the phrase + +>R M* R> FM/MOD SWAP DROP + +or the phrase + +>R M* R> SM/REM SWAP DROP +. + +

+ + +See: +3.2.2.1 Integer division + + +

+ +


+ + +6.1.0110 */MOD + + +
+star-slash-mod CORE +
+
+	( n1 n2 n3 -- n4 n5 )
+
+ +

+ +Multiply n1 by n2 producing the intermediate double-cell result d. Divide d +by n3 producing the single-cell remainder n4 and the single-cell quotient n5. +An ambiguous condition exists if n3 is zero, or if the quotient n5 lies +outside the range of a single-cell signed integer. If d and n3 differ in +sign, the implementation-defined result returned will be the same as that +returned by either the phrase + +>R M* R> FM/MOD + +or the phrase + +>R M* R> SM/REM +. + +

+ + +See: +3.2.2.1 Integer division + + +

+ +


+ + +6.1.0120 + + + +
+plus CORE +
+
+	( n1|u1 n2|u2 -- n3|u3 )
+
+ +

+ +Add n2|u2 +to n1|u1, giving the sum n3|u3. + +

+ + +See: +3.3.3.1 Address alignment + + +

+ +


+ + +6.1.0130 +! + + +
+plus-store CORE +
+
+	( n|u a-addr -- )
+
+ +

+ +Add n|u +to the single-cell number at a-addr. + +

+ + +See: +3.3.3.1 Address alignment + + +

+ +


+ + +6.1.0140 +LOOP + + +
+plus-loop CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( C: do-sys -- )
+
+

+ +Append the run-time semantics given below to the current definition. +Resolve the destination of all unresolved occurrences of +LEAVE between +the location given by do-sys and the next location for a transfer of +control, to execute the words following +LOOP. +

+

+	Run-time: ( n -- ) ( R: loop-sys1 -- | loop-sys2 )
+
+

+ +An ambiguous condition exists if the loop control parameters are +unavailable. Add n to the loop index. If the loop index did not cross +the boundary between the loop limit minus one and the loop limit, +continue execution at the beginning of the loop. Otherwise, discard the +current loop control parameters and continue execution immediately +following the loop. + +

+ + +See: +6.1.1240 DO , +6.1.1680 I , +6.1.1760 LEAVE , +A.6.1.0140 +LOOP + + +

+ +


+ + +6.1.0150 , + + +
+comma CORE +
+
+	( x -- )
+
+ +

+ +Reserve one cell of data space and store x in the cell. If the data-space +pointer is aligned when , begins execution, it will remain aligned when , +finishes execution. An ambiguous condition exists if the data-space pointer +is not aligned prior to execution of ,. + +

+ + +See: +3.3.3 Data space, +3.3.3.1 Address alignment, +A.6.1.0150 , + + + +

+ +


+ + +6.1.0160 - + + +
+minus CORE +
+
+	( n1|u1 n2|u2 -- n3|u3 )
+
+ +

+ +Subtract n2|u2 +from n1|u1, giving the difference n3|u3. + +

+ + +See: +3.3.3.1 Address alignment. + + + +

+ +


+ + +6.1.0180 . + + +
+dot CORE +
+
+	( n -- )
+
+ +

+ +Display n in +free field format. + +

+ + +See: +3.2.1.2 Digit conversion, +3.2.1.3 Free-field number display. + + +

+ +


+ + +6.1.0190 ." + + +
+dot-quote CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( "ccc<quote>" -- )
+
+

+ +Parse ccc delimited by " (double-quote). Append the run-time semantics +given below to the current definition. + + +

+        Run-time: ( -- )
+
+ +

+ +Display +ccc. + +

+ + +See: +3.4.1 Parsing, +6.2.0200 .( , +A.6.1.0190 ." + + +

+ +


+ + +6.1.0230 / + + +
+slash CORE +
+
+	( n1 n2 -- n3 )
+
+ +

+ +Divide n1 by n2, giving the single-cell quotient n3. An ambiguous +condition exists if n2 is zero. If n1 and n2 differ in sign, the +implementation-defined result returned will be the same as that returned +by either the phrase + +>R S>D R> FM/MOD SWAP DROP + +or the phrase + +>R S>D R> SM/REM SWAP DROP +. + +

+ + +See: +3.2.2.1 Integer division + + +

+ +


+ + +6.1.0240 /MOD + + +
+slash-mod CORE +
+
+	( n1 n2 -- n3 n4 )
+
+ +

+ +Divide n1 by n2, giving the single-cell remainder n3 and the single-cell +quotient n4. An ambiguous condition exists if n2 is zero. If n1 and n2 +differ in sign, the implementation-defined result returned will be the +same as that returned by either the phrase + +>R S>D R> FM/MOD + +or the phrase + +>R S>D R> SM/REM +. + +

+ + +See: +3.2.2.1 Integer division + + +

+ +


+ + +6.1.0250 0< + + +
+zero-less CORE +
+
+	( n -- flag )
+
+ +

+ +flag is true +if and only if n is less than zero. + +

+ +


+ + +6.1.0270 0= + + +
+zero-equals CORE +
+
+	( x -- flag )
+
+ +

+ +flag is +true if and only if x is equal to zero. + +

+ +


+ + +6.1.0290 1+ + + +
+one-plus CORE +
+
+	( n1|u1 -- n2|u2 )
+
+ +

+ +Add one (1) +to n1|u1 giving the sum n2|u2. + +

+ +


+ + +6.1.0300 1- + + +
+one-minus CORE +
+
+	( n1|u1 -- n2|u2 )
+
+ +

+ +Subtract one (1) +from n1|u1 giving the difference n2|u2. + +

+ +


+ + +6.1.0310 2! + + +
+two-store CORE +
+
+	( x1 x2 a-addr -- )
+
+ +

+ +Store the cell pair x1 x2 at a-addr, with x2 at a-addr and x1 at the next +consecutive cell. It is equivalent to the sequence + +SWAP OVER ! CELL+ ! +. + +

+ + +See: +3.3.3.1 Address alignment + + +

+ +


+ + +6.1.0320 2* + + +
+two-star CORE +
+
+	( x1 -- x2 )
+
+ +

+ +x2 is the result of shifting x1 one bit toward the most-significant bit, +filling the vacated least-significant bit with zero. + +

+ +See: +A.6.1.0320 2* + +

+ +


+ + +6.1.0330 2/ + + +
+two-slash CORE +
+
+	( x1 -- x2 )
+
+ +

+ +x2 is the result of shifting x1 one bit toward the least-significant +bit, leaving the most-significant bit unchanged. + +

+ +See: +A.6.1.0330 2/ + +

+ +


+ + +6.1.0350 2@ + + +
+two-fetch CORE +
+
+	( a-addr -- x1 x2 )
+
+ +

+ +Fetch the cell pair x1 x2 stored at a-addr. x2 is stored at a-addr and +x1 at the next consecutive cell. It is equivalent to the sequence + +DUP CELL+ @ SWAP @ +. + +

+ + +See: +3.3.3.1 Address alignment, +6.1.0310 2! , +A.6.1.0350 2@ + + +

+ +


+ + +6.1.0370 2DROP + + +
+two-drop CORE +
+
+	( x1 x2 -- )
+
+ +

+ +Drop cell +pair x1 x2 from the stack. + +

+ +


+ + +6.1.0380 2DUP + + +
+two-dupe CORE +
+
+	( x1 x2 -- x1 x2 x1 x2 )
+
+ +

+ +Duplicate cell +pair x1 x2. + +

+ +


+ + +6.1.0400 2OVER + + +
+two-over CORE +
+
+	( x1 x2 x3 x4 -- x1 x2 x3 x4 x1 x2 )
+
+ +

+ +Copy cell +pair x1 x2 to the top of the stack. + +

+ +


+ + +6.1.0430 2SWAP + + +
+two-swap CORE +
+
+	( x1 x2 x3 x4 -- x3 x4 x1 x2 )
+
+ +

+ +Exchange the +top two cell pairs. + +

+ +


+ + +6.1.0450 : + + +
+colon CORE +
+
+	( C: "<spaces>name" -- colon-sys )
+
+ +

+ +Skip leading space delimiters. Parse name delimited by a space. Create +a definition for name, called a colon definition. Enter +compilation state and start the current definition, producing colon-sys. +Append the initiation semantics given below to the current definition. + +

+ +The execution semantics of name will be determined by the words compiled +into the body of the definition. The current definition shall not be +findable in the dictionary until it is ended (or until the execution of +DOES> +in some systems). +

+

+	Initiation: ( i*x -- i*x )  ( R:  -- nest-sys )
+
+

+ +Save implementation-dependent information nest-sys about the calling +definition. The stack effects i*x represent arguments to name. + +

+

+	name Execution: ( i*x -- j*x )
+
+

+ +Execute the definition name. The stack effects i*x and j*x represent +arguments to and results from name, respectively. + +

+ + +See: +3.4 The Forth text interpreter, +3.4.1 Parsing, +3.4.5 Compilation, +6.1.2500 [ , +6.1.2540 ] , +15.6.2.0470 ;CODE , +A.6.1.0450 : , +RFI 0005 Initiation semantics. + + + +

+ +


+ + +6.1.0460 ; + + +
+semicolon CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( C: colon-sys -- )
+
+

+ +Append the run-time semantics below to the current definition. End the +current definition, allow it to be found in the dictionary and enter +interpretation state, consuming colon-sys. If the data-space pointer is +not aligned, reserve enough data space to align it. + +

+

+	Run-time: ( -- ) ( R: nest-sys -- )
+
+

+ +Return to +the calling definition specified by nest-sys. + +

+ + +See: +3.4 The Forth text interpreter, +3.4.5 Compilation, +A.6.1.0460 ; + + +

+ +


+ + +6.1.0480 < + + +
+less-than CORE +
+
+	( n1 n2 -- flag )
+
+ +

+ +flag is +true if and only if n1 is less than n2. + +

+ + +See: +6.1.2340 U< + + +

+ +


+ + +6.1.0490 <# + + +
+less-number-sign CORE +
+
+	( -- )
+
+ +

+ +Initialize the +pictured numeric output conversion process. + +

+ + +See: +6.1.0030 # , +6.1.0040 #> , +6.1.0050 #S + + +

+ +


+ + +6.1.0530 = + + +
+equals CORE +
+
+	( x1 x2 -- flag )
+
+ +

+ +flag is true +if and only if x1 is bit-for-bit the same as x2. + +

+ +


+ + +6.1.0540 > + + +
+greater-than CORE +
+
+	( n1 n2 -- flag )
+
+ +

+ +flag is true +if and only if n1 is greater than n2. + +

+ + +See: +6.2.2350 U> + + +

+ +


+ + +6.1.0550 >BODY + + +
+to-body CORE +
+
+	( xt -- a-addr )
+
+ +

+ +a-addr is the data-field address corresponding to xt. An ambiguous +condition exists if xt is not for a word defined via +CREATE. + +

+ + +See: +3.3.3 Data space, +A.6.1.0550 >BODY + + + +

+ +


+ + +6.1.0560 >IN + + +
+to-in CORE +
+
+	( -- a-addr )
+
+ +

+ +a-addr is the address of a cell containing the offset in characters from +the start of the input buffer to the start of the parse area. + +

+ +


+ + +6.1.0570 >NUMBER + + +
+to-number CORE +
+
+	( ud1 c-addr1 u1 -- ud2 c-addr2 u2 )
+
+ +

+ +ud2 is the unsigned result of converting the characters within the +string specified by c-addr1 u1 into digits, using the number in +BASE, +and adding each into ud1 after multiplying ud1 by the number in BASE. +Conversion continues left-to-right until a character that is not +convertible, including any + or -, is encountered or the +string is entirely converted. c-addr2 is the location of the first +unconverted character or the first character past the end of the string +if the string was entirely converted. u2 is the number of unconverted +characters in the string. An ambiguous condition exists if ud2 +overflows during the conversion. + +

+ + +See: +3.2.1.2 Digit conversion + + +

+ +


+ + +6.1.0580 >R + + +
+to-r CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Execution: ( x -- ) ( R:  -- x )
+
+

+ +Move x to +the return stack. + +

+ + +See: +3.2.3.3 Return stack, +6.1.2060 R> , +6.1.2070 R@ , +6.2.0340 2>R , +6.2.0410 2R> , +6.2.0415 2R@ + +

+ +


+ + +6.1.0630 ?DUP + + +
+question-dupe CORE +
+
+	( x -- 0 | x x )
+
+ +

+ +Duplicate x +if it is non-zero. + +

+ +


+ + +6.1.0650 @ + + +
+fetch CORE +
+
+	( a-addr -- x )
+
+ +

+ +x is the +value stored at a-addr. + +

+ + +See: +3.3.3.1 Address alignment + + +

+ +


+ + +6.1.0670 ABORT + + +
+CORE +
+
+	( i*x -- ) ( R: j*x -- )
+
+ +

+ +Empty the data stack and perform the function of +QUIT, which includes +emptying the return stack, without displaying a message. + +

+ + +See: +9.6.2.0670 ABORT + + +

+ +


+ + +6.1.0680 ABORT" + + +
+abort-quote CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( "ccc<quote>" -- )
+
+

+ +Parse ccc delimited by a " (double-quote). Append the run-time semantics +given below to the current definition. + +

+

+	Run-time: ( i*x x1 --  | i*x ) ( R: j*x --  | j*x )
+
+

+ +Remove x1 from the stack. If any bit of x1 is not zero, display ccc and +perform an implementation-defined abort sequence that includes the +function of +ABORT. + +

+ + +See: +3.4.1 Parsing, +9.6.2.0680 ABORT" , +A.6.1.0680 ABORT" + + +

+ +


+ + +6.1.0690 ABS + + +
+abs CORE +
+
+	( n -- u )
+
+ +

+ +u is the +absolute value of n. + +

+ +


+ + +6.1.0695 ACCEPT + + +
+CORE +
+	( c-addr +n1 -- +n2 )
+
+ +

+ +Receive a string of at most +n1 characters. An ambiguous condition +exists if +n1 is zero or greater than 32,767. Display graphic +characters as they are received. A program that depends on the presence +or absence of non-graphic characters in the string has an environmental +dependency. The editing functions, if any, that the system performs in +order to construct the string are implementation-defined. + +

+ +Input terminates when an implementation-defined line terminator is +received. When input terminates, nothing is appended to the string, and +the display is maintained in an implementation-defined way. + +

+ ++n2 is the +length of the string stored at c-addr. + +

+ +See: +A.6.1.0695 ACCEPT + +

+ +


+ + +6.1.0705 ALIGN + + +
+CORE +
+
+	( -- )
+
+ +

+ +If the data-space pointer is not aligned, reserve enough space to align +it. + +

+ + +See: +3.3.3 Data space, +3.3.3.1 Address alignment, +A.6.1.0705 ALIGN + + + +

+ +


+ + +6.1.0706 ALIGNED + + +
+CORE +
+
+	( addr -- a-addr )
+
+ +

+ +a-addr +is the first aligned address greater than or equal to addr. + +

+ + +See: +3.3.3.1 Address alignment, +6.1.0705 ALIGN + + + +

+ +


+ + +6.1.0710 ALLOT + + +
+CORE +
+
+	( n -- )
+
+ +

+ +If n is greater than zero, reserve n address units of data space. If n +is less than zero, release |n| address units of data space. If n is +zero, leave the data-space pointer unchanged. + +

+ +If the data-space pointer is aligned and n is a multiple of the size of +a cell when ALLOT begins execution, it will remain aligned when ALLOT +finishes execution. + +

+ +If the data-space pointer is character aligned and n is a multiple of +the size of a character when ALLOT begins execution, it will remain +character aligned when ALLOT finishes execution. + +

+ + +See: +3.3.3 Data space + + +

+ +


+ + +6.1.0720 AND + + +
+CORE +
+
+	( x1 x2 -- x3 )
+
+ +

+ +x3 is +the bit-by-bit logical and of x1 with x2. + +

+ +


+ + +6.1.0750 BASE + + +
+CORE +
+
+	( -- a-addr )
+
+ +

+ +a-addr is the address of a cell containing the current number-conversion +radix {{2...36}}. + +

+ +


+ + +6.1.0760 BEGIN + + +
+CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( C: -- dest )
+
+

+ +Put the next location for a transfer of control, dest, onto the control +flow stack. Append the run-time semantics given below to the current +definition. + +

+

+	Run-time: ( -- )
+
+

+ +Continue +execution. + +

+ + +See: +3.2.3.2 Control-flow stack, +6.1.2140 REPEAT , +6.1.2390 UNTIL , +6.1.2430 WHILE , +A.6.1.0760 BEGIN + + +

+ +


+ + +6.1.0770 BL + + +
+b-l CORE +
+
+	( -- char )
+
+ +

+ +char is +the character value for a space. + +

+ +See: +A.6.1.0770 BL + +

+ +


+ + +6.1.0850 C! + + +
+c-store CORE +
+
+	( char c-addr -- )
+
+ +

+ +Store char at c-addr. When character size is smaller than cell size, +only the number of low-order bits corresponding to character size are +transferred. + +

+ + +See: +3.3.3.1 Address alignment + + +

+ +


+ + +6.1.0860 C, + + +
+c-comma CORE +
+
+	( char -- )
+
+ +

+ +Reserve space for one character in the data space and store char in the +space. If the data-space pointer is character aligned when C, begins +execution, it will remain character aligned when C, finishes execution. +An ambiguous condition exists if the data-space pointer is not +character-aligned prior to execution of C,. + +

+ + +See: +3.3.3 Data space, +3.3.3.1 Address alignment. + + +

+ +


+ + +6.1.0870 C@ + + +
+c-fetch CORE +
+
+	( c-addr -- char )
+
+ +

+ +Fetch the character stored at c-addr. When the cell size is greater +than character size, the unused high-order bits are all zeroes. + +

+ + +See: +3.3.3.1 Address alignment + + +

+ +


+ + +6.1.0880 CELL+ + + +
+CORE +
+
+	( a-addr1 -- a-addr2 )
+
+ +

+ +Add the +size in address units of a cell to a-addr1, giving a-addr2. + +

+ + +See: +3.3.3.1 Address alignment, +A.6.1.0880 CELL+ + + + +

+ +


+ + +6.1.0890 CELLS + + +
+CORE +
+
+	( n1 -- n2 )
+
+ +

+ +n2 is +the size in address units of n1 cells. + +

+ +See: +A.6.1.0890 CELLS + +

+ +


+ + +6.1.0895 CHAR + + +
+char CORE +
+
+	( "<spaces>name" -- char )
+
+ +

+ +Skip leading +space delimiters. Parse name delimited by a space. Put the +value of its first character onto the stack. + +

+ + +See: +3.4.1 Parsing, +6.1.2520 [CHAR] , +A.6.1.0895 CHAR + + +

+ +


+ + +6.1.0897 CHAR+ + + +
+char-plus CORE +
+
+	( c-addr1 -- c-addr2 )
+
+ +

+ +Add the +size in address units of a character to c-addr1, giving c-addr2. + +

+ + +See: +3.3.3.1 Address alignment + + +

+ +


+ + +6.1.0898 CHARS + + +
+chars CORE +
+
+	( n1 -- n2 )
+
+ +

+ +n2 is +the size in address units of n1 characters. + + +

+ +


+ + +6.1.0950 CONSTANT + + +
+CORE +
+
+	( x "<spaces>name" -- )
+
+ +

+ +Skip leading +space delimiters. Parse name delimited by a space. Create a +definition for name with the execution semantics defined below. + +

+ +name is +referred to as a constant. + +

+

+	name Execution: ( -- x )
+
+

+ +Place x +on the stack. + +

+ + +See: +3.4.1 Parsing, +A.6.1.0950 CONSTANT + + +

+ +


+ + +6.1.0980 COUNT + + +
+CORE +
+
+	( c-addr1 -- c-addr2 u )
+
+ +

+ +Return the +character string specification for the counted string stored at +c-addr1. c-addr2 is the address of the first character after c-addr1. u is +the contents of the character at c-addr1, which is the length in characters of +the string at c-addr2. + +

+ +


+ + +6.1.0990 CR + + +
+c-r CORE +
+
+	( -- )
+
+ +

+ +Cause subsequent +output to appear at the beginning of the next line. + +

+ +


+ + +6.1.1000 CREATE + + +
+CORE +
+
+	( "<spaces>name" -- )
+
+ +

+ +Skip leading +space delimiters. Parse name delimited by a space. Create a +definition for name with the execution semantics defined below. If the +data-space pointer is not aligned, reserve enough data space to align it. The +new data-space pointer defines name's data field. CREATE does not allocate +data space in name's data field. + +

+

+	name Execution: ( -- a-addr )
+
+

+ +a-addr is the address of name's data field. The execution semantics of name +may be extended by using +DOES>. + +

+ + +See: +3.3.3 Data space, +A.6.1.1000 CREATE + + +

+ +


+ + +6.1.1170 DECIMAL + + +
+CORE +
+
+	( -- )
+
+ +

+ +Set the +numeric conversion radix to ten (decimal). + +

+ +


+ + +6.1.1200 DEPTH + + +
+CORE +
+
+	( -- +n )
+
+ +

+ ++n is the number of single-cell values contained in the data stack +before +n was placed on the stack. + +

+ +


+ + +6.1.1240 DO + + +
+CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( C: -- do-sys )
+
+

+ +Place do-sys onto the control-flow stack. Append the run-time semantics +given below to the current definition. The semantics are incomplete +until resolved by a consumer of do-sys such as +LOOP. + +

+

+	Run-time: ( n1|u1 n2|u2 -- ) ( R: -- loop-sys )
+
+

+ +Set up loop control parameters with index n2|u2 and limit n1|u1. An +ambiguous condition exists if n1|u1 and n2|u2 are not both the same +type. Anything already on the return stack becomes unavailable until +the loop-control parameters are discarded. + +

+ + +See: +3.2.3.2 Control-flow stack, +6.1.0140 +LOOP , +A.6.1.1240 DO + + +

+ +


+ + +6.1.1250 DOES> + + +
+does CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( C: colon-sys1 -- colon-sys2 )
+
+

+ +Append the run-time semantics below to the current definition. Whether +or not the current definition is rendered findable in the dictionary by +the compilation of DOES> is implementation defined. Consume +colon-sys1 and produce colon-sys2. Append the initiation semantics +given below to the current definition. + +

+

+	Run-time: ( -- ) ( R: nest-sys1 -- )
+
+

+ +Replace the execution semantics of the most recent definition, referred +to as name, with the name execution semantics given below. Return +control to the calling definition specified by nest-sys1. An ambiguous +condition exists if name was not defined with +CREATE +or a user-defined +word that calls CREATE. + +

+

+	Initiation: ( i*x -- i*x a-addr ) ( R:  -- nest-sys2 )
+
+

+ +Save implementation-dependent information nest-sys2 about the calling +definition. Place name's data field address on the stack. The stack +effects i*x represent arguments to name. + +

+

+	name Execution: ( i*x -- j*x )
+
+

+ +Execute the portion of the definition that begins with the initiation +semantics appended by the DOES> which modified name. The stack +effects i*x and j*x represent arguments to and results from name, +respectively. + +

+ + +See: +A.6.1.1250 DOES> , +RFI 0003 Defining words etc., +RFI 0005 Initiation semantics. + + +

+ +


+ + +6.1.1260 DROP + + +
+CORE +
+
+	( x -- )
+
+ +

+ +Remove x +from the stack. + +

+ +


+ + +6.1.1290 DUP + + +
+dupe CORE +
+
+	( x -- x x )
+
+ +

+ +Duplicate +x. + +

+ +


+ + +6.1.1310 ELSE + + +
+CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( C: orig1 -- orig2 )
+
+

+ +Put the location of a new unresolved forward reference orig2 onto the +control flow stack. Append the run-time semantics given below to the +current definition. The semantics will be incomplete until orig2 is +resolved (e.g., by +THEN). +Resolve the forward reference orig1 using the +location following the appended run-time semantics. + +

+

+	Run-time: ( -- )
+
+

+ +Continue execution at the location given by the resolution of orig2. + +

+ + +See: +6.1.1700 IF , +A.6.1.1310 ELSE + + +

+ +


+ + +6.1.1320 EMIT + + +
+CORE +
+
+	( x -- )
+
+ +

+ +If x is a graphic character in the implementation-defined character set, +display x. The effect of EMIT for all other values of x is +implementation-defined. + +

+ +When passed a character whose character-defining bits have a value +between hex 20 and 7E inclusive, the corresponding standard character, +specified by +3.1.2.1 +Graphic characters, is displayed. Because +different output devices can respond differently to control characters, +programs that use control characters to perform specific functions have +an environmental dependency. Each EMIT deals with only one character. + +

+ + +See: +6.1.2310 TYPE + + +

+ +


+ + +6.1.1345 ENVIRONMENT? + + +
+environment-query CORE +
+
+	( c-addr u -- false | i*x true )
+
+ +

+ +c-addr is the address of a character string and u is the string's +character count. u may have a value in the range from zero to an +implementation-defined maximum which shall not be less than 31. The +character string should contain a keyword from +3.2.6 Environmental +queries or the optional word sets to be checked for correspondence with +an attribute of the present environment. If the system treats the +attribute as unknown, the returned flag is false; otherwise, the flag is +true and the i*x returned is of the type specified in the table for the +attribute queried. + +

+ +See: +A.6.1.1345 ENVIRONMENT? + +

+ +


+ + +6.1.1360 EVALUATE + + +
+CORE +
+
+	( i*x c-addr u -- j*x )
+
+ +

+ +Save the current input source specification. Store minus-one (-1) in +SOURCE-ID +if it is present. Make the string described by c-addr and u +both the input source and input buffer, set +>IN +to zero, and +interpret. When the parse area is empty, restore the prior input source +specification. Other stack effects are due to the words EVALUATEd. + +

+ +See: +7.6.1.1360 EVALUATE , +A.6.1.1360 EVALUATE , +RFI 0006 Writing to Input Buffers. + +

+ +


+ + +6.1.1370 EXECUTE + + +
+CORE +
+
+	( i*x xt -- j*x )
+
+ +

+ +Remove xt from the stack and perform the semantics identified by it. +Other stack effects are due to the word EXECUTEd. + +

+ + +See: +6.1.0070 ' , +6.1.2510 ['] + + +

+ +


+ + +6.1.1380 EXIT + + +
+CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Execution: ( -- ) ( R: nest-sys -- )
+
+

+ +Return control to the calling definition specified by nest-sys. Before +executing EXIT within a do-loop, a program shall discard the loop-control +parameters by executing +UNLOOP. + +

+ + +See: +3.2.3.3 Return stack, +A.6.1.1380 EXIT + + +

+ +


+ + +6.1.1540 FILL + + +
+CORE +
+
+	( c-addr u char -- )
+
+ +

+ +If u +is greater than zero, store char in each of u consecutive characters of +memory beginning at c-addr. + +

+ +


+ + +6.1.1550 FIND + + +
+CORE +
+
+	( c-addr -- c-addr 0  |  xt 1  |  xt -1 )
+
+ +

+ +Find the definition named in the counted string at c-addr. If the +definition is not found, return c-addr and zero. If the definition is +found, return its execution token xt. If the definition is immediate, +also return one (1), otherwise also return minus-one (-1). For a given +string, the values returned by FIND while compiling may differ from +those returned while not compiling. + +

+ + +See: +3.4.2 Finding definition names, +6.1.0070 ' , +6.1.2510 ['] , +A.6.1.1550 FIND , +A.6.1.2033 POSTPONE , +D.6.7 Immediacy. + + +

+ +


+ + +6.1.1561 FM/MOD + + +
+f-m-slash-mod CORE +
+
+	( d1 n1 -- n2 n3 )
+
+ +

+ +Divide d1 by n1, giving the floored quotient n3 and the remainder n2. +Input and output stack arguments are signed. An ambiguous condition +exists if n1 is zero or if the quotient lies outside the range of a +single-cell signed integer. + +

+ + +See: +3.2.2.1 Integer division, +6.1.2214 SM/REM , +6.1.2370 UM/MOD , +A.6.1.1561 FM/MOD + + +

+ +


+ + +6.1.1650 HERE + + +
+CORE +
+
+	( -- addr )
+
+ +

+ +addr is +the data-space pointer. + +

+ + +See: +3.3.3.2 Contiguous regions + + +

+ +


+ + +6.1.1670 HOLD + + +
+CORE +
+
+	( char -- )
+
+ +

+ +Add char +to the beginning of the pictured numeric output string. An ambiguous +condition exists if HOLD executes outside of a +<# +#> +delimited number +conversion. + +

+ +


+ + +6.1.1680 I + + +
+CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Execution: ( -- n|u ) ( R:  loop-sys -- loop-sys )
+
+

+ +n|u is a copy of the current (innermost) loop index. An ambiguous condition +exists if the loop control parameters are unavailable. + +

+ +


+ + +6.1.1700 IF + + +
+CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( C: -- orig )
+
+

+ +Put the location of a new unresolved forward reference orig onto the +control flow stack. Append the run-time semantics given below to the +current definition. The semantics are incomplete until orig is +resolved, e.g., by +THEN or +ELSE. + +

+

+	Run-time: ( x -- )
+
+

+ +If all bits of x are zero, continue execution at the location specified +by the resolution of orig. + +

+ + +See: +3.2.3.2 Control flow stack, +A.6.1.1700 IF + + +

+ +


+ + +6.1.1710 IMMEDIATE + + +
+CORE +
+
+	( -- )
+
+ +

+ +Make the +most recent definition an immediate word. An ambiguous condition +exists if the most recent definition does not have a name. + +

+ + +See: +A.6.1.1710 IMMEDIATE , +D.6.7 Immediacy, +RFI 0007 Distinction between immediacy and special compilation semantics. + + +

+ +


+ + +6.1.1720 INVERT + + +
+CORE +
+
+	( x1 -- x2 )
+
+ +

+ +Invert all +bits of x1, giving its logical inverse x2. + +

+ + +See: +6.1.1910 NEGATE , +6.1.0270 0= , +A.6.1.1720 INVERT + + +

+ +


+ + +6.1.1730 J + + +
+CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Execution: ( -- n|u ) ( R: loop-sys1 loop-sys2 -- loop-sys1 loop-sys2 )
+
+

+ +n|u is a copy of the next-outer loop index. An ambiguous condition +exists if the loop control parameters of the next-outer loop, loop-sys1, +are unavailable. + +

+ +See: +A.6.1.1730 J + +

+ +


+ + +6.1.1750 KEY + + +
+CORE +
+
+	( -- char )
+
+ +

+ +Receive one character char, a member of the implementation-defined +character set. Keyboard events that do not correspond to such +characters are discarded until a valid character is received, and those +events are subsequently unavailable. + +

+ +All standard characters can be received. Characters received by KEY are +not displayed. + +

+ +Any standard character returned by KEY has the numeric value specified +in +3.1.2.1 +Graphic characters. Programs that require the ability to +receive control characters have an environmental dependency. + +

+ + +See: +10.6.2.1305 EKEY , +10.6.1.1755 KEY? + + +

+ +


+ + +6.1.1760 LEAVE + + +
+CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Execution: ( -- ) ( R: loop-sys -- )
+
+

+ +Discard the current loop control parameters. An ambiguous condition +exists if they are unavailable. Continue execution immediately +following the innermost syntactically enclosing +DO ... +LOOP +or DO ... ++LOOP. + +

+ + +See: +3.2.3.3 Return stack, +A.6.1.1760 LEAVE + + +

+ +


+ + +6.1.1780 LITERAL + + +
+CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( x -- )
+
+

+ +Append the run-time semantics +given below to the current definition. + +

+

+	Run-time: ( -- x )
+
+

+ +Place x +on the stack. + +

+ +See: +A.6.1.1780 LITERAL + +

+ +


+ + +6.1.1800 LOOP + + +
+CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( C: do-sys -- )
+
+

+ +Append the run-time semantics given below to the current definition. +Resolve the destination of all unresolved occurrences of +LEAVE +between +the location given by do-sys and the next location for a transfer of +control, to execute the words following the LOOP. + +

+

+	Run-time: ( -- ) ( R:  loop-sys1 --  | loop-sys2 )
+
+

+ +An ambiguous condition exists if the loop control parameters are +unavailable. Add one to the loop index. If the loop index is then +equal to the loop limit, discard the loop parameters and continue +execution immediately following the loop. Otherwise continue execution +at the beginning of the loop. + +

+ + +See: +6.1.1240 DO , +6.1.1680 I , +A.6.1.1800 LOOP + + +

+ +


+ + +6.1.1805 LSHIFT + + +
+l-shift CORE +
+
+	( x1 u -- x2 )
+
+ +

+ +Perform a +logical left shift of u bit-places on x1, giving x2. Put zeroes +into the least significant bits vacated by the shift. An ambiguous condition +exists if u is greater than or equal to the number of bits in a cell. + +

+ +


+ + +6.1.1810 M* + + +
+m-star CORE +
+
+	( n1 n2 -- d )
+
+ +

+ +d is +the signed product of n1 times n2. + +

+ +See: +A.6.1.1810 M* + +

+ +


+ + +6.1.1870 MAX + + +
+CORE +
+
+	( n1 n2 -- n3 )
+
+ +

+ +n3 is +the greater of n1 and n2. + +

+ +


+ + +6.1.1880 MIN + + +
+CORE +
+
+	( n1 n2 -- n3 )
+
+ +

+ +n3 is +the lesser of n1 and n2. + +

+ +


+ + +6.1.1890 MOD + + +
+CORE +
+
+	( n1 n2 -- n3 )
+
+ +

+ +Divide n1 by n2, giving the single-cell remainder n3. An ambiguous +condition exists if n2 is zero. If n1 and n2 differ in sign, the +implementation-defined result returned will be the same as that returned +by either the phrase +>R S>D R> FM/MOD DROP +or the phrase +>R S>D R> SM/REM DROP. + +

+ + +See: +3.2.2.1 Integer division + + +

+ +


+ + +6.1.1900 MOVE + + +
+CORE +
+
+	( addr1 addr2 u -- )
+
+ +

+ +If u is greater than zero, copy the contents of u consecutive address +units at addr1 to the u consecutive address units at addr2. After MOVE +completes, the u consecutive address units at addr2 contain exactly what +the u consecutive address units at addr1 contained before the move. + +

+ + +See: +17.6.1.0910 CMOVE , +17.6.1.0920 CMOVE> , +A.6.1.1900 MOVE + + +

+ +


+ + +6.1.1910 NEGATE + + +
+CORE +
+
+	( n1 -- n2 )
+
+ +

+ +Negate n1, +giving its arithmetic inverse n2. + +

+ + +See: +6.1.1720 INVERT , +6.1.0270 0= + + +

+ +


+ + +6.1.1980 OR + + +
+CORE +
+
+	( x1 x2 -- x3 )
+
+ +

+ +x3 is +the bit-by-bit inclusive-or of x1 with x2. + +

+ +


+ + +6.1.1990 OVER + + +
+CORE +
+
+	( x1 x2 -- x1 x2 x1 )
+
+ +

+ +Place a +copy of x1 on top of the stack. + +


+ + +6.1.2033 POSTPONE + + +
+CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( "<spaces>name" -- )
+
+

+ +Skip leading space delimiters. Parse name delimited by a space. Find +name. Append the compilation semantics of name to the current +definition. An ambiguous condition exists if name is not found. + +

+ + +See: +D.6.7 Immediacy, +3.4.1 Parsing, +A.6.1.2033 POSTPONE , +6.2.2530 [COMPILE] + + +

+ + +


+ + +6.1.2050 QUIT + + +
+CORE +
+
+	( -- )  ( R:  i*x -- )
+
+ +

+ +Empty the return stack, store zero in +SOURCE-ID +if it is present, make +the user input device the input source, and enter interpretation state. +Do not display a message. Repeat the following: + +

    +
  • Accept a line from the input source into the input buffer, set +>IN +to zero, and interpret. +
  • Display the implementation-defined system prompt if in interpretation +state, all processing has been completed, and no ambiguous condition +exists. +
+

+ + +See: +3.4 The Forth text interpreter + + +

+ +


+ + +6.1.2060 R> + + +
+r-from CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Execution: ( -- x ) ( R:  x -- )
+
+

+ +Move x from +the return stack to the data stack. + +

+ + +See: +3.2.3.3 Return stack, +6.1.0580 >R , +6.1.2070 R@ , +6.2.0340 2>R , +6.2.0410 2R> , +6.2.0415 2R@ + + +

+ +


+ + +6.1.2070 R@ + + +
+r-fetch CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Execution: ( -- x ) ( R:  x -- x )
+
+

+ +Copy x from +the return stack to the data stack. + +

+ + +See: +3.2.3.3 Return stack, +6.1.0580 >R , +6.1.2060 R> , +6.2.0340 2>R , +6.2.0410 2R> , +6.2.0415 2R@ + + +

+ +


+ + +6.1.2120 RECURSE + + +
+CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( -- )
+
+

+ +Append the execution semantics of the current definition to the current +definition. An ambiguous condition exists if RECURSE appears in a +definition after +DOES>. + +

+ + +See: +6.1.2120 RECURSE , +A.6.1.2120 RECURSE + + +

+ +


+ + +6.1.2140 REPEAT + + +
+CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( C: orig dest -- )
+
+

+ +Append the run-time semantics given below to the current definition, +resolving the backward reference dest. Resolve the forward reference +orig using the location following the appended run-time semantics. + +

+

+	Run-time: ( -- )
+
+

+ +Continue execution +at the location given by dest. + +

+ + +See: +6.1.0760 BEGIN , +6.1.2430 WHILE , +A.6.1.2140 REPEAT + + + +

+ +


+ + +6.1.2160 ROT + + +
+rote CORE +
+
+	( x1 x2 x3 -- x2 x3 x1 )
+
+ +

+ +Rotate the +top three stack entries. + + +

+ +


+ + +6.1.2162 RSHIFT + + +
+r-shift CORE +
+
+	( x1 u -- x2 )
+
+ +

+ +Perform a logical right shift of u bit-places on x1, giving x2. Put +zeroes into the most significant bits vacated by the shift. An +ambiguous condition exists if u is greater than or equal to the number +of bits in a cell. + +

+ +


+ + +6.1.2165 S" + + +
+s-quote CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( "ccc<quote>" -- )
+
+

+ +Parse ccc delimited by " (double-quote). Append the run-time semantics +given below to the current definition. + + +

+        Run-time: ( -- c-addr u )
+
+ +

+ +Return c-addr and u describing a string consisting of the characters +ccc. A program shall not alter the returned string. + +

+ + +See: +3.4.1 Parsing, +6.2.0855 C" , +11.6.1.2165 S" , +A.6.1.2165 S" + + +

+ +


+ + +6.1.2170 S>D + + +
+s-to-d CORE +
+
+	( n -- d )
+
+ +

+ +Convert the +number n to the double-cell number d with the same numerical +value. + +

+ +


+ + +6.1.2210 SIGN + + +
+CORE +
+
+	( n -- )
+
+ +

+ +If n is negative, add a minus sign to the beginning of the pictured +numeric output string. An ambiguous condition exists if SIGN executes +outside of a +<# +#> +delimited number conversion. + +

+ +


+ + +6.1.2214 SM/REM + + +
+s-m-slash-rem CORE +
+
+	( d1 n1 -- n2 n3 )
+
+ +

+ +Divide d1 by n1, giving the symmetric quotient n3 and the remainder n2. +Input and output stack arguments are signed. An ambiguous condition +exists if n1 is zero or if the quotient lies outside the range of a +single-cell signed integer. + +

+ + +See: +3.2.2.1 Integer division, +6.1.1561 FM/MOD , +6.1.2370 UM/MOD , +A.6.1.2214 SM/REM + + +

+ +


+ + +6.1.2216 SOURCE + + +
+CORE +
+
+	( -- c-addr u )
+
+ +

+ +c-addr is the address of, and u is the number of characters in, the +input buffer. + +

+ +See: +A.6.1.2216 SOURCE , +RFI 0006 Writing to Input Buffers. + +

+ +


+ + +6.1.2220 SPACE + + +
+CORE +
+
+	( -- )
+
+ +

+ +Display one +space. + +

+ +


+ + +6.1.2230 SPACES + + +
+CORE +
+
+	( n -- )
+
+ +

+ +If n +is greater than zero, display n spaces. + +

+ +


+ + +6.1.2250 STATE + + +
+CORE +
+
+	( -- a-addr )
+
+ +

+ +a-addr is the address of a cell containing the compilation-state flag. +STATE is true when in compilation state, false otherwise. The true +value in STATE is non-zero, but is otherwise implementation-defined. +Only the following standard words alter the value in STATE: : +(colon), ; +(semicolon), +ABORT, +QUIT, +:NONAME, [ +(left-bracket), and ] +(right-bracket). +

+ +Note: A program shall not directly alter the contents of +STATE. + + +

+ + +See: +3.4 The Forth text interpreter, +15.6.2.2250 STATE , +A.6.1.2250 STATE , +RFI 0007 Distinction between immediacy and special compilation semantics. + + +

+ +


+ + +6.1.2260 SWAP + + +
+CORE +
+
+	( x1 x2 -- x2 x1 )
+
+ +

+ +Exchange the +top two stack items. + +

+ +


+ + +6.1.2270 THEN + + +
+CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( C: orig -- )
+
+

+ +Append the run-time semantics given below to the current definition. +Resolve the forward reference orig using the location of the appended +run-time semantics. + +

+

+	Run-time: ( -- )
+
+

+ +Continue +execution. + +

+ + +See: +6.1.1310 ELSE , +6.1.1700 IF , +A.6.1.2270 THEN + + +

+ +


+ + +6.1.2310 TYPE + + +
+CORE +
+
+	( c-addr u -- )
+
+ +

+ +If u is greater than zero, display the character string specified by +c-addr and u. + +

+ +When passed a character in a character string whose character-defining +bits have a value between hex 20 and 7E inclusive, the corresponding +standard character, specified by +3.1.2.1 graphic characters, is +displayed. Because different output devices can respond differently to +control characters, programs that use control characters to perform +specific functions have an environmental dependency. + +

+ + +See: +6.1.1320 EMIT + + +

+ +


+ + +6.1.2320 U. + + +
+u-dot CORE +
+
+	( u -- )
+
+ +

+ +Display u +in free field format. + +

+ +


+ + +6.1.2340 U< + + +
+u-less-than CORE +
+
+	( u1 u2 -- flag )
+
+ +

+ +flag is +true if and only if u1 is less than u2. + +

+ + +See: +6.1.0480 < + + +

+ +


+ + +6.1.2360 UM* + + +
+u-m-star CORE +
+
+	( u1 u2 -- ud )
+
+ +

+ +Multiply u1 by u2, giving the unsigned double-cell product ud. All +values and arithmetic are unsigned. + +

+ +


+ + +6.1.2370 UM/MOD + + +
+u-m-slash-mod CORE +
+
+	( ud u1 -- u2 u3 )
+
+ +

+ +Divide ud by u1, giving the quotient u3 and the remainder u2. All +values and arithmetic are unsigned. An ambiguous condition exists if u1 +is zero or if the quotient lies outside the range of a single-cell +unsigned integer. + +

+ + +See: +3.2.2.1 Integer division, +6.1.1561 FM/MOD , +6.1.2214 SM/REM + + +

+ +


+ + +6.1.2380 UNLOOP + + +
+CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Execution: ( -- ) ( R: loop-sys -- )
+
+

+ +Discard the loop-control parameters for the current nesting level. An +UNLOOP is required for each nesting level before the definition may be +EXITed. +An ambiguous condition exists if the loop-control parameters +are unavailable. + +

+ + +See: +3.2.3.3 Return stack, +A.6.1.2380 UNLOOP + + +

+ +


+ + +6.1.2390 UNTIL + + +
+CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( C: dest -- )
+
+

+ +Append the run-time semantics given below to the current definition, +resolving the backward reference dest. + +

+

+	Run-time: ( x -- )
+
+

+ +If all bits of x are zero, continue execution at the location specified +by dest. + +

+ + +See: +6.1.0760 BEGIN , +A.6.1.2390 UNTIL + + +

+ +


+ + +6.1.2410 VARIABLE + + +
+CORE +
+
+	( "<spaces>name" -- )
+
+ +

+ +Skip leading space delimiters. Parse name delimited by a space. Create +a definition for name with the execution semantics defined below. +Reserve one cell of data space at an aligned address. + +

+ +name is referred +to as a variable. + +

+

+	name Execution: ( -- a-addr )
+
+

+ +a-addr is the address of the reserved cell. A program is responsible +for initializing the contents of the reserved cell. + +

+ + +See: +3.4.1 Parsing, +A.6.1.2410 VARIABLE + + +

+ +


+ + +6.1.2430 WHILE + + +
+CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( C: dest -- orig dest )
+
+

+ +Put the location of a new unresolved forward reference orig onto the +control flow stack, under the existing dest. Append the run-time +semantics given below to the current definition. The semantics are +incomplete until orig and dest are resolved (e.g., by +REPEAT). + +

+

+	Run-time: ( x -- )
+
+

+ +If all bits of x are zero, continue execution at the location specified +by the resolution of orig. + +

+ +See: +A.6.1.2430 WHILE + +

+ +


+ + +6.1.2450 WORD + + +
+CORE +
+
+	( char "<chars>ccc<char>" -- c-addr )
+
+ +

+ +Skip leading delimiters. Parse characters ccc delimited by char. An +ambiguous condition exists if the length of the parsed string is greater +than the implementation-defined length of a counted string. + +

+ +c-addr is the address of a transient region containing the parsed word +as a counted string. If the parse area was empty or contained no +characters other than the delimiter, the resulting string has a zero +length. A space, not included in the length, follows the string. A +program may replace characters within the string. + +

+ +Note: The requirement to follow the string with a space is +obsolescent and is included as a concession to existing programs that +use +CONVERT. +A program shall not depend on the existence of the +space. + + +

+ + +See: +3.3.3.6 Other transient regions, +3.4.1 Parsing, +6.2.2008 PARSE , +A.6.1.2450 WORD + + +

+ +


+ + +6.1.2490 XOR + + +
+x-or CORE +
+
+	( x1 x2 -- x3 )
+
+ +

+ +x3 is +the bit-by-bit exclusive-or of x1 with x2. + +

+ +


+ + +6.1.2500 [ + + +
+left-bracket CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: Perform the execution semantics given below.
+
+

+

+	Execution: ( -- )
+
+

+ +Enter interpretation +state. [ is an immediate word. + +

+ + +See: +3.4 The Forth text interpreter, +3.4.5 Compilation, +6.1.2540 ] , +A.6.1.2500 [ + + +

+ +


+ + +6.1.2510 ['] + + +
+bracket-tick CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( "<spaces>name" -- )
+
+

+ +Skip leading space delimiters. Parse name delimited by a space. Find +name. Append the run-time semantics given below to the current +definition. + +

+ +An ambiguous condition +exists if name is not found. + +

+

+	Run-time: ( -- xt )
+
+

+ +Place name's execution token xt on the stack. The execution token +returned by the compiled phrase +['] X is the same value returned +by ' X outside of compilation state. + +

+ + +See: +3.4.1 Parsing, +6.1.0070 ' , +A.6.1.2033 POSTPONE , +A.6.1.2510 ['] , +D.6.7 Immediacy. + + +

+ +


+ + +6.1.2520 [CHAR] + + +
+bracket-char CORE +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( "<spaces>name" -- )
+
+

+ +Skip leading space delimiters. Parse name delimited by a space. Append the +run-time semantics given below to the current definition. + +

+

+	Run-time: ( -- char )
+
+

+ +Place char, the +value of the first character of name, on the stack. + +

+ + +See: +3.4.1 Parsing, +6.1.0895 CHAR , +A.6.1.2520 [CHAR] + + +

+ +


+ + +6.1.2540 ] + + +
+right-bracket CORE +
+
+	( -- )
+
+ +

+ +Enter compilation +state. + +

+ + +See: +3.4 The Forth text interpreter, +3.4.5 Compilation, +6.1.2500 [ , +A.6.1.2540 ] , + + + +


+ +

6.2 Core extension words

+
+ +

+ +See: +A.6.2 Core extension words + +

+ +


+ + +6.2.0060 #TIB + + +
+number-t-i-b CORE EXT +
+
+	( -- a-addr )
+
+ +

+ +a-addr +is the address of a cell containing the number of characters in the +terminal input buffer. + +

+ +Note: This word is obsolescent and is included as a concession to +existing implementations. + + +

+ +See: +A.6.2.0060 #TIB + +

+ +


+ + +6.2.0200 .( + + +
+dot-paren CORE EXT +
+ +

+

+	Compilation: Perform the execution semantics given below.
+
+

+

+	Execution: ( "ccc<paren>" -- )
+
+

+ +Parse and display ccc delimited by ) (right parenthesis). .( is an +immediate word. + +

+ + +See: +3.4.1 Parsing, +6.1.0190 ." , +A.6.2.0200 .( + + +

+ +


+ + +6.2.0210 .R + + +
+dot-r CORE EXT +
+
+	( n1 n2 -- )
+
+ +

+ +Display n1 right aligned in a field n2 characters wide. If the number +of characters required to display n1 is greater than n2, all digits are +displayed with no leading spaces in a field as wide as necessary. + +

+ +See: +A.6.2.0210 .R + +

+ +


+ + +6.2.0260 0<> + + +
+zero-not-equals CORE EXT +
+
+	( x -- flag )
+
+ +

+ +flag is +true if and only if x is not equal to zero. + +

+ +


+ + +6.2.0280 0> + + +
+zero-greater CORE EXT +
+
+	( n -- flag )
+
+ +

+ +flag is +true if and only if n is greater than zero. + +

+ +


+ + +6.2.0340 2>R + + +
+two-to-r CORE EXT +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Execution: ( x1 x2 -- ) ( R:  -- x1 x2 )
+
+

+ +Transfer cell pair x1 x2 to the return stack. Semantically equivalent +to + +SWAP >R >R +. + +

+ + +See: +3.2.3.3 Return stack, +6.1.0580 >R , +6.1.2060 R> , +6.1.2070 R@ , +6.2.0410 2R> , +6.2.0415 2R@ , +A.6.2.0340 2>R + + +

+ +


+ + +6.2.0410 2R> + + +
+two-r-from CORE EXT +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Execution: ( -- x1 x2 ) ( R:  x1 x2 -- )
+
+

+ +Transfer cell pair x1 x2 from the return stack. Semantically equivalent +to + +R> R> SWAP +. + +

+ + +See: +3.2.3.3 Return stack, +6.1.0580 >R , +6.1.2060 R> , +6.1.2070 R@ , +6.2.0340 2>R , +6.2.0415 2R@ , +A.6.2.0410 2R> + + +

+ +


+ + +6.2.0415 2R@ + + +
+two-r-fetch CORE EXT +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Execution: ( -- x1 x2 ) ( R:  x1 x2 -- x1 x2 )
+
+

+ +Copy cell pair x1 x2 from the return stack. Semantically equivalent to + +R> R> 2DUP >R >R SWAP +. + +

+ + +See: +3.2.3.3 Return stack, +6.1.0580 >R , +6.1.2060 R> , +6.1.2070 R@ , +6.2.0340 2>R , +6.2.0410 2R> + + +

+ +


+ + +6.2.0455 :NONAME + + +
+colon-no-name CORE EXT +
+
+	( C:  -- colon-sys )  ( S:  -- xt )
+
+ +

+ +Create an execution token xt, enter compilation state and start the +current definition, producing colon-sys. Append the initiation +semantics given below to the current definition. + +

+ +The execution semantics of xt will be determined by the words compiled +into the body of the definition. This definition can be executed later +by using xt +EXECUTE. + +

+ +If the control-flow stack is implemented using the data stack, colon-sys +shall be the topmost item on the data stack. + +

+ +

+	Initiation: ( i*x -- i*x ) ( R:  -- nest-sys )
+
+

+ +Save implementation-dependent information nest-sys about the calling +definition. The stack effects i*x represent arguments to xt. + +

+

+	xt Execution: ( i*x -- j*x )
+
+

+ +Execute the definition specified by xt. The stack effects i*x and j*x +represent arguments to and results from xt, respectively. + +

+ +See: +A.6.2.0455 :NONAME , +3.2.3.2 Control-flow stack. + +

+ +


+ + +6.2.0500 <> + + +
+not-equals CORE EXT +
+
+	( x1 x2 -- flag )
+
+ +

+ +flag is +true if and only if x1 is not bit-for-bit the same as x2. + +

+ +


+ + +6.2.0620 ?DO + + +
+question-do CORE EXT +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( C: -- do-sys )
+
+

+ +Put do-sys onto the control-flow stack. Append the run-time semantics +given below to the current definition. The semantics are incomplete +until resolved by a consumer of do-sys such as +LOOP. +

+

+	Run-time: ( n1|u1 n2|u2 -- ) ( R: --  | loop-sys )
+
+

+ +If n1|u1 is equal to n2|u2, continue execution at the location given by +the consumer of do-sys. Otherwise set up loop control parameters with +index n2|u2 and limit n1|u1 and continue executing immediately following +?DO. Anything already on the return stack becomes unavailable until the +loop control parameters are discarded. An ambiguous condition exists if +n1|u1 and n2|u2 are not both of the same type. + +

+ + +See: +3.2.3.2 Control-flow stack, +6.1.0140 +LOOP , +6.1.1240 DO , +6.1.1680 I , +6.1.1760 LEAVE , +6.1.2380 UNLOOP , +A.6.2.0620 ?DO + + +

+ +


+ + +6.2.0700 AGAIN + + +
+CORE EXT +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( C: dest -- )
+
+

+ +Append the run-time semantics given below to the current definition, +resolving the backward reference dest. + +

+

+	Run-time: ( -- )
+
+

+ +Continue execution at the location specified by dest. If no other +control flow words are used, any program code after AGAIN will not be +executed. + +

+ +See: +6.1.0760 BEGIN , +A.6.2.0700 AGAIN + + +

+ +


+ + +6.2.0855 C" + + +
+c-quote CORE EXT +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( "ccc<quote>" -- )
+
+

+ +Parse ccc delimited by " (double-quote) and append the run-time +semantics given below to the current definition. + +

+

+	Run-time: ( -- c-addr )
+
+

+ +Return c-addr, a counted string consisting of the characters ccc. A +program shall not alter the returned string. + +

+ + +See: +3.4.1 Parsing, +6.1.2165 S" , +11.6.1.2165 S" , +A.6.2.0855 C" + + +

+ +


+ + +6.2.0873 CASE + + +
+CORE EXT +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( C: -- case-sys )
+
+

+ +Mark the start of the CASE ... +OF ... +ENDOF ... +ENDCASE structure. +Append the run-time semantics given below to the current definition. + +

+

+	Run-time: ( -- )
+
+

+ +Continue +execution. + +

+ + +See: +A.6.2.0873 CASE + + +

+ +


+ + +6.2.0945 COMPILE, + + +
+compile-comma CORE EXT +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Execution: ( xt -- )
+
+

+ +Append the execution semantics of the definition represented by xt to +the execution semantics of the current definition. + +

+ +See: +A.6.2.0945 COMPILE, + +

+ +


+ + +6.2.0970 CONVERT + + +
+CORE EXT +
+
+	( ud1 c-addr1 -- ud2 c-addr2 )
+
+ +

+ +ud2 is the result of converting the characters within the text beginning +at the first character after c-addr1 into digits, using the number in +BASE, +and adding each digit to ud1 after multiplying ud1 by the number +in BASE. Conversion continues until a character that is not convertible +is encountered. c-addr2 is the location of the first unconverted +character. An ambiguous condition exists if ud2 overflows. + +

+ +Note: This word is obsolescent and is included as a concession to +existing implementations. Its function is superseded by +6.1.0570 +>NUMBER. + +

+ + +See: +3.2.1.2 Digit conversion, +A.6.2.0970 CONVERT + + +

+ +


+ + +6.2.1342 ENDCASE + + +
+end-case CORE EXT +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( C: case-sys -- )
+
+

+ +Mark the end of the +CASE ... +OF ... +ENDOF +... ENDCASE structure. Use +case-sys to resolve the entire structure. Append the run-time semantics +given below to the current definition. + +

+

+	Run-time: ( x -- )
+
+

+ +Discard the +case selector x and continue execution. + +

+ + +See: +A.6.2.1342 ENDCASE + + +

+ +


+ + +6.2.1343 ENDOF + + +
+end-of CORE EXT +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( C: case-sys1 of-sys -- case-sys2 )
+
+

+ +Mark the end of the +OF +... ENDOF part of the +CASE +structure. The next +location for a transfer of control resolves the reference given by +of-sys. Append the run-time semantics given below to the current +definition. Replace case-sys1 with case-sys2 on the control-flow stack, +to be resolved by +ENDCASE. + +

+

+	Run-time: ( -- )
+
+

+ +Continue execution at +the location specified by the consumer of case-sys2. + +

+ + +See: +A.6.2.1343 ENDOF + + +

+ +


+ + +6.2.1350 ERASE + + +
+CORE EXT +
+
+	( addr u -- )
+
+ +

+ +If u +is greater than zero, clear all bits in each of u consecutive address +units of memory beginning at addr . + +

+ +


+ + +6.2.1390 EXPECT + + +
+CORE EXT +
+
+	( c-addr +n -- )
+
+ +

+ +Receive a string of at most +n characters. Display graphic characters +as they are received. A program that depends on the presence or absence +of non-graphic characters in the string has an environmental dependency. +The editing functions, if any, that the system performs in order to +construct the string of characters are implementation-defined. + +

+ +Input terminates when an implementation-defined line terminator is +received or when the string is +n characters long. When input +terminates, nothing is appended to the string and the display is +maintained in an implementation-defined way. + +

+ +Store the +string at c-addr and its length in +SPAN. + +

+ +Note: This word is obsolescent and is included as a concession to +existing implementations. Its function is superseded by +6.1.0695 +ACCEPT. + + +

+ +See: +A.6.2.1390 EXPECT + +

+ +


+ + +6.2.1485 FALSE + + +
+CORE EXT +
+
+	( -- false )
+
+ +

+ +Return a +false flag. + +

+ + +See: +3.1.3.1 Flags + + +

+ +


+ + +6.2.1660 HEX + + +
+CORE EXT +
+
+	( -- )
+
+ +

+ +Set contents +of +BASE +to sixteen. + + +

+ +


+ + +6.2.1850 MARKER + + +
+CORE EXT +
+
+	( "<spaces>name" -- )
+
+ +

+ +Skip leading space delimiters. Parse name delimited by a space. Create +a definition for name with the execution semantics defined below. + +

+

+	name Execution: ( -- )
+
+

+ +Restore all dictionary allocation and search order pointers to the state +they had just prior to the definition of name. Remove the definition of +name and all subsequent definitions. Restoration of any structures +still existing that could refer to deleted definitions or deallocated +data space is not necessarily provided. No other contextual information +such as numeric base is affected. + +

+ + +See: +3.4.1 Parsing, +15.6.2.1580 FORGET , +A.6.2.1850 MARKER + + + +

+ +


+ + +6.2.1930 NIP + + +
+CORE EXT +
+
+	( x1 x2 -- x2 )
+
+ +

+ +Drop the +first item below the top of stack. + + +

+ +


+ + +6.2.1950 OF + + +
+CORE EXT +
+ +

+

+	Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( C: -- of-sys )
+
+

+ +Put of-sys onto the control flow stack. Append the run-time semantics +given below to the current definition. The semantics are incomplete +until resolved by a consumer of of-sys such as +ENDOF. + +

+

+	Run-time: ( x1 x2 --   | x1 )
+
+

+ +If the two values on the stack are not equal, discard the top value and +continue execution at the location specified by the consumer of of-sys, +e.g., following the next ENDOF. Otherwise, discard both values and +continue execution in line. + +

+ + +See: +6.2.0873 CASE , +6.2.1342 ENDCASE , +A.6.2.1950 OF + + +

+ +


+ + +6.2.2000 PAD + + +
+CORE EXT +
+
+	( -- c-addr )
+
+ +

+ +c-addr is the address of a transient region that can be used to hold +data for intermediate processing. + +

+ + +See: +3.3.3.6 Other transient regions, +A.6.2.2000 PAD + + +

+ +


+ + +6.2.2008 PARSE + + +
+CORE EXT +
+
+	( char "ccc<char>" -- c-addr u )
+
+ +

+ +Parse ccc +delimited by the delimiter char. + +

+ +c-addr is the address (within the input buffer) and u is the length of +the parsed string. If the parse area was empty, the resulting string +has a zero length. + +

+ + +See: +3.4.1 Parsing, +A.6.2.2008 PARSE + + + +

+ +


+ + +6.2.2030 PICK + + +
+CORE EXT +
+
+	( xu ... x1 x0 u -- xu ... x1 x0 xu )
+
+ +

+ +Remove u. +Copy the xu to the top of the stack. An ambiguous condition exists +if there are less than u+2 items on the stack before PICK is executed. + +

+ +See: +A.6.2.2030 PICK + +

+ +


+ + +6.2.2040 QUERY + + +
+CORE EXT +
+
+	( -- )
+
+ +

+ +Make the user input device the input source. Receive input into the +terminal input buffer, replacing any previous contents. Make the +result, whose address is returned by +TIB, +the input buffer. Set +>IN +to zero. + +

+ +Note: This word is obsolescent and is included as a concession to +existing implementations. + +

+ +See: +A.6.2.2040 QUERY , +RFI 0006. + +

+ +


+ + +6.2.2125 REFILL + + +
+CORE EXT +
+
+	( -- flag )
+
+ +

+ +Attempt to fill the input buffer from the input source, returning a true +flag if successful. + +

+ +When the input source is the user input device, attempt to receive input +into the terminal input buffer. If successful, make the result the +input buffer, set +>IN +to zero, and return true. Receipt of a line +containing no characters is considered successful. If there is no input +available from the current input source, return false. + +

+ +When the input source is a string from +EVALUATE, +return false and +perform no other action. + +

+ + +See: +7.6.2.2125 REFILL , +11.6.2.2125 REFILL , +A.6.2.2125 REFILL + + +

+ +


+ + +6.2.2148 RESTORE-INPUT + + +
+CORE EXT +
+
+	( xn ... x1 n -- flag )
+
+ +

+ +Attempt to restore the input source specification to the state described +by x1 through xn. flag is true if the input source specification cannot +be so restored. + +

+ +An ambiguous condition exists if the input source represented by the +arguments is not the same as the current input source. + +

+ + +See: +A.6.2.2182 SAVE-INPUT + + +

+ +


+ + +6.2.2150 ROLL + + +
+CORE EXT +
+
+	( xu xu-1 ... x0 u -- xu-1 ... x0 xu )
+
+ +

+ +Remove u. Rotate u+1 items on the top of the stack. An ambiguous +condition exists if there are less than u+2 items on the stack before +ROLL is executed. + +

+ +See: +A.6.2.2150 ROLL + +

+ +


+ + +6.2.2182 SAVE-INPUT + + +
+CORE EXT +
+
+	( -- xn ... x1 n )
+
+ +

+ +x1 through xn describe the current state of the input source +specification for later use by +RESTORE-INPUT. + +

+ +See: +A.6.2.2182 SAVE-INPUT + +

+ +


+ + +6.2.2218 SOURCE-ID + + +
+source-i-d CORE EXT +
+
+	( -- 0 | -1 )
+
+ +

+ +Identifies the +input source as follows: + +

+ + +

+SOURCE-ID       Input source
+-1              String (via EVALUATE)
+ 0              User input device
+
+ +

+ + +See: +11.6.1.2218 SOURCE-ID + + +

+ +


+ + +6.2.2240 SPAN + + +
+CORE EXT +
+
+	( -- a-addr )
+
+ +

+ +a-addr is the address of a cell containing the count of characters +stored by the last execution of +EXPECT. + +

+ +Note: This word is obsolescent and is included as a concession to +existing implementations. + + +

+ +


+ + +6.2.2290 TIB + + +
+t-i-b CORE EXT +
+
+	( -- c-addr )
+
+ +

+ +c-addr +is the address of the terminal input buffer. + +

+ +Note: This word is obsolescent and is included as a concession to +existing implementations. + +

+ +See: +A.6.2.2290 TIB , +RFI 0006. + +

+ +


+ + +6.2.2295 TO + + +
+CORE EXT +
+ +

+ +

+	Interpretation: ( x "<spaces>name" -- )
+
+

+ +Skip leading spaces and parse name delimited by a space. Store x in +name. An ambiguous condition exists if name was not defined by +VALUE. + +

+

+	Compilation: ( "<spaces>name" -- )
+
+

+ +Skip leading spaces and parse name delimited by a space. Append the +run-time semantics given below to the current definition. An ambiguous +condition exists if name was not defined by VALUE. + +

+

+	Run-time: ( x -- )
+
+

+ +Store x +in name. + +

+ +Note: An ambiguous condition exists if either +POSTPONE or +[COMPILE] +is applied to TO. + +

+ + +See: +13.6.1.2295 TO , +A.6.2.2295 TO + + +

+ +


+ + +6.2.2298 TRUE + + +
+CORE EXT +
+
+	( -- true )
+
+ +

+ +Return a +true flag, a single-cell value with all bits set. + +

+ + +See: +3.1.3.1 Flags, +A.6.2.2298 TRUE + + +

+ +


+ + +6.2.2300 TUCK + + +
+CORE EXT +
+
+	( x1 x2 -- x2 x1 x2 )
+
+ +

+ +Copy the +first (top) stack item below the second stack item. + +

+ +


+ + +6.2.2330 U.R + + +
+u-dot-r CORE EXT +
+
+	( u n -- )
+
+ +

+ +Display u right aligned in a field n characters wide. If the number of +characters required to display u is greater than n, all digits are +displayed with no leading spaces in a field as wide as necessary. + +

+ +


+ + +6.2.2350 U> + + +
+u-greater-than CORE EXT +
+
+	( u1 u2 -- flag )
+
+ +

+ +flag is +true if and only if u1 is greater than u2. + +

+ + +See: +6.1.0540 > + + +

+ +


+ + +6.2.2395 UNUSED + + +
+CORE EXT +
+
+	( -- u )
+
+ +

+ +u is +the amount of space remaining in the region addressed by +HERE , in +address units. + +

+ +


+ + +6.2.2405 VALUE + + +
+CORE EXT +
+
+	( x "<spaces>name" -- )
+
+ +

+ +Skip leading +space delimiters. Parse name delimited by a space. Create a +definition for name with the execution semantics defined below, with an +initial value equal to x. + +

+ +name is +referred to as a value. + +

+

+	name Execution: ( -- x )
+
+

+ +Place x on the stack. The value of x is that given when name +was created, +until the phrase x TO name +is executed, causing a new value of x to be +associated with name. + +

+ + +See: +3.4.1 Parsing, +A.6.2.2405 VALUE , +6.2.2295 TO + + +

+ +


+ + +6.2.2440 WITHIN + + +
+CORE EXT +
+
+	( n1|u1 n2|u2 n3|u3 -- flag )
+
+ +

+ +Perform a comparison of a test value n1|u1 with a lower limit n2|u2 and +an upper limit n3|u3, returning true if either (n2|u2 < n3|u3 and +(n2|u2 <= n1|u1 and n1|u1 < n3|u3)) or (n2|u2 > n3|u3 and +(n2|u2 <= n1|u1 or n1|u1 < n3|u3)) is true, returning false +otherwise. An ambiguous condition exists if n1|u1, n2|u2, and n3|u3 are +not all the same type. + +

+ +See: +A.6.2.2440 WITHIN + +

+ +


+ + +6.2.2530 [COMPILE] + + +
+bracket-compile CORE EXT +
+ +

+

+	Intrepretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( "<spaces>name" -- )
+
+

+ +Skip leading space delimiters. Parse name delimited by a space. Find +name. If name has other than default compilation semantics, append them +to the current definition; otherwise append the execution semantics of +name. An ambiguous condition exists if name is not found. + +

+ + +See: +3.4.1 Parsing, +6.1.2033 POSTPONE , +A.6.2.2530 [COMPILE] + + +

+ +


+ + +6.2.2535 \ + + +
+backslash CORE EXT +
+ +

+

+	Compilation: Perform the execution semantics given below.
+
+

+

+	Execution: ( "ccc<eol>"-- )
+
+

+ +Parse and discard +the remainder of the parse area. \ is an immediate word. + +

+ + +See: +7.6.2.2535 \ , +A.6.2.2535 \ + + +

+ + +


+ Table of Contents +
+ +Next Section +

+ + + diff --git a/docs/reference/standards/ans94/dpans7.htm b/docs/reference/standards/ans94/dpans7.htm new file mode 100644 index 00000000..54f8b0f1 --- /dev/null +++ b/docs/reference/standards/ans94/dpans7.htm @@ -0,0 +1,764 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

7. The optional Block word set

+ + +See: +A.7 The optional Block word set + + +
+ +

7.1 Introduction

+
+ + +
+ +

7.2 Additional terms

+
+ +
block:
1024 characters of data on mass +storage, designated by a block number. +
block buffer:
A block-sized region of data space where a block +is +made temporarily available for use. The current block buffer is the +block buffer most recently accessed by +BLOCK, +BUFFER, +LOAD, +LIST, or +THRU. +
+ +

+ +See: +A.7.2 Additional terms + + +


+ +

7.3 Additional usage requirements

+
+ + +
+ +

7.3.1 Environmental queries

+
+ +Append table 7.1 +to table 3.5. +

+ +See: +3.2.6 Environmental queries + +

+ +Table 7.1 - Environmental Query Strings + + +

+String          Value data type  Constant?       Meaning
+------          ---------------  ---------       -------
+BLOCK           flag             no              block word set present
+BLOCK-EXT       flag             no              block extensions word set present
+
+
+

+ +


+ +

7.3.2 Data space

+
+ +A program may access memory +within a valid block buffer. +

+ +See: +3.3.3 Data Space + + +

+ +


+ +

7.3.3 Block buffer regions

+
+ +The address of a block buffer returned by +BLOCK or +BUFFER is transient. +A call to BLOCK or BUFFER may render a previously-obtained block-buffer +address invalid, as may a call to any word that: +

+ +

    +
  • parses: +
  • displays characters on the user output device, such as +TYPE or +EMIT; +
  • controls the user output device, such as +CR or +AT-XY; +
  • receives or tests for the presence of characters from the user input +device such as +ACCEPT or +KEY; +
  • waits for a condition or event, such as +MS or +EKEY; +
  • manages the block buffers, such as +FLUSH, +SAVE-BUFFERS, or +EMPTY-BUFFERS; +
  • performs any operation on a file or file-name directory that implies +I/O, such as +REFILL or any word that returns an ior; +
  • implicitly performs I/O, such as text interpreter nesting and +un-nesting when files are being used (including un-nesting implied by +THROW). +
+

+ +If the input source is a block, these restrictions also apply to the address +returned by +SOURCE. +

+ +Block buffers are +uniquely assigned to blocks. + +

+ + +


+ +

7.3.4 Parsing

+
+ +The Block word set implements an alternative input source for the text +interpreter. When the input source is a block, +BLK shall contain the +non-zero block number and the input buffer is the 1024-character buffer +containing that block. +

+ +A block is conventionally displayed +as 16 lines of 64 characters. +

+ +A program may switch the input source to a block by using +LOAD or +THRU. +Input sources may be nested using LOAD and +EVALUATE in any order. +

+ +A program may reposition the parse area within a block by manipulating +>IN. +More extensive repositioning can be accomplished using +SAVE-INPUT +and +RESTORE-INPUT. +

+ +See: +3.4.1 Parsing + +

+ + +


+ +

7.3.5 Possible action on an ambiguous condition

+
+

+

    +
  • A system with the Block word set may set interpretation state and interpret +a block. +
+ + +See: +3.4.4 Possible action on an ambiguous +condition + +

+ +


+ +

7.4 Additional documentation requirements

+
+ + +
+ +

7.4.1 System documentation

+
+ + +
+ +

7.4.1.1 Implementation-defined options

+
+ +
    +
  • the format used for display by +7.6.2.1770 LIST (if implemented); +
  • the length of a line affected by +7.6.2.2535 \ (if implemented). +
+

+ + +


+ +

7.4.1.2 Ambiguous conditions

+
+ +
    +
  • Correct block read was not possible; +
  • I/O exception in block transfer; +
  • Invalid block number +(7.6.1.0800 BLOCK, +7.6.1.0820 BUFFER, +7.6.1.1790 LOAD); +
  • A program directly alters the contents of +7.6.1.0790 BLK; +
  • No current block buffer for +7.6.1.2400 UPDATE. +
+ +

+ + +


+ +

7.4.1.3 Other system documentation

+
+ +
    +
  • any restrictions a multiprogramming system places on the use of buffer +addresses; +
  • the number of blocks available for source text and data. +
+

+ + +


+ +

7.4.2 Program documentation

+
+ +
    +
  • the number of blocks required by the program. +
+

+ + +


+ +

7.5 Compliance and labeling

+
+ + +
+ +

7.5.1 ANS Forth systems

+
+ +The phrase Providing the Block word set shall be appended to the +label of any Standard System that provides all of the Block word set. +

+ +The phrase Providing name(s) from the Block Extensions word set +shall be appended to the label of any Standard System that provides +portions of the Block Extensions word set. +

+ +The phrase Providing the Block Extensions word set shall be +appended to the label of any Standard System that provides all of the +Block and Block Extensions word sets. +

+ + +


+ +

7.5.2 ANS Forth programs

+
+ +The phrase Requiring the Block word set shall be appended to the +label of Standard Programs that require the system to provide the Block +word set. +

+ +The phrase Requiring name(s) from the Block Extensions word set +shall be appended to the label of Standard Programs that require the +system to provide portions of the Block Extensions word set. +

+ +The phrase Requiring the Block Extensions word set shall be +appended to the label of Standard Programs that require the system to +provide all of the Block and Block Extensions word sets. +

+ + +


+ +

7.6 Glossary

+
+ + +
+ +

7.6.1 Block words

+
+ + +
+ + +7.6.1.0790 BLK + + +
+b-l-k BLOCK +
+
+	( -- a-addr )
+
+ +

+ +a-addr is the address of a cell containing zero or the number of the +mass-storage block being interpreted. If BLK contains zero, the input +source is not a block and can be identified by +SOURCE-ID, if SOURCE-ID +is available. An ambiguous condition exists if a program directly +alters the contents of BLK. + +

+ +See: +7.3.3 Block buffer regions + +

+ +


+ + +7.6.1.0800 BLOCK + + +
+BLOCK +
+
+	( u -- a-addr )
+
+ +

+ +a-addr is the address of the first character of the block buffer assigned to +mass-storage block u. An ambiguous condition exists if u is not an available +block number. +

+ +If block u is already in a block buffer, a-addr is the address of that block +buffer. +

+ +If block u is not already in memory and there is an unassigned block buffer, +transfer block u from mass storage to an unassigned block buffer. a-addr is +the address of that block buffer. +

+ +If block u is not already in memory and there are no unassigned block buffers, +unassign a block buffer. If the block in that buffer has been +UPDATEd, +transfer the block to mass storage and transfer block u from mass storage into +that buffer. a-addr is the address of that block buffer. +

+ +At the conclusion of the operation, the block buffer pointed to by a-addr is +the current block buffer and is assigned to u. + +

+ +


+ + +7.6.1.0820 BUFFER + + +
+BLOCK +
+
+	( u -- a-addr )
+
+ +

+ +a-addr is the address of the first character of the block buffer +assigned to block u. The contents of the block are unspecified. An +ambiguous condition exists if u is not an available block number. +

+ +If block u is already in a block buffer, a-addr is the address of that +block buffer. +

+ +If block u is not already in memory and there is an unassigned buffer, +a-addr is the address of that block buffer. +

+ +If block u is not already in memory and there are no unassigned block +buffers, unassign a block buffer. If the block in that buffer has been +UPDATEd, +transfer the block to mass storage. a-addr is the address of +that block buffer. +

+ +At the conclusion of the operation, the block buffer pointed to by +a-addr is the current block buffer and is assigned to u. +

+ + +See: +7.6.1.0800 BLOCK + + +

+ +


+ + +7.6.1.1360E EVALUATE + + +
+BLOCK +
+

+ +Extend the semantics of +6.1.1360 EVALUATE to include: +

+ + Store zero in BLK. + +

+ +


+ + +7.6.1.1559 FLUSH + + +
+BLOCK +
+
+	( -- )
+
+ +

+ +Perform the function of +SAVE-BUFFERS, +then unassign all block buffers. + +

+ +


+ + +7.6.1.1790 LOAD + + +
+BLOCK +
+
+	( i*x u -- j*x )
+
+ +

+ +Save the current input-source specification. Store u in +BLK (thus +making block u the input source and setting the input buffer to +encompass its contents), set +>IN +to zero, and interpret. When the parse +area is exhausted, restore the prior input source specification. Other +stack effects are due to the words LOADed. +

+ +An ambiguous condition exists if u is zero or is not a valid block +number. +

+ + +See: +3.4 The Forth text interpreter + + +

+ +


+ + +7.6.1.2180 SAVE-BUFFERS + + +
+BLOCK +
+
+	( -- )
+
+ +

+ +Transfer the contents of each +UPDATEd block buffer to mass storage. +Mark all buffers as unmodified. + +

+ +


+ + +7.6.1.2400 UPDATE + + +
+BLOCK +
+
+	( -- )
+
+ +

+ +Mark the current block buffer as modified. An ambiguous condition +exists if there is no current block buffer. +

+ +UPDATE does not immediately cause I/O. +

+ + +See: +7.6.1.0800 BLOCK , +7.6.1.0820 BUFFER , +7.6.1.1559 FLUSH , +7.6.1.2180 SAVE-BUFFERS + + +

+ +


+ +

7.6.2 Block extension words

+
+ +
+ + +7.6.2.1330 EMPTY-BUFFERS + + +
+BLOCK EXT +
+
+	( -- )
+
+ +

+ +Unassign all block buffers. Do not transfer the contents of any +UPDATEd +block buffer to mass storage. +

+ + +See: +7.6.1.0800 BLOCK + + +

+ +


+ + +7.6.2.1770 LIST + + +
+BLOCK EXT +
+
+	( u -- )
+
+ +

+ +Display block u in an +implementation-defined format. Store u in +SCR. +

+ + +See: +7.6.1.0800 BLOCK + + +

+ +


+ + +7.6.2.2125 REFILL + + +
+BLOCK EXT +
+
+	( -- flag )
+
+ +

+ +Extend the execution semantics of +6.2.2125 REFILL with the following: +

+ +When the input source is a block, make the next block the input source +and current input buffer by adding one to the value of +BLK and setting +>IN to zero. Return true if the new value of BLK is a valid block +number, otherwise false. +

+ + +See: +11.6.2.2125 REFILL + + +

+ +


+ + +7.6.2.2190 SCR + + +
+s-c-r BLOCK EXT +
+
+	( -- a-addr )
+
+ +

+ +a-addr is the address of a cell containing the block number of the block +most recently +LISTed. + +

+ +See: +A.7.6.2.2190 SCR + +

+ +


+ + +7.6.2.2280 THRU + + +
+BLOCK EXT +
+
+	( i*x u1 u2 -- j*x )
+
+ +

+ +LOAD +the mass storage blocks numbered u1 through u2 in sequence. Other +stack effects are due to the words LOADed. + +

+ +


+ + +7.6.2.2535 \ + + +
+backslash BLOCK EXT +
+

+ +Extend the semantics of +6.2.2535 \ to be: +

+

+        Compilation: Perform the execution semantics given below.
+
+

+

+        Execution: ( ccc<eol>-- )
+
+

+ +If +BLK +contains zero, parse and discard the remainder of the parse area; +otherwise parse and discard the portion of the parse area corresponding +to the remainder of the current line. \ is an immediate word. + + +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpans8.htm b/docs/reference/standards/ans94/dpans8.htm new file mode 100644 index 00000000..6076ba34 --- /dev/null +++ b/docs/reference/standards/ans94/dpans8.htm @@ -0,0 +1,783 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

8. The optional Double-Number word set

+ +

+ +See: +A.8 The optional Double-Number word set + + +


+ +

8.1 Introduction

+
+ +Sixteen-bit Forth systems often use double-length numbers. However, +many Forths on small embedded systems do not, and many users of Forth on +systems with a cell size of 32 bits or more find that the use of +double-length numbers is much diminished. Therefore, the words that +manipulate double-length entities have been placed in this optional word +set. + +

+ +


+ +

8.2 Additional terms and notation

+
+ +None. + +

+ +


+ +

8.3 Additional usage requirements

+
+ + +
+ +

8.3.1 Environmental queries

+
+ +Append table 8.1 +to table 3.5. +

+ + +See: +3.2.6 Environmental queries + + +

+ +Table 8.1 - Environmental Query Strings +

+ + +

+String         Value data type   Constant?   Meaning
+------         ---------------   ---------   -------
+DOUBLE          flag             no          double-number word set present
+DOUBLE-EXT      flag             no          double-number extensions word set present
+
+ +

+ + +


+ +

8.3.2 Text interpreter input number conversion

+
+ +When the text interpreter processes a number that is immediately +followed by a decimal point and is not found as a definition name, the +text interpreter shall convert it to a double-cell number. +

+ +For example, entering DECIMAL 1234 leaves the single-cell number 1234 on +the stack, and entering DECIMAL 1234. leaves the double-cell number +1234 0 on the stack. +

+ + +See: +3.4.1.3 Text interpreter input number +conversion, +RFI 0004 Number Conversion. + + +

+ +


+ +

8.4 Additional documentation requirements

+
+ + +
+ +

8.4.1 System documentation

+
+ + +
+ +

8.4.1.1 Implementation-defined options

+
+ +
    +
  • no additional requirements. +
+

+ +


+ +

8.4.1.2 Ambiguous conditions

+
+ + +

+ +


+ +

8.4.1.3 Other system documentation

+
+ +
    +
  • no additional requirements. +
+

+ + +


+ +

8.4.2 Program documentation

+
+ +
    +
  • no additional requirements. +
+

+ + +


+ +

8.5 Compliance and labeling

+
+ + +
+ +

8.5.1 ANS Forth systems

+
+ +The phrase Providing the Double-Number word set shall be appended +to the label of any Standard System that provides all of the +Double-Number word set. +

+ +The phrase Providing name(s) from the Double-Number Extensions word +set shall be appended to the label of any Standard System that +provides portions of the Double-Number Extensions word set. +

+ +The phrase Providing the Double-Number Extensions word set shall +be appended to the label of any Standard System that provides all of the +Double-Number and Double-Number Extensions word sets. + +

+ + +


+ +

8.5.2 ANS Forth programs

+
+ +The phrase Requiring the Double-Number word set shall be appended +to the label of Standard Programs that require the system to provide the +Double-Number word set. +

+ +The phrase Requiring name(s) from the Double-Number Extensions word +set shall be appended to the label of Standard Programs that require +the system to provide portions of the Double-Number Extensions word set. +

+ +The phrase Requiring the Double-Number Extensions word set shall +be appended to the label of Standard Programs that require the system to +provide all of the Double-Number and Double-Number Extensions word sets. + +

+ + +


+ +

8.6 Glossary

+
+ + +
+ +

8.6.1 Double-Number words

+
+ + + +
+ + +8.6.1.0360 2CONSTANT + + +
+two-constant DOUBLE +
+
+	( x1 x2 "<spaces>name" -- )
+
+

+ +Skip leading space delimiters. Parse name delimited by a space. Create +a definition for name with the execution semantics defined below. +

+ +name is referred to +as a two-constant. +

+

+        name Execution: ( -- x1 x2 )
+
+

+ +Place cell +pair x1 x2 on the stack. +

+ + +See: +3.4.1 Parsing, +A.8.6.1.0360 2CONSTANT + + +

+ +


+ + +8.6.1.0390 2LITERAL + + +
+ two-literal DOUBLE +
+

+

+        Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+	Compilation: ( x1 x2 -- )
+
+

+ +Append the run-time semantics +below to the current definition. +

+

+        Run-time: ( -- x1 x2 )
+
+

+ +Place cell pair +x1 x2 on the stack. + +

+ +See: +A.8.6.1.0390 2LITERAL + + +

+ +


+ + +8.6.1.0440 2VARIABLE + + +
+two-variable DOUBLE +
+
+	( "<spaces>name" -- )
+
+ +

+ +Skip leading space delimiters. Parse name delimited by a space. Create +a definition for name with the execution semantics defined below. +Reserve two consecutive cells of data space. +

+ +name is referred to +as a two-variable. +

+

+        name Execution: ( -- a-addr )
+
+

+ +a-addr is the address of the first (lowest address) cell of two +consecutive cells in data space reserved by 2VARIABLE when it defined +name. A program is responsible for initializing the contents. +

+ + +See: +3.4.1 Parsing, +6.1.2410 VARIABLE , +A.8.6.1.0440 2VARIABLE + + + +

+ +


+ + +8.6.1.1040 D+ + + +
+d-plus DOUBLE +
+
+	( d1|ud1 d2|ud2 -- d3|ud3 )
+
+ +

+ +Add d2|ud2 to d1|ud1, +giving the sum d3|ud3. + +

+ +


+ + +8.6.1.1050 D- + + +
+d-minus DOUBLE +
+
+	( d1|ud1 d2|ud2 -- d3|ud3 )
+
+ +

+ +Subtract d2|ud2 from d1|ud1, +giving the difference d3|ud3. + +

+ +


+ + +8.6.1.1060 D. + + +
+d-dot DOUBLE +
+
+	( d -- )
+
+ +

+ +Display d in +free field format. + +

+ +


+ + +8.6.1.1070 D.R + + +
+d-dot-r DOUBLE +
+
+	( d n -- )
+
+ +

+ +Display d right aligned in a field n characters wide. If the number of +characters required to display d is greater than n, all digits are +displayed with no leading spaces in a field as wide as necessary. + +

+ +See: +A.8.6.1.1070 D.R + + +

+ +


+ + +8.6.1.1075 D0< + + +
+d-zero-less DOUBLE +
+
+	( d -- flag )
+
+ +

+ +flag is true if and +only if d is less than zero. + +

+ +


+ + +8.6.1.1080 D0= + + +
+d-zero-equals DOUBLE +
+
+	( xd -- flag )
+
+ +

+ +flag is true if and +only if xd is equal to zero. + +

+ +


+ + +8.6.1.1090 D2* + + +
+d-two-star DOUBLE +
+
+	( xd1 -- xd2 )
+
+ +

+ +xd2 is the result of shifting xd1 one bit toward the most-significant bit, +filling the vacated least-significant bit with zero. + + +

+ +See: +A.8.6.1.1090 D2* + + +

+ +


+ + +8.6.1.1100 D2/ + + +
+d-two-slash DOUBLE +
+
+	( xd1 -- xd2 )
+
+ +

+ +xd2 is the result of shifting xd1 one bit toward the least-significant bit, +leaving the most-significant bit unchanged. + +

+ +See: +A.8.6.1.1100 D2/ + + +

+ +


+ + +8.6.1.1110 D< + + +
+d-less-than DOUBLE +
+
+	( d1 d2 -- flag )
+
+ +

+ +flag is true if and only +if d1 is less than d2. + +

+ +


+ + +8.6.1.1120 D= + + +
+d-equals DOUBLE +
+
+	( xd1 xd2 -- flag )
+
+ +

+ +flag is true if and only if xd1 +is bit-for-bit the same as xd2. + +

+ +


+ + +8.6.1.1140 D>S + + +
+d-to-s DOUBLE +
+
+	( d -- n )
+
+ +

+ +n is the equivalent of d. An ambiguous condition exists if d lies +outside the range of a signed single-cell number. + + +

+ +See: +A.8.6.1.1140 D>S + + +

+ +


+ + +8.6.1.1160 DABS + + +
+d-abs DOUBLE +
+
+	( d -- ud )
+
+ +

+ +ud is the +absolute value of d. + +

+ +


+ + +8.6.1.1210 DMAX + + +
+d-max DOUBLE +
+
+	( d1 d2 -- d3 )
+
+ +

+ +d3 is the +greater of d1 and d2. + +

+ +


+ + +8.6.1.1220 DMIN + + +
+d-min DOUBLE +
+
+	( d1 d2 -- d3 )
+
+ +

+ +d3 is the +lesser of d1 and d2. + +

+ +


+ + +8.6.1.1230 DNEGATE + + +
+d-negate DOUBLE +
+
+	( d1 -- d2 )
+
+ +

+ +d2 is +the negation of d1. + +

+ +


+ + +8.6.1.1820 M*/ + + +
+m-star-slash DOUBLE +
+
+	( d1 n1 +n2 -- d2 )
+
+ +

+ +Multiply d1 by n1 producing the triple-cell intermediate result t. +Divide t by +n2 giving the double-cell quotient d2. An ambiguous +condition exists if +n2 is zero or negative, or the quotient lies +outside of the range of a double-precision signed integer. + +

+ +See: +A.8.6.1.1820 M*/ + + +

+ +


+ + +8.6.1.1830 M+ + + +
+m-plus DOUBLE +
+
+	( d1|ud1 n -- d2|ud2 )
+
+ +

+ +Add n to d1|ud1, +giving the sum d2|ud2. + +

+ +See: +A.8.6.1.1830 M+ + + +

+ +


+ +

8.6.2 Double-Number extension words

+
+ +
+ + +8.6.2.0420 2ROT + + +
+two-rote DOUBLE EXT +
+	( x1 x2 x3 x4 x5 x6 -- x3 x4 x5 x6 x1 x2 )
+
+ +

+ +Rotate the top three cell pairs on the stack bringing cell pair x1 x2 to +the top of the stack. + +

+ +


+ + +8.6.2.1270 DU< + + +
+d-u-less DOUBLE EXT +
+
+	( ud1 ud2 -- flag )
+
+

+ +flag is true if +and only if ud1 is less than ud2. + + + +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpans9.htm b/docs/reference/standards/ans94/dpans9.htm new file mode 100644 index 00000000..a2234664 --- /dev/null +++ b/docs/reference/standards/ans94/dpans9.htm @@ -0,0 +1,553 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

9. The optional Exception word set

+ + +

+ +See: +A.9 The optional Exception word set + +

+ + +


+ +

9.1 Introduction

+
+ + +
+ +

9.2 Additional terms and notation

+
+ +None. + + +
+ +

9.3 Additional usage requirements

+
+ +

+ +See: +A.9.3 Additional usage requirements + +

+ +


+ +

9.3.1 THROW values

+
+ +The +THROW +values {-255...-1} shall be used only as assigned by this +Standard. The values {-4095...-256} shall be used only as assigned by a +system. +

+ +If the +File-Access or +Memory-Allocation word sets are implemented, it is +recommended that the non-zero values of ior lie within the range of +system THROW values, as defined above. In an operating-system +environment, this can sometimes be accomplished by biasing the +range of operating-system exception-codes to fall within the THROW +range. +

+ +Programs shall not define values for use with THROW in the range +{-4095...-1}. + +

+ +


+ +

9.3.2 Exception frame

+
+ +An exception frame is the implementation-dependent set of information +recording the current execution state necessary for the proper +functioning of +CATCH and +THROW. It often includes the depths of the +data stack and return stack. +

+ + +


+ +

9.3.3 Exception stack

+
+ +A stack used for the nesting of exception frames by +CATCH and +THROW. It +may be, but need not be, implemented using the return stack. +

+ + +


+ +

9.3.4 Environmental queries

+
+ +Append table 9.1 +to table 3.5. +

+ + +See: +3.2.6 Environmental queries + +

+ +Table 9.1 - Environmental query strings +

+ + +

+String          Value data type  Constant?   Meaning
+------          ---------------  ---------   -------
+EXCEPTION       flag             no          Exception word set present
+EXCEPTION-EXT   flag             no          Exception extensions word set present
+
+
+ +

+ +


+ +

9.3.5 Possible actions on an ambiguous condition

+
+ +A system choosing to execute +THROW when detecting one of the ambiguous +conditions listed in table 9.3.6 shall use the throw code listed there. +

+ + +See: +3.4.4 Possible actions on an ambiguous +condition + + +

+ +Table 9.2 - THROW code assignments +

+ + +

+       Code     Reserved for
+       ----     ------------
+        -1      ABORT
+        -2      ABORT"
+        -3      stack overflow
+        -4      stack underflow
+        -5      return stack overflow
+        -6      return stack underflow
+        -7      do-loops nested too deeply during execution
+        -8      dictionary overflow
+        -9      invalid memory address
+        -10     division by zero
+        -11     result out of range
+        -12     argument type mismatch
+        -13     undefined word
+        -14     interpreting a compile-only word
+        -15     invalid FORGET
+        -16     attempt to use zero-length string as a name
+        -17     pictured numeric output string overflow
+        -18     parsed string overflow
+        -19     definition name too long
+        -20     write to a read-only location
+        -21     unsupported operation (e.g., AT-XY on a
+                too-dumb terminal)
+        -22     control structure mismatch
+        -23     address alignment exception
+        -24     invalid numeric argument
+        -25     return stack imbalance
+        -26     loop parameters unavailable
+        -27     invalid recursion
+        -28     user interrupt
+        -29     compiler nesting
+        -30     obsolescent feature
+        -31     >BODY used on non-CREATEd definition
+        -32     invalid name argument (e.g., TO xxx)
+        -33     block read exception
+        -34     block write exception
+        -35     invalid block number
+        -36     invalid file position
+        -37     file I/O exception
+        -38     non-existent file
+        -39     unexpected end of file
+        -40     invalid BASE for floating point conversion
+        -41     loss of precision
+        -42     floating-point divide by zero
+        -43     floating-point result out of range
+        -44     floating-point stack overflow
+        -45     floating-point stack underflow
+        -46     floating-point invalid argument
+        -47     compilation word list deleted
+        -48     invalid POSTPONE
+        -49     search-order overflow
+        -50     search-order underflow
+        -51     compilation word list changed
+        -52     control-flow stack overflow
+        -53     exception stack overflow
+        -54     floating-point underflow
+        -55     floating-point unidentified fault
+        -56     QUIT
+        -57     exception in sending or receiving a character
+        -58     [IF], [ELSE], or [THEN] exception
+
+ +

+ +


+ +

9.3.6 Exception handling

+
+ +There are several methods of coupling +CATCH and +THROW to other +procedural nestings. The usual nestings are the execution of +definitions, use of the return stack, use of loops, instantiation of +locals and nesting of input sources (i.e., with +LOAD, +EVALUATE, or +INCLUDE-FILE). +

+ +When a THROW returns control to a CATCH, the system shall un-nest not +only definitions, but also, if present, locals and input source +specifications, to return the system to its proper state for continued +execution past the CATCH. +

+ +See: +A.9.3.6 Exception handling + +

+ + +


+ +

9.4 Additional documentation requirements

+
+ + + +
+ +

9.4.1 System documentation

+
+ + + +
+ +

9.4.1.1 Implementation-defined options

+
+ + +

+ + +


+ +

9.4.1.2 Ambiguous conditions

+
+ +
    +
  • no additional requirements. +
+

+ + +


+ +

9.4.1.3 Other system documentation

+
+ +
    +
  • no additional requirements. +
+ +

+ + +


+ +

9.4.2 Program documentation

+
+ +
    +
  • no additional requirements. +
+ + +
+ +

9.5 Compliance and labeling

+
+ + + +
+ +

9.5.1 ANS Forth systems

+
+ +The phrase Providing the Exception word set shall be appended to +the label of any Standard System that provides all of the Exception word +set. +

+ +The phrase Providing name(s) from the Exception Extensions word +set shall be appended to the label of any Standard System that +provides portions of the Exception Extensions word set. +

+ +The phrase Providing the Exception Extensions word set shall be +appended to the label of any Standard System that provides all of the +Exception and Exception Extensions word sets. +

+ + + +


+ +

9.5.2 ANS Forth programs

+
+ +The phrase Requiring the Exception word set shall be appended to +the label of Standard Programs that require the system to provide the +Exception word set. +

+ +The phrase Requiring name(s) from the Exception Extensions word +set shall be appended to the label of Standard Programs that require +the system to provide portions of the Exception Extensions word set. +

+ +The phrase Requiring the Exception Extensions word set shall be +appended to the label of Standard Programs that require the system to +provide all of the Exception and Exception Extensions word sets. + +

+ + +


+ +

9.6 Glossary

+
+ + +
+ +

9.6.1 Exception words

+
+ + + +
+ + +9.6.1.0875 CATCH + + +
+EXCEPTION +
+
+	( i*x xt -- j*x 0 | i*x n )
+
+

+ +Push an exception frame on the exception stack and then execute the +execution token xt (as with +EXECUTE) +in such a way that control can be +transferred to a point just after CATCH if +THROW is executed during the +execution of xt. +

+ +If the execution of xt completes normally (i.e., the exception frame +pushed by this CATCH is not popped by an execution of THROW) pop the +exception frame and return zero on top of the data stack, above whatever +stack items would have been returned by xt EXECUTE. Otherwise, the +remainder of the execution semantics are given by THROW. + +

+ +


+ + +9.6.1.2275 THROW + + +
+EXCEPTION +
+
+	( k*x n -- k*x | i*x n )
+
+

+ +If any bits of n are non-zero, pop the topmost exception frame from the +exception stack, along with everything on the return stack above that +frame. Then restore the input source specification in use before the +corresponding +CATCH +and adjust the depths of all stacks defined by this +Standard so that they are the same as the depths saved in the exception +frame (i is the same number as the i in the input arguments to the +corresponding CATCH), put n on top of the data stack, and transfer +control to a point just after the CATCH that pushed that exception +frame. +

+ +If the top of the stack is non zero and there is no exception frame on +the exception stack, the behavior is as follows: +

+ +If n is minus-one (-1), perform the function of +6.1.0670 ABORT (the +version of ABORT in the Core word set), displaying no message. +

+ +If n is minus-two, perform the function of +6.1.0680 ABORT" (the version +of ABORT" in the Core word set), displaying the characters ccc +associated with the ABORT" that generated the THROW. +

+ +Otherwise, the system may display an implementation-dependent message +giving information about the condition associated with the THROW code n. +Subsequently, the system shall perform the function of +6.1.0670 ABORT +(the version of ABORT in the Core word set). +

+ +

+ +See: +A.9.6.1.2275 THROW + +

+ +


+ +

9.6.2 Exception extension words

+
+ +
+ + +9.6.2.0670 ABORT + + +
+EXCEPTION EXT +

+ +Extend the semantics of +6.1.0670 ABORT to be: +

+ +

+	( i*x -- ) ( R: j*x -- )
+
+

+ +Perform the function of -1 +THROW . +

+ + +


+ + +9.6.2.0680 ABORT" + + +
+abort-quote EXCEPTION EXT +

+Extend the semantics of +6.1.0680 ABORT" to be: +

+

+        Interpretation: Interpretation semantics for this word are undefined.
+
+

+

+        Compilation: ( "ccc<quote>" -- )
+
+

+ +Parse ccc delimited by a " (double-quote). Append the run-time semantics +given below to the current definition. +

+ +

+        Run-time:       ( i*x x1 --  | i*x ) ( R: j*x --  | j*x )
+
+

+ +Remove x1 from the stack. If any bit of x1 is not zero, perform the function +of -2 +THROW, +displaying ccc if there is no exception frame on the exception +stack. +

+ + +See: +3.4.1 Parsing + +

+ + +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansa1.htm b/docs/reference/standards/ans94/dpansa1.htm new file mode 100644 index 00000000..0d731c27 --- /dev/null +++ b/docs/reference/standards/ans94/dpansa1.htm @@ -0,0 +1,234 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

A. Rationale (informative annex)

+ + +
+ +

A.1 Introduction

+
+ +
+ +

A.1.1 Purpose

+ + + +
+ +

A.1.2 Scope

+
+ +This Standard is more extensive than previous industry standards for the Forth +language. Several things made this necessary: + +
    +
  • the desire to resolve conflicts between previous standards; +
  • the need to eliminate semantic ambiguities and other inadequacies; +
  • the requirement to standardize common practice, where possible +resolving divergences in a way that minimizes the cost of compliance; +
  • the desire to standardize common system techniques, including those +germane to hardware. +
+

+ +The result of the effort to satisfy all of these objectives is a +Standard arranged so that the required word set remains small. Thus ANS +Forth can be provided for resource-constrained embedded systems. Words +beyond those in the required word set are organized into a number of +optional word sets and their extensions, enabling implementation of +tailored systems that are Standard. + +

+ +When judging relative merits, the members of the X3J14 Technical +Committee were guided by the following goals (listed in alphabetic +order): + +

+ +

+
Consistency +
The Standard provides a functionally complete +set of words +with minimal functional overlap. + +
Cost of compliance +
This goal includes such issues as common +practice, how +much existing code would be broken by the proposed change, and the amount of +effort required to bring existing applications and systems into conformity +with the Standard. + +
Efficiency +
Execution speed, memory compactness. + +
Portability +
Words chosen for inclusion should be free of +system-dependent +features. + +
Readability +
Forth definition names should clearly delineate +their +behavior. That behavior should have an apparent simplicity which supports +rapid understanding. Forth should be easily taught and support readily +maintained code. + +
Utility +
Be judged to have sufficiently essential functionality +and frequency +of use to be deemed suitable for inclusion.
+ + +

+ +


+ +

A.1.3 Document organization

+
+ + +
+ +

A.1.3.1 Word sets

+
+ +From the beginning, the X3J14 Technical Committee faced not only +conflicting ideas as to what real Forth is, but also conflicting +needs of the various groups within the Forth community. At one extreme +were those who pressed for a bare Forth. At the other extreme +were those who wanted a fat Forth. Many were somewhere in +between. All were convinced of the rightness of their own position and +of the wrongness of at least one of the two extremes. The committee's +composition reflected this full range of interests. + +

+ +The approach we have taken is to define a +Core word set +establishing a +greatest lower bound for required system functionality and to provide a +portfolio of optional word sets for special purposes. This simple +approach parallels the fundamental nature of Forth as an extensible +language, and thereby achieves a kind of meta-extensibility. + +

+ +With this key, high-level compromise, regardless of the actual makeup of +the individual word sets, a firm and workable framework is established +for the long term. One may or may not agree that there should be a +Locals word set, +or that the word +COMPILE, +belongs in the +Core Extensions word set. +But at least there is a mechanism whereby such +things can be included in a logical and orderly manner. + +

+ +Several implications of this scheme of optional word sets are +significant. + +

+ +First, ANS Forth systems can continue to be implemented on a greater +range of hardware than could be claimed by almost any other single +language. Since only the +Core word set is required, very limited +hardware will be able to accommodate an ANS Forth implementation. + +

+ +Second, a greater degree of portability of applications, and of +programmers, is anticipated. The optional word sets standardize various +functions (e.g., floating point) that were widely implemented before, +but not with uniform definition names and methodologies, nor the same +levels of completeness. With such words now standardized in the +optional word sets, communications between programmers - verbally, via +magazine or journal articles, etc. - will leap to a new level of +facility, and the shareability of code and applications should rise +dramatically. + +

+ +Third, ANS Forth systems may be designed to offer the user the power to +selectively, even dynamically, include or exclude one or more of the +optional word sets or portions thereof. Also, lower-priced products may +be offered for the user who needs the Core word set and not much more. +Thus, virtually unlimited flexibility will be available to the user. + +

+ +But these advantages have a price. The burden is on the user to decide +what capabilities are desired, and to select product offerings +accordingly, especially when portability of applications is important. +We do not expect most implementors to attempt to provide all word sets, +but rather to select those most valuable to their intended markets. + +

+ +The basic requirement is that if the implementor claims to have a +particular optional word set the entire required portion of that word +set must be available. If the implementor wishes to offer only part of +an optional word set, it is acceptable to say, for example, This +system offers portions of the [named] word set, particularly if the +selected or excluded words are itemized clearly. + +

+ +Each optional word set will probably appeal to a particular +constituency. For example, scientists performing complex mathematical +analysis may place a higher value on the +Floating-Point word set +than +programmers developing simple embedded controllers. As in the case of +the core extensions, we expect implementors to offer those word sets +they expect will be valued by their users. + +

+ +Optional word sets may be offered in source form or otherwise factored +so that the user may selectively load them. + +

+ +The extensions to the optional word sets include words which are deemed +less essential to performing the primary activity supported by the word +set, though clearly relevant to it. As in the case of the Core +Extensions, implementors may selectively add itemized subsets of a word +set extension providing the labeling doesn't mislead the user into +thinking incorrectly that all words are present. + +

+ +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansa10.htm b/docs/reference/standards/ans94/dpansa10.htm new file mode 100644 index 00000000..f3dfa73f --- /dev/null +++ b/docs/reference/standards/ans94/dpansa10.htm @@ -0,0 +1,357 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

A.10 +The optional Facility word set

+ + +
+ +

A.10.6 +Glossary

+ + +
+ +A.10.6.1.0742 +AT-XY + +

+ +Most implementors supply a method of positioning a cursor on a CRT +screen, but there is great variance in names and stack arguments. This +version is supported by at least one major vendor. + +

+ +


+ +A.10.6.1.1755 +KEY? + +

+ +The Technical Committee has gone around several times on the stack +effects. Whatever is decided will violate somebody's practice and +penalize some machine. This way doesn't interfere with type-ahead on +some systems, while requiring the implementation of a single-character +buffer on machines where polling the keyboard inevitably results in the +destruction of the character. + +

+ +Use of +KEY +or KEY? indicates that the application does not wish to +bother with non-character events, so they are discarded, in anticipation +of eventually receiving a valid character. Applications wishing to +handle non-character events must use +EKEY and +EKEY?. It is possible to +mix uses of KEY? / KEY and EKEY? / EKEY within a single application, but +the application must use KEY? and KEY only when it wishes to discard +non-character events until a valid character is received. + +

+ +


+ +A.10.6.2.1305 +EKEY + +

+ +EKEY provides a standard word to access a system-dependent set of +raw keyboard events, including events corresponding to members of +the standard character set, events corresponding to other members of the +implementation-defined character set, and keystrokes that do not +correspond to members of the character set. + +

+ +EKEY assumes no particular numerical correspondence between particular +event code values and the values representing standard characters. On +some systems, this may allow two separate keys that correspond to the +same standard character to be distinguished from one another. + +

+ +In systems that combine both keyboard and mouse events into a single +event stream, the single number returned by EKEY may be +inadequate to represent the full range of input possibilities. In such +systems, a single event record may include a time stamp, the x,y +coordinates of the mouse position, the keyboard state, and the state of +the mouse buttons. In such systems, it might be appropriate for EKEY to +return the address of an event record from which the other +information could be extracted. + +

+ +Also, consider a hypothetical Forth system running under MS-DOS on a +PC-compatible computer. Assume that the implementation-defined +character set is the normal 8-bit PC character set. In that +character set, the codes from 0 to 127 correspond to ASCII characters. +The codes from 128 to 255 represent characters from various non-English +languages, mathematical symbols, and some graphical symbols used for +line drawing. In addition to those characters, the keyboard can +generate various other scan codes, representing such +non-character events as arrow keys and function keys. + +

+ +There may be multiple keys, with different scan codes, corresponding to +the same standard character. For example, the character representing +the number 1 often appears both in the row of number keys above +the alphabetic keys, and also in the separate numeric keypad. + +

+ +When a program asks the MS-DOS operating system for a keyboard event, it +receives either a single non-zero byte, representing a character, or a +zero byte followed by a scan code byte, representing a +non-character keyboard event (e.g., a function key). + +

+ +EKEY represents each keyboard event as a single number, rather than as a +sequence of numbers. For the system described above, the following +would be a reasonable implementation of EKEY and related words: + +

+ +The +MAX-CHAR +environmental query would return 255. + +

+ +Assume the existence of a word DOS-KEY ( -- char ) which executes the +MS-DOS Direct STDIN Input system call (Interrupt 21h, Function +07h) and a word DOS-KEY? ( -- flag) which executes the MS-DOS Check +STDIN Status system call (Interrupt 21h, Function 0Bh). + +

+: EKEY?  ( -- flag )  DOS-KEY?  0<>  ;
+
+: EKEY  ( -- u )  DOS-KEY  ?DUP 0= IF  DOS-KEY 256 +  THEN ;
+
+: EKEY>CHAR  ( u -- u false | char true )
+    DUP 255 > IF          ( u )
+    DUP 259 = IF           \ 259 is Ctrl-@ (ASCII NUL)
+        DROP 0 TRUE EXIT   \ so replace with character
+      THEN FALSE EXIT      \ otherwise extended character
+    THEN  TRUE             \ normal extended ASCII char.
+;
+
+VARIABLE PENDING-CHAR   -1 PENDING-CHAR !
+
+: KEY?  ( -- flag )
+    PENDING-CHAR @ 0< IF
+      BEGIN  EKEY? WHILE
+        EKEY EKEY>CHAR IF
+          PENDING-CHAR !  TRUE EXIT
+        THEN DROP
+      REPEAT  FALSE EXIT
+    THEN  TRUE
+;
+
+: KEY  ( -- char )
+    PENDING-CHAR @ 0< IF
+      BEGIN  EKEY  EKEY>CHAR 0=
+      WHILE
+        DROP
+      REPEAT  EXIT
+    THEN  PENDING-CHAR @  -1 PENDING-CHAR !
+;
+
+ +

+ +This is a full-featured implementation, providing the application +program with an easy way to either handle non-character events (with +EKEY), or to ignore them and to only consider real characters +(with +KEY). + +

+ +Note that EKEY maps scan codes from 0 to 255 into numbers from 256 to +511. EKEY maps the number 259, representing the keyboard combination +Ctrl-Shift-@, to the character whose numerical value is 0 (ASCII NUL). +Many ASCII keyboards generate ASCII NUL for Ctrl-Shift-@, so we use that +key combination for ASCII NUL (which is otherwise unavailable from +MS-DOS, because the zero byte signifies that another scan-code byte +follows). + +

+ +One consequence of using the Direct STDIN Input system call +(function 7) instead of the STDIN Input system call (function 8) +is that the normal DOS Ctrl-C interrupt behavior is disabled when +the system is waiting for input (Ctrl-C would still cause an interrupt +while characters are being output). On the other hand, if the STDIN +Input system call (function 8) were used to implement EKEY, Ctrl-C +interrupts would be enabled, but Ctrl-Shift-@ would also cause an +interrupt, because the operating system would treat the second byte of +the 0,3 sequence as a Ctrl-C, even though the 3 is really a scan code +and not a character. One best of both worlds solution is to use +function 8 for the first byte received by EKEY, and function 7 for the +scan code byte. For example: + +

+: EKEY  ( -- u )
+    DOS-KEY-FUNCTION-8  ?DUP  0=  IF
+      DOS-KEY-FUNCTION-7 DUP 3  =  IF
+        DROP 0  ELSE  256 +
+      THEN
+    THEN
+;
+
+ +

+ +Of course, if the Forth implementor chooses to pass Ctrl-C through to +the program, without using it for its usual interrupt function, then DOS +function 7 is appropriate in both cases (and some additional care must +be taken to prevent a typed-ahead Ctrl-C from interrupting the Forth +system during output operations). + +

+ +A Forth system might also choose a simpler implementation of KEY, +without implementing EKEY, as follows: + +

+: KEY   ( -- char )  DOS-KEY  ;
+
+: KEY?  ( -- flag )  DOS-KEY? 0<>  ;
+
+ +

+ +The disadvantages of the simpler version are: + +

+ +a) An application program that uses KEY, expecting to receive only valid +characters, might receive a sequence of bytes (e.g., a zero byte +followed by a byte with the same numerical value as the letter A) +that appears to contain a valid character, even though the user pressed +a key (e.g., function key 4) that does not correspond to any valid +character. + +

+ +b) An application program that wishes to handle non-character events +will have to execute KEY twice if it returns zero the first time. This +might appear to be a reasonable and easy thing to do. However, such +code is not portable to other systems that do not use a zero byte as an +escape code. Using the EKEY approach, the algorithm for handling +keyboard events can be the same for all systems; the system dependencies +can be reduced to a table or set of constants listing the +system-dependent key codes used to access particular application +functions. Without EKEY, the algorithm, not just the table, is likely +to be system dependent. + +

+ +Another approach to EKEY on MS-DOS is to use the BIOS Read Keyboard +Status function (Interrupt 16h, Function 01h) or the related +Check Keyboard function (Interrupt 16h, Function 11h). The +advantage of this function is that it allows the program to distinguish +between different keys that correspond to the same character (e.g. the +two 1 keys). The disadvantage is that the BIOS keyboard +functions read only the keyboard. They cannot be redirected to +another standard input source, as can the DOS STDIN Input +functions. + +

+ + +


+ +A.10.6.2.1306 +EKEY>CHAR + +

+ +EKEY>CHAR translates a keyboard event into the corresponding member of +the character set, if such a correspondence exists for that event. + +

+ +It is possible that several different keyboard events may correspond to +the same character, and other keyboard events may correspond to no +character. + +

+ +


+ +A.10.6.2.1325 +EMIT? + +

+ +An indefinite delay is a device related condition, such as printer +off-line, that requires operator intervention before the device will +accept new data. + +

+ +


+ +A.10.6.2.1905 +MS + +

+ +Although their frequencies vary, every system has a clock. Since many +programs need to time intervals, this word is offered. Use of +milliseconds as an internal unit of time is a practical least common +denominator external unit. It is assumed implementors will use +clock ticks (whatever size they are) as an internal unit and +convert as appropriate. + +

+ +


+ +A.10.6.2.2292 +TIME&DATE + +

+ +Most systems have a real-time clock/calendar. This word gives portable +access to it. + +

+ +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansa11.htm b/docs/reference/standards/ans94/dpansa11.htm new file mode 100644 index 00000000..8383dcde --- /dev/null +++ b/docs/reference/standards/ans94/dpansa11.htm @@ -0,0 +1,304 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

A.11 The optional File-Access word set

+ +Many Forth systems support access to a host file system, and many of +these support interpretation of Forth from source text files. The +Forth-83 Standard did not address host OS files. Nevertheless, a degree +of similarity exists among modern implementations. + +

+ +For example, files must be opened and closed, created and deleted. +Forth file-system implementations differ mostly in the treatment and +disposition of the exception codes, and in the format of the +file-identification strings. The underlying mechanism for creating +file-control blocks might or might not be visible. We have chosen to +keep it invisible. + +

+ +Files must also be read and written. Text files, if supported, must be +read and written one line at a time. Interpretation of text files +implies that they are somehow integrated into the text interpreter input +mechanism. These and other requirements have shaped the file-access +extensions word set. + +

+ +Most of the existing implementations studied use simple English words +for common host file functions: OPEN, CLOSE, READ, etc. Although we +would have preferred to do likewise, there were so many minor variations +in implementation of these words that adopting any particular meaning +would have broken much existing code. We have used names with a suffix +-FILE for most of these words. We encourage implementors to conform +their single-word primitives to the ANS behaviors, and hope that if this +is done on a widespread basis we can adopt better definition names in a +future standard. + +

+ +Specific rationales +for members of this word set follow. + +

+ +


+ +

A.11.3 Additional usage requirements

+
+ +
+ +

A.11.3.2 Blocks in files

+
+ +Many systems reuse file identifiers; when a file is closed, a +subsequently opened file may be given the same identifier. If the +original file has blocks still in block buffers, these will be +incorrectly associated with the newly opened file with disastrous +results. The block buffer system must be flushed to avoid this. + +

+ +


+ +

A.11.6 Glossary

+
+ + +
+ +A.11.6.1.0765 BIN + +

+ +Some operating systems require that files be opened in a different mode +to access their contents as an unstructured stream of binary data rather +than as a sequence of lines. + +

+ +The arguments to +READ-FILE and +WRITE-FILE are +arrays of character +storage elements, each element consisting of at least 8 bits. The +Technical Committee intends that, in BIN mode, the contents of these +storage elements can be written to a file and later read back without +alteration. The Technical Committee has declined to address issues +regarding the impact of wide characters on the File and Block +word sets. + +

+ +


+ +A.11.6.1.1010 CREATE-FILE + +

+ +Typical use: + +

+: X .. S" TEST.FTH" R/W CREATE-FILE  ABORT" CREATE-FILE FAILED" ... ;
+
+

+ +


+ +A.11.6.1.1717 INCLUDE-FILE + +

+ +Here are two implementation alternatives for saving the input source +specification in the presence of text file input: + +

+ +1) Save the file position (as returned by +FILE-POSITION) of the beginning +of the line being interpreted. To restore the input source specification, +seek to that position and re-read the line into the input buffer. + +

+ +2) Allocate a separate line buffer for each active text input file, using +that buffer as the input buffer. This method avoids the seek and reread +step, and allows the use of pseudo-files such as pipes and other +sequential-access-only communication channels. + +

+ +


+ +A.11.6.1.1718 INCLUDED + +

+ +Typical use: ... S" filename" INCLUDED ... + +

+ +


+ +A.11.6.1.1970 OPEN-FILE + +

+ +Typical use: + +

+: X .. S" TEST.FTH" R/W OPEN-FILE  ABORT" OPEN-FILE FAILED" ... ;
+
+

+ +


+ +A.11.6.1.2080 READ-FILE + +

+ +A typical sequential +file-processing algorithm might look like: + +

+   BEGIN                (  )
+   ... READ-FILE THROW  ( length )
+   ?DUP WHILE           ( length )
+   ...                  (  )
+   REPEAT               (  )
+
+ +

+ +In this example, +THROW +is used to handle (unexpected) exception +conditions, which are reported as non-zero values of the ior return +value from READ-FILE. End-of-file is reported as a zero value of the +length return value. + +

+ +


+ +A.11.6.1.2090 READ-LINE + +

+ +Implementations are allowed to store the line terminator in the memory +buffer in order to allow the use of line reading functions provided by +host operating systems, some of which store the terminator. Without +this provision, a temporary buffer might be needed. The two-character +limitation is sufficient for the vast majority of existing operating +systems. Implementations on host operating systems whose line +terminator sequence is longer than two characters may have to take +special action to prevent the storage of more than two terminator +characters. + +

+ +Standard Programs may not depend on the presence of any such terminator +sequence in the buffer. + +

+ +A typical line-oriented sequential file-processing algorithm might look +like: + +

+   BEGIN                (  )
+   ... READ-LINE THROW  ( length not-eof-flag )
+   WHILE                ( length )
+   ...                  (  )
+   REPEAT DROP          (  )
+
+ +

+ +In this example, +THROW +is used to handle (unexpected) I/O exception condition, +which are reported as non-zero values of the ior return value from +READ-LINE. + +

+ +READ-LINE needs a separate end-of-file flag because empty (zero-length) lines +are a routine occurrence, so a zero-length line cannot be used to signify +end-of-file. + +

+ +


+ +A.11.6.1.2165 S" + +

+ +Typical use: ... S" ccc" ... + +

+ +The interpretation semantics for S" are intended to provide a simple +mechanism for entering a string in the interpretation state. Since an +implementation may choose to provide only one buffer for interpreted +strings, an interpreted string is subject to being overwritten by the +next execution of S" in interpretation state. It is intended that no +standard words other than S" should in themselves cause the interpreted +string to be overwritten. However, since words such as +EVALUATE, +LOAD, +INCLUDE-FILE and +INCLUDED +can result in the interpretation of arbitrary +text, possibly including instances of S", the interpreted string may be +invalidated by some uses of these words. + +

+ +When the possibility of overwriting a string can arise, it is prudent to +copy the string to a safe buffer allocated by the application. + +

+ +Programs wishing to parse in the fashion of S" are advised to use +PARSE +or +WORD +COUNT +instead of S", preventing the overwriting of the +interpreted string buffer. + +

+ +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansa12.htm b/docs/reference/standards/ans94/dpansa12.htm new file mode 100644 index 00000000..3b1c2909 --- /dev/null +++ b/docs/reference/standards/ans94/dpansa12.htm @@ -0,0 +1,382 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

A.12 The optional Floating-Point word set

+ +The Technical Committee has considered many proposals dealing with the +inclusion and makeup of the Floating-Point Word Sets in ANS Forth. +Although it has been argued that ANS Forth should not address +floating-point arithmetic and numerous Forth applications do not need +floating-point, there are a growing number of important Forth +applications from spreadsheets to scientific computations that require +the use of floating-point arithmetic. Initially the Technical Committee +adopted proposals that made the Forth Vendors Group Floating-Point +Standard, first published in 1984, the framework for inclusion of +Floating-Point in ANS Forth. There is substantial common practice and +experience with the Forth Vendors Group Floating-Point Standard. +Subsequently the Technical Committee adopted proposals that placed the +basic floating-point arithmetic, stack and support words in the +Floating-Point word set and the floating-point transcendental functions +in the Floating-Point Extensions word set. The Technical Committee also +adopted proposals that: + +
    +
  • changed names for clarity and consistency; e.g., REALS to +FLOATS, and +REAL+ to +FLOAT+ . +
  • removed words; e.g., FPICK . +
  • added words for completeness and increased functionality; e.g., +FSINCOS, +F~, +DF@, +DF!, +SF@ and +SF! +
+

+ +Several issues concerning the Floating-Point word set were resolved by +consensus in the Technical Committee: + +

+ +Floating-point stack: By default the floating-point stack is separate +from the data and return stacks; however, an implementation may keep +floating-point numbers on the data stack. A program can determine +whether floating-point numbers are kept on the data stack by passing the +string +FLOATING-STACK to +ENVIRONMENT? +It is the experience of several +members of the Technical Committee that with proper coding practices it +is possible to write floating-point code that will run identically on +systems with a separate floating-point stack and with floating-point +numbers kept on the data stack. + +

+ +Floating-point input: The current base must be +DECIMAL. Floating-point +input is not allowed in an arbitrary base. All floating-point numbers +to be interpreted by an ANS Forth system must contain the exponent +indicator E (see +12.3.7 Text interpreter input number +conversion). +Consensus in the Technical Committee deemed this form of +floating-point input to be in more common use than the alternative that +would have a floating-point input mode that would allow numbers with +embedded decimal points to be treated as floating-point numbers. + +

+ +Floating-point representation: Although the format and precision of the +significand and the format and range of the exponent of a floating-point +number are implementation defined in ANS Forth, the Floating-Point +Extensions word set contains the words DF@, SF@, DF!, and SF! for +fetching and storing double- and single-precision IEEE +floating-point-format numbers to memory. The IEEE floating-point format +is commonly used by numeric math co-processors and for exchange of +floating-point data between programs and systems. + +

+ + +


+ +

A.12.3 Additional usage requirements

+
+ + + +
+ +

A.12.3.5 Address alignment

+
+ +In defining custom floating-point data structures, be aware that +CREATE +doesn't necessarily leave the data space pointer aligned for various +floating-point data types. Programs may comply with the requirement for +the various kinds of floating-point alignment by specifying the +appropriate alignment both at compile-time and execution time. For +example: + +
+: FCONSTANT ( F:  r -- )
+    CREATE FALIGN  HERE  1 FLOATS ALLOT  F!
+    DOES> ( F:  -- r )  FALIGNED F@ ;
+
+ +

+ + +


+ +

A.12.3.7 Text interpreter input number conversion

+
+ +The Technical Committee has more than once received the suggestion that +the text interpreter in Standard Forth systems should treat numbers that +have an embedded decimal point, but no exponent, as floating-point +numbers rather than double cell numbers. This suggestion, although it +has merit, has always been voted down because it would break too much +existing code; many existing implementations put the full digit string +on the stack as a double number and use other means to inform the +application of the location of the decimal point. + +

+ +See: +RFI 0004 Number Conversion + +

+ +


+ +

A.12.6 Glossary

+
+ + + +
+A.12.6.1.0558 >FLOAT +

+ +>FLOAT enables programs to read floating-point data in legible ASCII +format. It accepts a much broader syntax than does the text interpreter +since the latter defines rules for composing source programs whereas +>FLOAT defines rules for accepting data. >FLOAT is defined as broadly +as is feasible to permit input of data from ANS Forth systems as well as +other widely used standard programming environments. + +

+ +This is a synthesis of common FORTRAN practice. Embedded spaces are +explicitly forbidden in much scientific usage, as are other field +separators such as comma or slash. + +

+ +While >FLOAT is not required to treat a string of blanks as zero, this +behavior is strongly encouraged, since a future version of ANS Forth may +include such a requirement. + +

+ +


+A.12.6.1.1427 F. +

+ +For example, 1E3 F. displays 1000. . + +

+ +


+A.12.6.1.1492 FCONSTANT +

+ +Typical use: r FCONSTANT name + +

+ +


+A.12.6.1.1552 FLITERAL +

+ +Typical use: : X ... [ ... ( r ) ] FLITERAL ... ; + +

+ +


+A.12.6.1.1630 FVARIABLE +

+ +Typical use: FVARIABLE name + +

+ +


+A.12.6.1.2143 REPRESENT +

+ +This word provides a primitive for floating-point display. Some +floating-point formats, including those specified by IEEE-754, allow +representations of numbers outside of an implementation-defined range. +These include plus and minus infinities, denormalized numbers, and +others. In these cases we expect that REPRESENT will usually be +implemented to return appropriate character strings, such as ++infinity or nan, possibly truncated. + +

+ +


+A.12.6.2.1489 FATAN2 +

+ +FSINCOS +and +FATAN2 +are a complementary pair of operators which convert +angles to 2-vectors and vice-versa. They are essential to most +geometric and physical applications since they correctly and +unambiguously handle this conversion in all cases except null vectors, +even when the tangent of the angle would be infinite. + +

+ +FSINCOS returns a Cartesian unit vector in the direction of the given +angle, measured counter-clockwise from the positive X-axis. The order +of results on the stack, namely y underneath x, permits the 2-vector +data type to be additionally viewed and used as a ratio approximating +the tangent of the angle. Thus the phrase FSINCOS +F/ is functionally +equivalent to +FTAN, +but is useful over only a limited and discontinuous +range of angles, whereas FSINCOS and FATAN2 are useful for all angles. +This ordering has been found convenient for nearly two decades, and has +the added benefit of being easy to remember. A corollary to this +observation is that vectors in general should appear on the stack in +this order. + +

+ +The argument order for FATAN2 is the same, converting a vector in the +conventional representation to a scalar angle. Thus, for all angles, +FSINCOS FATAN2 is an identity within the accuracy of the arithmetic and +the argument range of FSINCOS. Note that while FSINCOS always returns a +valid unit vector, FATAN2 will accept any non-null vector. An ambiguous +condition exists if the vector argument to FATAN2 has zero magnitude. + +

+ +


+A.12.6.2.1516 FEXPM1 +

+ +This function allows accurate computation when its arguments are close +to zero, and provides a useful base for the standard exponential +functions. Hyperbolic functions such as cosh(x) can be efficiently and +accurately implemented by using FEXPM1; accuracy is lost in this +function for small values of x if the word +FEXP is used. + +

+ +An important application of this word is in finance; say a loan is +repaid at 15% per year; what is the daily rate? On a computer with +single precision (six decimal digit) accuracy: + +

+ +1. Using +FLN and FEXP: +

+ +FLN of 1.15 = 0.139762, +divide by 365 = 3.82910E-4, +form the exponent using +FEXP = 1.00038, and +subtract one (1) and convert to percentage = 0.038%. + +

+ +Thus we only have two digit accuracy. +

+ + +2. Using +FLNP1 and FEXPM1: + +

+ +FLNP1 of 0.15 = 0.139762, (this is the same value as in the first example, +although with the argument closer to zero it may not be so) +divide by 365 = 3.82910E-4, +form the exponent and subtract one (1) using FEXPM1 = 3.82983E-4, +and convert to percentage = 0.0382983%. + +

+ +This is full six digit accuracy. +

+ + +The presence of this word allows the hyperbolic functions to be computed with +usable accuracy. For example, the hyperbolic sine can be defined as: + +

+: FSINH  ( r1 -- r2 )
+    FEXPM1  FDUP  FDUP 1.0E0 F+  F/  F+  2.0E0 F/ ;
+
+ +

+ +


+A.12.6.2.1554 FLNP1 +

+ +This function allows accurate compilation when its arguments are close +to zero, and provides a useful base for the standard logarithmic +functions. For example, +FLN can be implemented as: + + +

+	: FLN   1.0E0 F-  FLNP1 ;
+
+

+ +See: +A.12.6.2.1516 FEXPM1 + +

+ +


+A.12.6.2.1616 FSINCOS +

+ +See: +A.12.6.2.1489 FATAN2 + +

+ +


+A.12.6.2.1640 F~ +

+ +This provides the three types of floating point equality in +common use -- close in absolute terms, exact equality as +represented, and relatively close. + +

+ +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansa13.htm b/docs/reference/standards/ans94/dpansa13.htm new file mode 100644 index 00000000..25fc0e61 --- /dev/null +++ b/docs/reference/standards/ans94/dpansa13.htm @@ -0,0 +1,392 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

A.13 The optional Locals word set

+ +The Technical Committee has had a problem with locals. It has been +argued forcefully that ANS Forth should say nothing about locals since: + +
    +
  • there is no clear accepted practice in this area; +
  • not all Forth programmers use them or even know what they are; and +
  • few implementations use the same syntax, let alone the same broad +usage rules and general approaches. +
+

+ +It has also been argued, it would seem equally forcefully, that the lack +of any standard approach to locals is precisely the reason for this lack +of accepted practice since locals are at best non-trivial to implement +in a portable and useful way. It has been further argued that users who +have elected to become dependent on locals tend to be locked into a +single vendor and have little motivation to join the group that it is +hoped will broadly accept ANS Forth unless the Standard addresses +their problems. + +

+ +Since the Technical Committee has been unable to reach a strong +consensus on either leaving locals out or on adopting any particular +vendor's syntax, it has sought some way to deal with an issue that it +has been unable to simply dismiss. Realizing that no single mechanism +or syntax can simultaneously meet the desires expressed in all the +locals proposals that have been received, it has simplified the problem +statement to be to define a locals mechanism that: + +

    +
  • is independent of any particular syntax; +
  • is user extensible; +
  • enables use of arbitrary identifiers, local in scope to a single +definition; +
  • supports the fundamental cell size data types of Forth; and +
  • works consistently, especially with respect to re-entrancy and +recursion. +
+

+ +This appears to the Technical Committee to be what most of those who +actively use locals are trying to achieve with them, and it is at +present the consensus of the Technical Committee that if ANS Forth has +anything to say on the subject this is an acceptable thing for it to +say. + +

+ +This approach, defining +(LOCAL), +is proposed as one that can be used +with a small amount of user coding to implement some, but not all, of +the locals schemes in use. The following coding examples illustrate how +it can be used to implement two syntaxes. + +

+ +The syntax defined by this Standard and used in the systems of +Creative Solutions, Inc.: + +

+ + +

+   : LOCALS|  ( "name...name |" -- )
+       BEGIN
+         BL WORD   COUNT OVER C@
+         [CHAR] | - OVER 1 - OR
+       WHILE
+         (LOCAL)
+       REPEAT 2DROP   0 0 (LOCAL)
+   ;
+   IMMEDIATE
+
+   : EXAMPLE  ( n -- n n**2 n**3 )
+       LOCALS| N |   N  DUP N *  DUP N * ;
+
+ +A proposed syntax: ( LOCAL name ) with additional usage rules: + +

+ + +

+   : LOCAL  ( "name" -- )  BL WORD COUNT (LOCAL) ;  IMMEDIATE
+
+   : END-LOCALS  ( -- )  0 0 (LOCAL) ;  IMMEDIATE
+
+   : EXAMPLE  ( n -- n n**2 n**3 )
+       LOCAL N  END-LOCALS   N  DUP N *  DUP N * ;
+
+ +

+ +Other syntaxes can be implemented, although some will admittedly require +considerably greater effort or in some cases program conversion. Yet +other approaches to locals are completely incompatible due to gross +differences in usage rules and in some cases even scope identifiers. +For example, the complete local scheme in use at Johns Hopkins had +elaborate semantics that cannot be duplicated in terms of this model. + +

+ +To reinforce the intent of section +13, here are two examples of actual use of +locals. The first illustrates correct usage: + +

+ +a) + +

+: {  ( "name ... }" - )
+    BEGIN  BL WORD COUNT
+      OVER C@ [CHAR] }
+      - OVER 1 -  OR 
+    WHILE
+      (LOCAL)
+    REPEAT 2DROP 0 0 (LOCAL)
+;  IMMEDIATE
+
+ +

+ +b) + +

+: JOE  ( a b c -- n )
+    >R 2* R> 2DUP + 0
+    { ANS 2B+C C 2B A }
+    2 0 DO  1 ANS + I + TO ANS  ANS . CR  LOOP
+    ANS . 2B+C . C . 2B . A . CR
+    ANS
+;
+
+c) +
+100 300 10 JOE .
+
+ +

+ +The word { at a) defines a local declaration syntax that surrounds the +list of locals with braces. It doesn't do anything fancy, such as +reordering locals or providing initial values for some of them, so +locals are initialized from the stack in the default order. The +definition of JOE at b) illustrates a use of this syntax. Note that +work is performed at execution time in that definition before locals are +declared. It's OK to use the return stack as long as whatever is placed +there is removed before the declarations begin. + +

+ +Note that before declaring locals, B is doubled, a subexpression (2B+C) +is computed, and an initial value (zero) for ANS is provided. After +locals have been declared, JOE proceeds to use them. Note that locals +may be accessed and updated within do-loops. The effect of interpreting +line c) is to display the following values: + +

+ +1 (ANS the first time through the loop), +
+3 (ANS the second time), +
+3 (ANS), 610 (2B+C), 10 (C), 600 (2B), 100 (A), +
+and 3 (ANS left on the stack by JOE). +
+ +

+ +The names of the locals vanish after JOE has been compiled. The storage and +meaning of locals appear when JOE's locals are declared and vanish as JOE +returns to its caller at ; (semicolon). + +

+ +A second set of examples illustrates various things that break the rules. We +assume that the definitions of LOCAL and END-LOCALS above are present, along +with { from the preceding example. +

+ +d) +

+: ZERO   0 POSTPONE LITERAL POSTPONE LOCAL ; IMMEDIATE
+
+

+ +e) +

+: MOE  ( a b )
+     ZERO TEMP  LOCAL B  1+ LOCAL A+  ZERO ANSWER ;
+
+ +

+ +f) +

+: BOB  ( a b c d )  { D C }  { B A } ;
+
+

+ +Here are two definitions with various violations of rule +13.3.3.2a. In +e) the declaration of TEMP is legal and creates a local whose initial +value is zero. It's OK because the executable code that ZERO generates +precedes the first use of (LOCAL) in the definition. However, the 1+ +preceding the declaration of A+ is illegal. Likewise the use of ZERO to +define ANSWER is illegal because it generates executable code between +uses of (LOCAL). Finally, MOE terminates illegally (no END-LOCALS). +BOB in f) violates the rule against declaring two sets of locals. +

+ +g) +

+: ANN  ( a b  -- b )  DUP >R  DUP IF { B A } THEN  R> ;
+
+

+ +h) +

+: JANE  ( a b -- n )  { B A }  A B + >R  A B -  R> / ;
+
+

+ +ANN in g) violates two rules. The IF ... THEN around the declaration +of its locals violates +13.3.3.2b, +and the copy of B left on the return +stack before declaring locals violates +13.3.3.2c. JANE in h) violates +13.3.3.2d +by accessing locals after placing the sum of A and B on the +return stack without first removing that sum. + +

+ +i) +

+: CHRIS  ( a b)
+     { B A }  ['] A EXECUTE  5 ['] B >BODY !
+     [ ' A ] LITERAL LEE ;
+
+ +

+ +CHRIS in i) illustrates three violations of +13.3.3.2e. The attempt to +EXECUTE +the local called A is inconsistent with some implementations. +The store into B via +>BODY +is likely to cause tragic results with many +implementations; moreover, if locals are in registers they can't be +addressed as memory no matter what is written. + +

+ +The third violation, in which an execution token for a definition's +local is passed as an argument to the word LEE, would, if allowed, have +the unpleasant implication that LEE could EXECUTE the token and obtain a +value for A from the particular execution of CHRIS that called LEE this +time. + +

+ +


+ +

A.13.3 Additional usage requirements

+
+ +Rule +13.3.3.2d +could be relaxed without affecting the integrity of the +rest of this structure. +13.3.3.2c could not be. + +

+ +13.3.3.2b +forbids the use of the data stack for local storage because no +usage rules have been articulated for programmer users in such a case. +Of course, if the data stack is somehow employed in such a way that +there are no usage rules, then the locals are invisible to the +programmer, are logically not on the stack, and the implementation +conforms. + +

+ +The minimum required number of locals can (and should) be adjusted to +minimize the cost of compliance for existing users of locals. + +

+ +Access to previously declared local variables is prohibited by Section +13.3.3.2d +until any data placed onto the return stack by the application +has been removed, due to the possible use of the return stack for +storage of locals. + +

+ +Authorization for a Standard Program to manipulate the return stack +(e.g., via +>R +R>) +while local variables are active overly constrains +implementation possibilities. The consensus of users of locals was that +Local facilities represent an effective functional replacement for +return stack manipulation, and restriction of standard usage to only one +method was reasonable. + +

+ +Access to Locals within +DO..LOOPs +is expressly permitted as an +additional requirement of conforming systems by Section +13.3.3.2g. +Although words, such as +(LOCALS), +written by a System Implementor, may +require inside knowledge of the internal structure of the return stack, +such knowledge is not required of a user of compliant Forth systems. + +

+ +


+ +

A.13.6 Glossary

+
+ + + +
+A.13.6.1.2295 TO +

+ +Typical use: x TO name + +

+ +See: A.6.2.2295 TO + +

+ +


+A.13.6.2.1795 LOCALS| +

+ +A possible implementation of this word and an example of usage is given in +A.13, +above. It is intended as an example only; any implementation yielding +the described semantics is acceptable. + +

+ +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansa14.htm b/docs/reference/standards/ans94/dpansa14.htm new file mode 100644 index 00000000..3ecd22f6 --- /dev/null +++ b/docs/reference/standards/ans94/dpansa14.htm @@ -0,0 +1,44 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

A.14 The optional Memory-Allocation word set

+ +The Memory-Allocation word set provides a means for acquiring memory +other than the contiguous data space that is allocated by +ALLOT. In +many operating system environments it is inappropriate for a process to +pre-allocate large amounts of contiguous memory (as would be necessary +for the use of ALLOT). The Memory-Allocation word set can acquire +memory from the system at any time, without knowing in advance the +address of the memory that will be acquired. + +

+ +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansa15.htm b/docs/reference/standards/ans94/dpansa15.htm new file mode 100644 index 00000000..5467c9ae --- /dev/null +++ b/docs/reference/standards/ans94/dpansa15.htm @@ -0,0 +1,279 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

A.15 The optional Programming-Tools word set

+ +These words have been in widespread common use since the earliest Forth +systems. + +

+ +Although there are environmental dependencies intrinsic to programs +using an assembler, virtually all Forth systems provide such a +capability. Insofar as many Forth programs are intended for real-time +applications and are intrinsically non-portable for this reason, the +Technical Committee believes that providing a standard window into +assemblers is a useful contribution to Forth programmers. + +

+ +Similarly, the programming aids +DUMP, +etc., are valuable tools even +though their specific formats will differ between CPUs and Forth +implementations. These words are primarily intended for use by the +programmer, and are rarely invoked in programs. + +

+ +One of the original aims of Forth was to erase the boundary between +user and programmer - to give all possible power to anyone +who had occasion to use a computer. Nothing in the above labeling or +remarks should be construed to mean that this goal has been abandoned. + +

+ +


+ +

A.15.6 Glossary

+
+ + + +
+A.15.6.1.0220 .S +

+ +.S is a debugging convenience found on almost all Forth systems. It is +universally mentioned in Forth texts. + +

+ +


+A.15.6.1.2194 SEE +

+ +SEE acts as an on-line form of documentation of words, allowing modification +of words by decompiling and regenerating with appropriate changes. + +

+ +


+A.15.6.1.2465 WORDS +

+ +WORDS is a debugging convenience found on almost all Forth systems. It is +universally referred to in Forth texts. + +

+ +


+A.15.6.2.0470 ;CODE +

+ +Typical use: : namex ... <create> ... ;CODE ... + +

+ +where namex is a defining word, and <create> is +CREATE or any user +defined +word that calls CREATE. + +

+ +


+A.15.6.2.0930 CODE +

+ +Some Forth systems implement the assembly function by adding an +ASSEMBLER +word list to the search order, using the text interpreter to +parse a postfix assembly language with lexical characteristics similar +to Forth source code. Typically, in such systems, assembly ends when a +word END-CODE is interpreted. + +

+ +


+A.15.6.2.1015 CS-PICK +

+ +The intent is to reiterate a dest on the control-flow stack so that it can be +resolved more than once. For example: + +

+\ Conditionally transfer control to beginning of loop
+\ This is similar in spirit to C's "continue" statement.
+
+: ?REPEAT  ( dest -- dest ) \ Compilation
+           ( flag -- )      \ Execution
+    0 CS-PICK   POSTPONE UNTIL
+; IMMEDIATE
+
+: XX  ( -- ) \ Example use of ?REPEAT
+    BEGIN
+      ...
+    flag ?REPEAT  ( Go back to BEGIN if flag is false )
+      ...
+    flag ?REPEAT  ( Go back to BEGIN if flag is false )
+      ...
+    flag UNTIL    ( Go back to BEGIN if flag is false )
+    ...
+;
+
+ +

+ +


+A.15.6.2.1020 CS-ROLL +

+ +The intent is to modify the order in which the origs and dests on the +control-flow stack are to be resolved by subsequent control-flow words. For +example, +WHILE could be implemented in terms of +IF and CS-ROLL, as follows: + +

+: WHILE  ( dest -- orig dest )   POSTPONE IF  1 CS-ROLL ; IMMEDIATE
+
+

+ +


+A.15.6.2.1580 FORGET +

+ +Typical use: ... FORGET name ... + +

+ +FORGET assumes that all the information needed to restore the dictionary to +its previous state is inferable somehow from the forgotten word. While this +may be true in simple linear dictionary models, it is difficult to implement +in other Forth systems; e.g., those with multiple address spaces. For +example, if Forth is embedded in ROM, how does FORGET know how much RAM to +recover when an array is forgotten? A general and preferred solution is +provided by +MARKER. + +

+ +


+A.15.6.2.2531 [ELSE] +

+ +Typical use: ... flag [IF] ... [ELSE] ... [THEN] ... + +

+ +


+A.15.6.2.2532 [IF] +

+ +Typical use: ... flag [IF] ... [ELSE] ... [THEN] ... + +

+ +


+A.15.6.2.2533 [THEN] +

+ +Typical use: ... flag [IF] ... [ELSE] ... [THEN] ... + +

+ +Software that runs in several system environments often contains some +source code that is environmentally dependent. Conditional compilation - the +selective inclusion or exclusion of portions of the source code at +compile time - is one technique that is often used to assist in the +maintenance of such source code. +

+ +Conditional compilation is sometimes done with smart comments - +definitions that either skip or do not skip the remainder of the line +based on some test. For example: + +

+\ If 16-Bit? contains TRUE, lines preceded by 16BIT\
+\ will be skipped. Otherwise, they will not be skipped.
+
+VARIABLE 16-BIT?
+
+: 16BIT\  ( -- )  16-BIT? @  IF  POSTPONE \  THEN ;  IMMEDIATE
+
+ +

+ +This technique works on a line by line basis, and is good for short, +isolated variant code sequences. + +

+ +More complicated conditional compilation problems suggest a nestable +method that can encompass more than one source line at a time. The +words included in the ANS Forth optional Programming tools extensions +word set are useful for this purpose. The implementation given below +works with any input source (keyboard, +EVALUATE, +BLOCK, or text file). + +

+: [ELSE]  ( -- )
+    1 BEGIN                               \ level
+      BEGIN
+        BL WORD COUNT  DUP  WHILE         \ level adr len
+        2DUP  S" [IF]"  COMPARE 0=
+        IF                                \ level adr len
+          2DROP 1+                        \ level'
+        ELSE                              \ level adr len
+          2DUP  S" [ELSE]"
+          COMPARE 0= IF                   \ level adr len
+             2DROP 1- DUP IF 1+ THEN      \ level'
+          ELSE                            \ level adr len
+            S" [THEN]"  COMPARE 0= IF     \ level
+              1-                          \ level'
+            THEN
+          THEN
+        THEN ?DUP 0=  IF EXIT THEN        \ level'
+      REPEAT  2DROP                       \ level
+    REFILL 0= UNTIL                       \ level
+    DROP
+;  IMMEDIATE
+
+: [IF]  ( flag -- )
+0= IF POSTPONE [ELSE] THEN ;  IMMEDIATE
+
+: [THEN]  ( -- )  ;  IMMEDIATE
+
+ +

+ +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansa16.htm b/docs/reference/standards/ans94/dpansa16.htm new file mode 100644 index 00000000..b5ef6b9a --- /dev/null +++ b/docs/reference/standards/ans94/dpansa16.htm @@ -0,0 +1,287 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ + +

A.16 The optional Search-Order word set

+ +Search-order specification and control mechanisms vary widely. The +FIG-Forth, Forth-79, polyFORTH, and Forth-83 vocabulary and search order +mechanisms are all mutually incompatible. The complete list of +incompatible mechanisms, in use or proposed, is much longer. The +ALSO/ONLY +scheme described in a Forth-83 Experimental Proposal has +substantial community support. However, many consider it to be +fundamentally flawed, and oppose it vigorously. + +

+ +Recognizing this variation, this Standard specifies a new +primitive set of tools from which various schemes may be +constructed. This primitive search-order word set is intended to be a +portable construction set from which search-order words may be +built, rather than a user interface. ALSO/ONLY or the various +vocabulary schemes supported by the major Forth vendors can be +defined in terms of the primitive search-order word set. + +

+ +The encoding for word list identifiers wid might be a small-integer +index into an array of word-list definition records, the data-space +address of such a record, a user-area offset, the execution token of a +Forth-83 style sealed vocabulary, the link-field address of the first +definition in a word list, or anything else. It is entirely up to the +system implementor. + +

+ +In some systems the interpretation of numeric literals is controlled by +including pseudo word lists that recognize numbers at the end of +the search order. This technique is accommodated by the default +search order behavior of +SET-ORDER +when given an argument of -1. In +a system using the traditional implementation of ALSO/ONLY , the minimum +search order would be equivalent to the word ONLY. + +

+ +There has never been a portable way to restore a saved search order. +F83 (not Forth-83) introduced the word +PREVIOUS, which almost made it +possible to unload the search order by repeatedly executing the +phrase CONTEXT @ PREVIOUS. +The search order could be reloaded by +repeating +ALSO CONTEXT !. +Unfortunately there was no portable way to +determine how many word lists were in the search order. + +

+ +ANS Forth has removed the word CONTEXT because in many systems its +contents refer to more than one word list, compounding portability +problems. + +

+ +Note that : +(colon) +no longer affects the search order. The previous +behavior, where the compilation word list replaces the first word list +of the search order, can be emulated with the following redefinition of +: (colon). + +

+: :  GET-ORDER SWAP DROP  GET-CURRENT  SWAP SET-ORDER  : ;
+
+

+ + + +


+ +

A.16.2 Additional terms

+
+ +
+
search order +
Note that the use of the term list does not necessarily imply +implementation as a linked list.
+ +

+ + +


+ +

A.16.3.3 Finding definition names

+
+ +In other words, the following is not guaranteed to work: + +
+: FOO  ... [ ... SET-CURRENT ] ... RECURSE ... ;  IMMEDIATE
+
+ +RECURSE, +; (semicolon), and +IMMEDIATE +may or may not need information stored +in the compilation word list. + +

+ + +


+ +

A.16.6 Glossary

+
+ + + +
+A.16.6.1.2192 SEARCH-WORDLIST +

+ +The string argument to SEARCH-WORDLIST is represented by c-addr u, +rather than by just c-addr as with +FIND. +The committee wishes to +establish c-addr u as the preferred representation of a string on the +stack, and has adopted that representation for all new functions that +accept string arguments. While this decision may cause the +implementation of SEARCH-WORDLIST to be somewhat more difficult in +existing systems, the committee feels that the additional difficulty is +minor. + +

+ +When SEARCH-WORDLIST fails to find the word, it does not return the +string, as does FIND. This is in accordance with the general principle +that Forth words consume their arguments. + +

+ +


+A.16.6.2.0715 ALSO +

+ +Here is an implementation of +ALSO/ONLY +in terms of the primitive +search-order word set. + + +

+WORDLIST CONSTANT ROOT   ROOT SET-CURRENT
+
+: DO-VOCABULARY  ( -- ) \ Implementation factor
+    DOES>  @ >R           (  ) ( R: widnew )
+     GET-ORDER  SWAP DROP ( wid1 ... widn-1 n )
+     R> SWAP SET-ORDER
+;
+
+: DISCARD  ( x1 .. xu u - ) \ Implementation factor
+   0 ?DO DROP LOOP          \ DROP u+1 stack items
+;
+
+CREATE FORTH  FORTH-WORDLIST , DO-VOCABULARY
+
+: VOCABULARY  ( name -- )  WORDLIST CREATE ,  DO-VOCABULARY ;
+
+: ALSO  ( -- )  GET-ORDER  OVER SWAP 1+ SET-ORDER ;
+
+: PREVIOUS  ( --  )  GET-ORDER  SWAP DROP 1- SET-ORDER ;
+
+: DEFINITIONS  ( -- )  GET-ORDER  OVER SET-CURRENT DISCARD ;
+
+: ONLY ( -- )  ROOT ROOT  2 SET-ORDER ;
+
+\ Forth-83 version; just removes ONLY
+: SEAL  ( -- )  GET-ORDER 1- SET-ORDER DROP ;
+
+\ F83 and F-PC version; leaves only CONTEXT
+: SEAL  ( -- )  GET-ORDER OVER 1 SET-ORDER DISCARD ;
+
+ +

+ +The preceding definition of ONLY in terms of a ROOT word list +follows F83 usage, and assumes that the default search order just +includes ROOT and +FORTH. +A more portable definition of FORTH and ONLY, +without the assumptions, is: + +

+<omit the  ... WORDLIST CONSTANT ROOT ... line>
+
+CREATE FORTH GET-ORDER OVER , DISCARD DO-VOCABULARY
+
+: ONLY  ( -- )  -1 SET-ORDER ;
+
+ +

+ +Here is a simple implementation of +GET-ORDER and +SET-ORDER, including a +corresponding definition of +FIND. The implementations of +WORDLIST, +SEARCH-WORDLIST, +GET-CURRENT and +SET-CURRENT +depend on system details +and are not given here. + +

+16 CONSTANT #VOCS
+
+VARIABLE #ORDER
+
+CREATE CONTEXT  #VOCS CELLS ALLOT
+
+: GET-ORDER  ( -- wid1 .. widn n )
+    #ORDER @ 0 ?DO
+      #ORDER @  I - 1- CELLS CONTEXT + @
+    LOOP
+    #ORDER @
+;
+
+: SET-ORDER  ( wid1 .. widn n -- )
+    DUP -1 = IF
+      DROP  <push system default word lists and n>
+    THEN
+    DUP #ORDER !
+    0 ?DO  I CELLS CONTEXT + ! LOOP
+;
+
+: FIND  ( c-addr -- c-addr 0 | w 1 | w -1 )
+    0                     ( c-addr 0 )
+    #ORDER @ 0 ?DO
+      OVER COUNT          ( c-addr 0 c-addr' u )
+      I CELLS CONTEXT + @ ( c-addr 0 c-addr' u wid)
+      SEARCH-WORDLIST     ( c-addr 0; 0 | w 1 | w -1 )
+      ?DUP IF             ( c-addr 0; w 1 | w -1 )
+        2SWAP 2DROP LEAVE ( w 1 | w -1 )
+      THEN                ( c-addr 0 )
+    LOOP                  ( c-addr 0 | w 1 | w -1 )
+;
+
+ +

+ +In an implementation where the dictionary search mechanism uses a hash +table or lookup cache to reduce the search time, SET-ORDER might need to +reconstruct the hash table or flush the cache. + +

+ +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansa17.htm b/docs/reference/standards/ans94/dpansa17.htm new file mode 100644 index 00000000..c09e4068 --- /dev/null +++ b/docs/reference/standards/ans94/dpansa17.htm @@ -0,0 +1,148 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

A.17 The optional String word set

+ + + +
+ +

A.17.6 Glossary

+
+ + + +
+A.17.6.1.0245 /STRING +

+ +/STRING is used to remove or add characters relative to the left +end of the character string. Positive values of n will exclude +characters from the string while negative values of n will include +characters to the left of the string. /STRING is a natural factor of +WORD +and commonly available. + +

+ +


+A.17.6.1.0910 CMOVE +

+ +If c-addr2 lies within the source region (i.e., when c-addr2 is not less +than c-addr1 and c-addr2 is less than the quantity c-addr1 u +CHARS +), +memory propagation occurs. + +

+ +Typical +use: Assume a character string at address 100: ABCD. Then after + + +

+	100 DUP  CHAR+  3 CMOVE
+
+ +

+ +the string at address 100 is AAAA. + +

+ +Rationale +for CMOVE and +CMOVE> follows +MOVE. + +

+ +


+A.17.6.1.0920 CMOVE> +

+ +If c-addr1 lies within the destination region (i.e., when c-addr1 is +greater than or equal to c-addr2 and c-addr2 is less than the quantity +c-addr1 u +CHARS +), memory propagation occurs. + +

+ +Typical use: Assume a character string at address 100: ABCD. +Then after + + +

+	100 DUP CHAR+ SWAP 3 CMOVE>
+
+ +

+ +the string at address 100 is DDDD. + +

+ +


+A.17.6.1.0935 COMPARE +

+ +Existing Forth systems perform string comparison operations using words that +differ in spelling, input and output arguments, and case sensitivity. One in +widespread use was chosen. + +

+ +


+A.17.6.1.2191 SEARCH +

+ +Existing Forth systems perform string searching operations using words that +differ in spelling, input and output arguments, and case sensitivity. One in +widespread use was chosen. + +

+ +


+A.17.6.1.2212 SLITERAL +

+ +The current functionality of +6.1.2165 S" may be provided by the following +definition: + +

+: S" ( "ccc<quote>" -- )
+    [CHAR] " PARSE   POSTPONE SLITERAL ; IMMEDIATE
+
+
+

+ + +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansa2.htm b/docs/reference/standards/ans94/dpansa2.htm new file mode 100644 index 00000000..d0ccfa40 --- /dev/null +++ b/docs/reference/standards/ans94/dpansa2.htm @@ -0,0 +1,104 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ + +

A.2 Terms and notation

+ + +
+ +

A.2.1 Definitions of terms

+
+ +
+
ambiguous condition +
The response of a Standard System to an ambiguous condition is left to +the discretion of the implementor. A Standard System need not +explicitly detect or report the occurrence of ambiguous conditions. +

+

cross compiler +
Cross-compilers may be used to prepare a program for execution in an +embedded system, or may be used to generate Forth kernels either for the +same or a different run-time environment. +

+

data field +
In earlier standards, data fields were known as parameter fields. +

+ +On subroutine threaded Forth systems, everything is object code. There +are no traditional code or data fields. Only a word defined by +CREATE +or by a word that calls +CREATE has a data field. Only a data field +defined via CREATE can be manipulated portably. +

+

word set +
This Standard recognizes that some functions, while useful in certain +application areas, are not sufficiently general to justify requiring +them in all Forth systems. Further, it is helpful to group Forth words +according to related functions. These issues are dealt with using the +concept of word sets. + +

+ +The Core word set contains the essential body of words in a Forth +system. It is the only required word set. Other word sets +defined in this Standard are optional additions to make it possible to +provide Standard Systems with tailored levels of functionality.

+ +

+ +


+ +

A.2.2 Notation

+
+ + +
+ +

A.2.2.2 Stack notation

+
+ +The use of -sys, orig, and dest data types in stack effect diagrams +conveys two pieces of information. First, it warns the reader that many +implementations use the data stack in unspecified ways for those +purposes, so that items underneath on either the control-flow or data +stacks are unavailable. Second, in cases where orig and dest are used, +explicit pairing rules are documented on the assumption that all systems +will implement that model so that its results are equivalent to +employment of some stack, and that in fact many implementations do use +the data stack for this purpose. However, nothing in this Standard +requires that implementations actually employ the data stack (or any +other) for this purpose so long as the implied behavior of the model is +maintained. + +

+ +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansa3.htm b/docs/reference/standards/ans94/dpansa3.htm new file mode 100644 index 00000000..6dc13518 --- /dev/null +++ b/docs/reference/standards/ans94/dpansa3.htm @@ -0,0 +1,1434 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

A.3 Usage requirements

+ +Forth systems are unusually simple to develop, in comparison with +compilers for more conventional languages such as C. In addition to +Forth systems supported by vendors, public-domain implementations and +implementation guides have been widely available for nearly twenty +years, and a large number of individuals have developed their own Forth +systems. As a result, a variety of implementation approaches have +developed, each optimized for a particular platform or target market. + +

+ +The X3J14 Technical Committee has endeavored to accommodate this +diversity by constraining implementors as little as possible, consistent +with a goal of defining a standard interface between an underlying Forth +System and an application program being developed on it. + +

+ +Similarly, we will not undertake in this section to tell you how to +implement a Forth System, but rather will provide some guidance as to +what the minimum requirements are for systems that can properly claim +compliance with this Standard. + +

+ +


+ +

A.3.1 Data-types

+
+ +Most computers deal with arbitrary bit patterns. There is no way to +determine by inspection whether a cell contains an address or an +unsigned integer. The only meaning a datum possesses is the meaning +assigned by an application. + +

+ +When data are operated upon, the meaning of the result depends on the +meaning assigned to the input values. Some combinations of input values +produce meaningless results: for instance, what meaning can be assigned +to the arithmetic sum of the ASCII representation of the character +A and a +TRUE +flag? The answer may be no meaning; or +alternatively, that operation might be the first step in producing a +checksum. Context is the determiner. + +

+ +The discipline of circumscribing meaning which a program may assign to +various combinations of bit patterns is sometimes called data typing. +Many computer languages impose explicit data typing and have compilers +that prevent ill-defined operations. + +

+ +Forth rarely explicitly imposes data-type restrictions. Still, data +types implicitly do exist, and discipline is required, particularly if +portability of programs is a goal. In Forth, it is incumbent upon the +programmer (rather than the compiler) to determine that data are +accurately typed. + +

+ +This section attempts to offer guidance regarding de facto data typing +in Forth. + +

+ +


+ +

A.3.1.2 Character types

+
+ +The correct identification and proper manipulation of the character data +type is beyond the purview of Forth's enforcement of data type by means +of stack depth. Characters do not necessarily occupy the entire width +of their single stack entry with meaningful data. While the distinction +between signed and unsigned character is entirely absent from the formal +specification of Forth, the tendency in practice is to treat characters +as short positive integers when mathematical operations come into play. + +

+ +

+a) Standard Character Set + +

+ +

+1) The storage unit for the character data type +(C@, +C!, +FILL, etc.) must be +able to contain unsigned numbers from 0 through 255. + +

+ +2) An implementation is not required to restrict character storage to +that range, but a Standard Program without environmental dependencies +cannot assume the ability to store numbers outside that range in a +char location. + +

+ +3) The allowed number representations are two's-complement, +one's-complement, and signed-magnitude. Note that all of these number +systems agree on the representation of positive numbers. + +

+ +4) Since a char can store small positive numbers and since the +character data type is a sub-range of the unsigned integer data type, C! +must store the n least-significant bits of a cell (8 <= n <= bits/cell). +Given the enumeration of allowed number representations and their known +encodings, +TRUE xx C! xx C@ must leave a stack item with some +number of bits set, which will thus will be accepted as non-zero by +IF. + +

+ +5) For the purposes of input +(KEY, +ACCEPT, +etc.) and output +(EMIT, +TYPE, +etc.), the encoding between numbers and human-readable symbols is +ISO646/IRV (ASCII) within the range from 32 to 126 (space to ~). EBCDIC +is out (most EBCDIC computer systems support ASCII too). Outside +that range, it is up to the implementation. The obvious implementation +choice is to use ASCII control characters for the range from 0 to 31, at +least for the displayable characters in that range (TAB, RETURN, +LINEFEED, FORMFEED). However, this is not as clear-cut as it may seem, +because of the variation between operating systems on the treatment of +those characters. For example, some systems TAB to 4 character +boundaries, others to 8 character boundaries, and others to preset tab +stops. Some systems perform an automatic linefeed after a carriage +return, others perform an automatic carriage return after a linefeed, +and others do neither. + +

+ +The codes from 128 to 255 may eventually be standardized, either +formally or informally, for use as international characters, such as the +letters with diacritical marks found in many European languages. One +such encoding is the 8-bit ISO Latin-1 character set. The computer +marketplace at large will eventually decide which encoding set of those +characters prevails. For Forth implementations running under an +operating system (the majority of those running on standard platforms +these days), most Forth implementors will probably choose to do whatever +the system does, without performing any remapping within the domain of +the Forth system itself. + +

+ +6) A Standard Program can depend on the ability to receive any character +in the range 32 ... 126 through KEY, and similarly to display the same +set of characters with EMIT. If a program must be able to receive or +display any particular character outside that range, it can declare an +environmental dependency on the ability to receive or display that +character. + +

+ +7) A Standard Program cannot use control characters in definition names. +However, a Standard System is not required to enforce this prohibition. +Thus, existing systems that currently allow control characters in words +names from +BLOCK +source may continue to allow them, and programs running +on those systems will continue to work. In text file source, the +parsing action with space as a delimiter (e.g., +BL +WORD) treats control +characters the same as spaces. This effectively implies that you cannot +use control characters in definition names from text-file source, since +the text interpreter will treat the control characters as delimiters. +Note that this control-character folding applies only when space +is the delimiter, thus the phrase +CHAR ) WORD may collect a +string containing control characters. +

+

+ +b) Storage and retrieval +

+ +

+Characters are transferred from the data stack to memory by C! and from +memory to the data stack by C@. A number of lower-significance bits +equivalent to the implementation-dependent width of a character are +transferred from a popped data stack entry to an address by the action +of C! without affecting any bits which may comprise the +higher-significance portion of the cell at the destination address; +however, the action of C@ clears all higher-significance bits of the +data stack entry which it pushes that are beyond the +implementation-dependent width of a character (which may include +implementation-defined display information in the higher-significance +bits). The programmer should keep in mind that operating upon arbitrary +stack entries with words intended for the character data type may result +in truncation of such data. +
+

+ +c) Manipulation on the stack +

+ +

+In addition to C@ and C!, characters are moved to, from and upon the +data stack by the following words: + +

+ + +>R +?DUP +DROP +DUP +OVER +PICK +R> +R@ +ROLL +ROT +SWAP + +

+

+ +d) Additional operations +

+ +

+The following mathematical operators are valid for character data: + +

+ + ++ +- +* +/ +/MOD +MOD + +

+ +The following comparison and bitwise operators may be valid for +characters, keeping in mind that display information cached in the most +significant bits of characters in an implementation-defined fashion may +have to be masked or otherwise dealt with: + +

+ + +AND +OR +> +< +U> +U< += +<> +0= +0<> +MAX +MIN +LSHIFT +RSHIFT + + +

+
+

+ + +


+ +

A.3.1.3 Single-cell types

+
+

+ +A single-cell stack entry viewed without regard to typing is the +fundamental data type of Forth. All other data types are actually +represented by one or more single-cell stack entries. + +

+ +

+a) Storage and retrieval +

+ + +

+Single-cell data are transferred from the stack to memory by +!; from +memory to the stack by +@. +All bits are transferred in both directions +and no type checking of any sort is performed, nor does the Standard +System check that a memory address used by ! or @ is properly aligned or +properly sized to hold the datum thus transferred. +
+

+ +b) Manipulation on the stack +

+ +

+Here is a selection of the most important words which move single-cell +data to, from and upon the data stack: + +

+ + +! +@ +>R +?DUP +DROP +DUP +OVER +PICK +R> +R@ +ROLL +ROT +SWAP + +

+

+ +c) Comparison operators +

+ +

+The following comparison operators are universally valid for one or more +single cells: + +

+ + += +<> +0= +0<> + +

+

+
+ +
+ +

A.3.1.3.1 Flags

+
+ +A +FALSE +flag is a single-cell datum with all bits unset, and a +TRUE +flag +is a single-cell datum with all bits set. While Forth words which test +flags accept any non-null bit pattern as true, there exists the concept +of the well-formed flag. If an operation whose result is to be used as +a flag may produce any bit-mask other than TRUE or FALSE, the +recommended discipline is to convert the result to a well-formed flag by +means of the Forth word +0<> +so that the result of any subsequent logical +operations on the flag will be predictable. + +

+ +In addition to the words which move, fetch and store single-cell items, +the following words are valid for operations on one or more flag data +residing on the data stack: + +

+ + +AND +OR +XOR +INVERT + +

+ +


+ +

A.3.1.3.2 Integers

+
+

+ +Given the same number of bits, unsigned integers usually represent twice +the number of absolute values representable by signed integers. + +

+ +A single-cell datum may be treated by a Standard Program as an unsigned +integer. Moving and storing such data is performed as for any +single-cell data. In addition, the following mathematical and +comparison operators are valid for single-cell unsigned integers: + +

+ + +UM* +UM/MOD ++ ++! +- +1+ +1- +* +U< +U> + +

+ + +


+ +

A.3.1.3.3 Addresses

+
+ +An address is uniquely represented as a single cell unsigned number and can be +treated as such when being moved to, from, or upon the stack. Conversely, +each unsigned number represents a unique address (which is not necessarily an +address of accessible memory). This one-to-one relationship between addresses +and unsigned numbers forces an equivalence between address arithmetic and the +corresponding operations on unsigned numbers. + +

+ +Several operators are provided specifically for address arithmetic: +

+ + +CHAR+ +CHARS +CELL+ +CELLS + +

+ +and, if the floating-point word set is present: +

+ + +FLOAT+ +FLOATS +SFLOAT+ +SFLOATS +DFLOAT+ +DFLOATS + +

+ +A Standard Program may never assume a particular correspondence between +a Forth address and the physical address to which it is mapped. + +

+ + +


+ +

A.3.1.3.4 Counted strings

+
+ +The trend in ANS Forth is to move toward the consistent use of the +c-addr u representation of strings on the stack. The use of the +alternate address of counted string stack representation is +discouraged. The traditional Forth words +WORD and +FIND +continue to use +the address of counted string representation for historical +reasons. The new word +C" +, added as a porting aid for existing +programs, also uses the counted string representation. + +

+ +Counted strings remain useful as a way to store strings in memory. This +use is not discouraged, but when references to such strings appear on +the stack, it is preferable to use the c-addr u representation. + +

+ + +


+ +

A.3.1.3.5 Execution tokens

+
+ +The association between an execution token and a definition is static. +Once made, it does not change with changes in the search order or +anything else. However it may not be unique, e.g., the phrases + +
+	' 1+ 
+   and
+
+	' CHAR+
+
+might return the same value. + +

+ + +


+ +

A.3.1.4 Cell-pair types

+
+ +
+a) Storage and retrieval +

+ +

+Two operators are provided to fetch and store cell pairs: + +

+ + +2@ +2! + +

+

+ +b) Manipulation on the stack +

+ +

+Additionally, these operators may be used to move cell pairs from, to +and upon the stack: + +

+ + +2>R +2DROP +2DUP +2OVER +2R> +2SWAP +2ROT + +

+

+ +c) Comparison +

+ +

+The following comparison operations are universally valid for cell +pairs: + +

+ + +D= +D0= + +

+
+

+ + +


+ +

A.3.1.4.1 Double-cell integers

+
+ +If a double-cell integer is to be treated as signed, the following +comparison and mathematical operations are valid: + +

+ + +D+ +D- +D< +D0< +DABS +DMAX +DMIN +DNEGATE +M*/ +M+ + +

+ +If a double-cell integer is to be treated as unsigned, the following +comparison and mathematical operations are valid: + +

+ + +D+ +D- +UM/MOD +DU< + +

+ + +


+ +

A.3.1.4.2 Character strings

+
+ +See: +A.3.1.3.4 Counted Strings +

+ + +


+ +

A.3.2 The implementation environment

+
+ + + +
+ +

A.3.2.1 Numbers

+
+ +Traditionally, Forth has been implemented on two's-complement machines +where there is a one-to-one mapping of signed numbers to unsigned +numbers - any single cell item can be viewed either as a signed or +unsigned number. Indeed, the signed representation of any positive +number is identical to the equivalent unsigned representation. Further, +addresses are treated as unsigned numbers: there is no distinct pointer +type. Arithmetic ordering on two's complement machines allows + and - +to work on both signed and unsigned numbers. This arithmetic behavior +is deeply embedded in common Forth practice. As a consequence of these +behaviors, the likely ranges of signed and unsigned numbers for +implementations hosted on each of the permissible arithmetic +architectures is: + +

+

+      ---------------------------------------------------------
+      Arithmetic architecture  signed numbers  unsigned numbers
+      ---------------------------------------------------------
+      Two's complement         -n-1 to n       0 to 2n+1
+      One's complement         -n to n         0 to n
+      Signed magnitude         -n to n         0 to n
+      ---------------------------------------------------------
+
+

+ +where n is the largest positive signed number. For all three +architectures, signed numbers in the 0 to n range are bitwise identical +to the corresponding unsigned number. Note that unsigned numbers on a +signed magnitude machine are equivalent to signed non-negative numbers +as a consequence of the forced correspondence between addresses and +unsigned numbers and of the required behavior of + and -. + +

+ +For reference, these number representations may be defined by the way +that +NEGATE is implemented: + +

+ + +

+two's complement:       : NEGATE  INVERT 1+ ;
+one's complement:       : NEGATE  INVERT ;
+signed-magnitude:       : NEGATE  HIGH-BIT XOR ;
+
+ +

+ +where HIGH-BIT is a bit mask with only the most-significant bit set. +Note that all of these number systems agree on the representation of +non-negative numbers. + +

+ +Per 3.2.1.1 Internal number +representation and +6.1.0270 0=, the +implementor must ensure that no standard or supported word return +negative zero for any numeric (non-Boolean or flag) result. Many +existing programmer assumptions will be violated otherwise. + +

+ +There is no requirement to implement circular unsigned arithmetic, nor +to set the range of unsigned numbers to the full size of a cell. There +is historical precedent for limiting the range of u to that of +n, which +is permissible when the cell size is greater than 16 bits. + +

+ + +


+ +

A.3.2.1.2 Digit conversion

+
+ +For example, an implementation might convert the characters a +through z identically to the characters A through +Z, or it might treat the characters [ through ~ +as additional digits with decimal values 36 through 71, respectively. + +

+ + +


+ +

A.3.2.2 Arithmetic

+
+ + +
+ +

A.3.2.2.1 Integer division

+
+ +The Forth-79 Standard specifies that the signed division operators +(/, +/MOD, +MOD, +*/MOD, +and +*/) +round non-integer quotients towards zero +(symmetric division). Forth-83 changed the semantics of these operators +to round towards negative infinity (floored division). Some in the +Forth community have declined to convert systems and applications from +the Forth-79 to the Forth-83 divide. To resolve this issue, an ANS +Forth system is permitted to supply either floored or symmetric +operators. In addition, ANS Forth systems must provide a floored +division primitive +(FM/MOD), +a symmetric division primitive +(SM/REM), +and a mixed precision multiplication operator +(M*). + +

+ +This compromise protects the investment made in current Forth +applications; Forth-79 and Forth-83 programs are automatically compliant +with ANS Forth with respect to division. In practice, the rounding +direction rarely matters to applications. However, if a program +requires a specific rounding direction, it can use the floored division +primitive FM/MOD or the symmetric division primitive SM/REM to construct +a division operator of the desired flavor. This simple technique can be +used to convert Forth-79 and Forth-83 programs to ANS Forth without any +analysis of the original programs. + +

+ + +


+ +

A.3.2.2.2 Other integer operations

+
+ +Whether underflow occurs depends on the data-type of the result. For +example, the phrase +1 2 - underflows if the result is unsigned and +produces the valid signed result -1. + +

+ + +


+ +

A.3.2.3 Stacks

+
+ +The only data type in Forth which has concrete rather than abstract +existence is the stack entry. Even this primitive typing Forth only +enforces by the hard reality of stack underflow or overflow. The +programmer must have a clear idea of the number of stack entries to be +consumed by the execution of a word and the number of entries that will +be pushed back to a stack by the execution of a word. The observation +of anomalous occurrences on the data stack is the first line of defense +whereby the programmer may recognize errors in an application program. +It is also worth remembering that multiple stack errors caused by +erroneous application code are frequently of equal and opposite +magnitude, causing complementary (and deceptive) results. + +

+ +For these reasons and a host of other reasons, the one unambiguous, +uncontroversial, and indispensable programming discipline observed since +the earliest days of Forth is that of providing a stack diagram for all +additions to the application dictionary with the exception of static +constructs such as +VARIABLEs and +CONSTANTs. + +

+ + +


+ +

A.3.2.3.2 Control-flow stack

+
+ +The simplest use of control-flow words is to implement the basic control +structures shown in figure A.1. + +

+ +* + +

+    ---------------------------------------------------------------
+         |                 _____ |               _____ |
+        < >-----  IF      |     \|     BEGIN    |     \|     BEGIN
+         |      |         |  +-------+          |  +-------+
+     +-------+  |         |  |       |          |  |       |
+     |       |  |         |  +-------+          |  +-------+
+     +-------+  |         |      |              |      |
+         | _____|          -----< >    UNTIL     ------      AGAIN
+         |/       THEN           |
+         |                       |
+    ---------------------------------------------------------------
+                      Figure A.1 - The basic control-flow patterns.
+
+

+ +Figure A.1 - The basic control-flow patterns. +

+ +In control flow every branch, or transfer of control, must terminate at +some destination. A natural implementation uses a stack to remember the +origin of forward branches and the destination of backward branches. At +a minimum, only the location of each origin or destination must be +indicated, although other implementation-dependent information also may +be maintained. + +

+ +An origin is the location of the branch itself. A destination is where +control would continue if the branch were taken. A destination is +needed to resolve the branch address for each origin, and conversely, if +every control-flow path is completed no unused destinations can remain. + +

+ +With the addition of just three words +(AHEAD, +CS-ROLL and +CS-PICK), the +basic control-flow words supply the primitives necessary to compile a +variety of transportable control structures. The abilities required are +compilation of forward and backward conditional and unconditional +branches and compile-time management of branch origins and destinations. +Table A.1 shows the desired behavior. + +

+ +The requirement that control-flow words are properly balanced by other +control-flow words makes reasonable the description of a compile-time +implementation-defined control-flow stack. There is no prescription as +to how the control-flow stack is implemented, e.g., data stack, linked +list, special array. Each element of the control-flow stack mentioned +above is the same size. + +

+* + +

+                 Table A.1 - Compilation behavior of control-flow words
+   ---------------------------------------------------------------------------
+   at compile time,
+   word:    supplies:  resolves:  is used to:
+   ---------------------------------------------------------------------------
+   IF       orig                  mark origin of forward conditional branch
+   THEN                orig       resolve IF or AHEAD
+   BEGIN    dest                  mark backward destination
+   AGAIN               dest       resolve with backward unconditional branch
+   UNTIL               dest       resolve with backward conditional branch
+   AHEAD    orig                  mark origin of forward unconditional branch
+   CS-PICK                        copy item on control-flow stack
+   CS-ROLL                        reorder items on control-flow stack
+   --------------------------------------------------------------------------
+
+

+ +With these tools, the remaining basic control-structure elements, shown +in +figure A.2, +can be defined. The stack notation used here for +immediate words is ( compilation / execution ). + +

+ +

+: WHILE  ( dest -- orig dest / flag -- )
+                            \ conditional exit from loops
+	POSTPONE IF         \ conditional forward branch
+           1 CS-ROLL        \ keep dest on top
+; IMMEDIATE
+
+
+: REPEAT  ( orig dest -- / -- )
+                            \ resolve a single WHILE and return to BEGIN
+           POSTPONE AGAIN   \ uncond. backward branch to dest
+           POSTPONE THEN    \ resolve forward branch from orig
+; IMMEDIATE
+
+: ELSE  ( orig1 -- orig2 / -- )
+                            \ resolve IF supplying alternate execution
+        POSTPONE AHEAD      \ unconditional forward branch orig2
+           1 CS-ROLL        \ put orig1 back on top
+           POSTPONE THEN    \ resolve forward branch from orig1
+; IMMEDIATE
+
+ +

+* + +

+     -----------------------------------------------
+             |                 _____ |
+            < >-----  IF      |     \|        BEGIN
+             |      |         |  +-------+
+         +-------+  |         |  |       |
+         |       |  |         |  +-------+
+         +-------+  |         |      |
+             | _____|         |     < >-----  WHILE
+       _____/ /       ELSE    |      |      |
+      |      |                |  +-------+  |
+      |  +-------+            |  |       |  |
+      |  |       |            |  +-------+  |
+      |  +-------+            |      |      |
+      |_____ |                |_____/  _____|
+            \|        THEN            /       REPEAT
+             |                       |
+    ----------------------------------------------
+    Figure A.2 - Additional basic control-flow patterns.
+
+

+ +Forth control flow provides a solution for well-known problems with +strictly structured programming. + +

+ +The basic control structures can be supplemented, as shown in the +examples in +figure A.3, +with additional WHILEs in BEGIN ... UNTIL and +BEGIN ... WHILE ... REPEAT structures. However, for each additional +WHILE there must be a THEN at the end of the structure. THEN completes +the syntax with WHILE and indicates where to continue execution when the +WHILE transfers control. The use of more than one additional WHILE is +possible but not common. Note that if the user finds this use of THEN +undesirable, an alias with a more likable name could be defined. + +

+ +Additional actions may be performed between the control flow word (the +REPEAT or UNTIL) and the THEN that matches the additional WHILE. +Further, if additional actions are desired for normal termination and +early termination, the alternative actions may be separated by the +ordinary Forth ELSE. The termination actions are all specified after +the body of the loop. + +

+* + +

+    --------------------------------------------------
+     _____ |                      _____ |
+    |     \|         BEGIN       |     \|        BEGIN
+    |  +-------+                 |  +-------+
+    |  |       |                 |  |       |
+    |  +-------+                 |  +-------+
+    |      |                     |      |
+    |     < >------  WHILE       |     < >-----  WHILE
+    |      |       |             |      |      |
+    |  +-------+   |             |  +-------+  |
+    |  |       |   |             |  |       |  |
+    |  +-------+   |             |  +-------+  |
+    |      |       |             |      |      |
+    |     < >----  | WHILE        -----< >     | UNTIL
+    |      |     | |                    |      |
+    |  +-------+ | |                +-------+  |
+    |  |       | | |                |       |  |
+    |  +-------+ | |                +-------+  |
+    |      | ____| |                    | _____/
+     \____/ /      | REPEAT       _____/ /       ELSE
+           |       |             |      |
+       +-------+   |             |  +-------+
+       |       |   |             |  |       |
+       +-------+   |             |  +-------+
+           | ______/              \____ |
+           |/        THEN              \|        THEN
+           |                            |
+    ---------------------------------------------------
+    Figure A.3 - Extended control-flow pattern examples.
+
+

+ +Note that REPEAT creates an anomaly when matching the WHILE with ELSE or +THEN, most notable when compared with the BEGIN...UNTIL case. That is, +there will be one less ELSE or THEN than there are WHILEs because REPEAT +resolves one THEN. As above, if the user finds this count mismatch +undesirable, REPEAT could be replaced in-line by its own definition. + +

+ +Other loop-exit control-flow words, and even other loops, can be +defined. The only requirements are that the control-flow stack is +properly maintained and manipulated. + +

+ +The simple implementation of the ANS Forth CASE structure below is an +example of control structure extension. Note the maintenance of the +data stack to prevent interference with the possible control-flow stack +usage. + +

+ + +

+0 CONSTANT CASE IMMEDIATE  ( init count of OFs )
+
+: OF  ( #of -- orig #of+1 / x -- )
+    1+    ( count OFs )
+    >R    ( move off the stack in case the control-flow )
+          ( stack is the data stack. )
+    POSTPONE OVER  POSTPONE = ( copy and test case value)
+    POSTPONE IF    ( add orig to control flow stack )
+    POSTPONE DROP  ( discards case value if = )
+    R>             ( we can bring count back now )
+; IMMEDIATE
+
+: ENDOF ( orig1 #of -- orig2 #of )
+    >R   ( move off the stack in case the control-flow )
+         ( stack is the data stack. )
+    POSTPONE ELSE
+    R>   ( we can bring count back now )
+; IMMEDIATE
+
+: ENDCASE  ( orig1..orign #of -- )
+    POSTPONE DROP  ( discard case value )
+    0 ?DO
+      POSTPONE THEN
+    LOOP
+; IMMEDIATE
+
+ +

+ +


+ +

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: +

+ +

    +
  • Directly into the data or return stacks; +
  • Into a definition's data field if not stored by the application. +
+

+ +The read-only restrictions arise because some Forth systems run from ROM +and some share I/O buffers with other users or systems. Portable +programs cannot know which areas are affected, hence the general restrictions. + + +

+ +


+ +

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. + +

+ +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansa4.htm b/docs/reference/standards/ans94/dpansa4.htm new file mode 100644 index 00000000..9b99d1e8 --- /dev/null +++ b/docs/reference/standards/ans94/dpansa4.htm @@ -0,0 +1,45 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

A.4 Documentation requirements

+ + +
+ +

A.4.1 System documentation

+
+ + +
+ +

A.4.2 Program documentation

+
+ +
+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansa5.htm b/docs/reference/standards/ans94/dpansa5.htm new file mode 100644 index 00000000..c44ef0c3 --- /dev/null +++ b/docs/reference/standards/ans94/dpansa5.htm @@ -0,0 +1,111 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ + +

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. + +

+ +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansa6.htm b/docs/reference/standards/ans94/dpansa6.htm new file mode 100644 index 00000000..bcf31074 --- /dev/null +++ b/docs/reference/standards/ans94/dpansa6.htm @@ -0,0 +1,2043 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

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 ... ; + +

+ + +


+ +

A.6.2 Core extension words

+
+ +The words in this collection fall into several categories: +

+ +

    +
  • Words that are in common use but are deemed less essential than Core +words (e.g., +0<>); +
  • Words that are in common use but can be trivially defined from Core +words (e.g., +FALSE); +
  • Words that are primarily useful in narrowly defined types of +applications or are in less frequent use (e.g., +PARSE); +
  • Words that are being deprecated in favor of new words introduced to +solve specific problems (e.g., +CONVERT). +
+

+ +Because of the varied justifications for inclusion of these words, the +Technical Committee does not encourage implementors to offer the +complete collection, but to select those words deemed most valuable to +their clientele. + +

+ +


+A.6.2.0060 #TIB +

+ +The function of #TIB has been superseded by +SOURCE. + +

+ +


+A.6.2.0200 .( +

+ +Typical use: .( ccc) + +

+ +


+A.6.2.0210 .R +

+ +In .R, R is short for RIGHT. + +

+ +


+A.6.2.0340 2>R +

+ +Historically, 2>R has been used to implement +DO. Hence the order of +parameters on the return stack. + +

+ +The primary advantage of 2>R is that it puts the top stack entry on the +top of the return stack. For instance, a double-cell number may be +transferred to the return stack and still have the most significant cell +accessible on the top of the return stack. + +

+ +


+A.6.2.0410 2R> +

+ +Note that 2R> is not equivalent to +R> R>. Instead, it mirrors the +action of +2>R +(see A.6.2.0340). + +

+ +


+A.6.2.0455 :NONAME +

+ +:NONAME allows a user to create an execution token with the semantics of +a colon definition without an associated name. Previously, only +: +(colon) could create an execution token with these semantics. Thus, +Forth code could only be compiled using the syntax of :, that is: + + +

+	: NAME  ...  ;
+
+ +

+ +:NONAME removes this constraint and places the Forth compiler in the +hands of the programmer. + +

+ +:NONAME can be used to create application-specific programming +languages. One technique is to mix Forth code fragments with +application-specific constructs. The application-specific constructs +use :NONAME to compile the Forth code and store the corresponding +execution tokens in data structures. + +

+ +The functionality of :NONAME can be built on any Forth system. For +years, expert Forth programmers have exploited intimate knowledge of +their systems to generate unnamed code fragments. Now, this function +has been named and can be used in a portable program. + +

+ +For example, :NONAME can be used to build a table of code fragments +where indexing into the table allows executing a particular fragment. +The declaration syntax of the table is: + +

+ + +

+:NONAME .. code for command 0 .. ;  0 CMD !
+
+:NONAME .. code for command 1 .. ;  1 CMD !
+   ...
+
+:NONAME .. code for command 99 .. ; 99 CMD !
+
+   ... 5 CMD @ EXECUTE ...
+
+
+

+ +The definitions of the table building words are: + +

+CREATE CMD-TABLE  \ table for command execution tokens
+100 CELLS ALLOT
+
+: CMD ( n -- a-addr ) \ nth element address in table
+    CELLS CMD-TABLE + ;
+
+ +

+ +As a further example, a defining word can be created to allow +performance monitoring. In the example below, the number of times a +word is executed is counted. : must first be renamed to allow the +definition of the new ;. + +

+ + +

+: DOCOLON ( -- )     \ Modify CREATEd word to execute like a colon def
+     DOES> ( i*x a-addr -- j*x )
+     1 OVER +!         \ count executions
+     CELL+ @ EXECUTE   \ execute :NONAME definition
+;
+
+: OLD: : ;           \ just an alias
+
+OLD: : ( "name" -- a-addr xt colon-sys )
+                     \ begins an execution-counting colon definition
+     CREATE  HERE 0 ,  \ storage for execution counter
+     0 ,               \ storage for execution token
+     DOCOLON           \ set run time for CREATEd word
+    :NONAME           \ begin unnamed colon definition
+;
+
+

+ +( Note the placement of DOES>: DOES> must modify the CREATEd word and not +the :NONAME definition, so DOES> must execute before :NONAME.) + +

+OLD: ; ( a-addr xt colon-sys -- )
+                      \ ends an execution-counting colon definition )
+    POSTPONE ;        \ complete compilation of colon def
+    SWAP CELL+ !      \ save execution token
+;  IMMEDIATE
+
+ +

+ +The new : and ; are used just like the standard ones to define words: +

+ + +

+	... : xxx  ... ;  ...  xxx  ...
+
+ +Now however, these words may be ticked to retrieve the count (and +execution token): + + +
+	... ' xxx >BODY ? ...
+
+ +

+ +


+A.6.2.0620 ?DO +

+ +Typical use: + +: FACTORIAL ( +n1 -- +n2 ) 1 SWAP 1+ ?DO I * LOOP ; + +

+ +This word was added in response to many requests for a resolution of the +difficulty introduced by Forth-83's DO, which on a 16-bit system will +loop 65,535 times if given equal arguments. As this Standard also +encourages 32-bit systems, this behavior can be intolerable. The +Technical Committee considered applying these semantics to +DO, but +declined on the grounds that it might break existing code. + +

+ +


+A.6.2.0700 AGAIN +

+ +Typical use: : X ... BEGIN ... AGAIN ... ; + +

+ +Unless word-sequence has a way to terminate, this is an endless loop. + +

+ +


+A.6.2.0855 C" +

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

+ +It is easy to convert counted strings to pointer/length but hard to do +the opposite. C" is the only new word that uses the address of +counted string stack representation. It is provided as an aid to +porting existing programs to ANS Forth systems. It is relatively +difficult to implement C" in terms of other standard words, considering +its compile string into the current definition semantics. + +

+ +Users of C" are encouraged to migrate their application code toward the +consistent use of the preferred c-addr u stack representation +with the alternate word +S". This may be accomplished by converting +application words with counted string input arguments to use the +preferred c-addr u representation, thus eliminating the need for +C" . + +

+ +See: +A.3.1.3.4 Counted strings + +

+ +


+A.6.2.0873 CASE +

+ +Typical use: + +

+   : X ...
+       CASE
+       test1 OF ... ENDOF
+       testn OF ... ENDOF
+       ... ( default )
+       ENDCASE ...
+   ;
+
+ +

+ +


+A.6.2.0945 COMPILE, +

+ +COMPILE, is the compilation equivalent of +EXECUTE. In many cases, it is +possible to compile a word by using +POSTPONE without resorting to the +use of COMPILE,. However, the use of POSTPONE requires that the name of +the word must be known at compile time, whereas COMPILE, allows the word +to be located at any time. It is sometime possible to use +EVALUATE to +compile a word whose name is not known until run time. This has two +possible problems: + +

    +
  • EVALUATE is slower than COMPILE, because a dictionary search is +required. +
  • The current search order affects the outcome of EVALUATE. +
+

+ +In traditional threaded-code implementations, compilation is performed +by +, (comma). +This usage is not portable; it doesn't work for +subroutine-threaded, native code, or relocatable implementations. Use +of COMPILE, is portable. + +

+ +In most systems it is possible to implement COMPILE, so it will generate +code that is optimized to the same extent as code that is generated by +the normal compilation process. However, in some implementations there +are two different tokens corresponding to a particular definition +name: the normal execution token that is used while interpreting +or with EXECUTE, and another compilation token that is used while +compiling. It is not always possible to obtain the compilation token +from the execution token. In these implementations, COMPILE, might not +generate code that is as efficient as normally compiled code. + +

+ +


+A.6.2.0970 CONVERT +

+ +CONVERT may be defined as follows: + + +

+	: CONVERT   CHAR+ 65535 >NUMBER DROP ;
+
+ +

+ +


+A.6.2.1342 ENDCASE +

+ +Typical use: + +

+   : X ...
+       CASE
+       test1 OF ... ENDOF
+       testn OF ... ENDOF
+       ... ( default )
+       ENDCASE ...
+   ;
+
+ +

+ +


+A.6.2.1343 ENDOF +

+ +Typical use: + +

+: X ...
+   CASE
+   test1 OF ... ENDOF
+   testn OF ... ENDOF
+   ... ( default )
+   ENDCASE ...
+;
+
+ +

+ +


+A.6.2.1390 EXPECT +

+ +Specification of positive integer counts (+n) for EXPECT 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. + +

+ +


+A.6.2.1850 MARKER +

+ +As dictionary implementations have gotten more elaborate and in some +cases have used multiple address spaces, +FORGET has become prohibitively +difficult or impossible to implement on many Forth systems. MARKER +greatly eases the problem by making it possible for the system to +remember landmark information in advance that specifically marks +the spots where the dictionary may at some future time have to be +rearranged. + +

+ +


+A.6.2.1950 OF +

+ +Typical use: + +

+   : X ...
+       CASE
+       test1 OF ... ENDOF
+       testn OF ... ENDOF
+       ... ( default )
+       ENDCASE ...
+   ;
+
+ +

+ +


+A.6.2.2000 PAD +

+ +PAD has been available as scratch storage for strings since the earliest +Forth implementations. It was brought to our attention that many +programmers are reluctant to use PAD, fearing incompatibilities with +system uses. PAD is specifically intended as a programmer convenience, +however, which is why we documented the fact that no standard words use +it. + +

+ +


+A.6.2.2008 PARSE +

+ +Typical use: char PARSE ccc<char> + +

+ +The traditional Forth word for parsing is +WORD. PARSE solves the +following problems with WORD: + +

+ +a) WORD always skips leading delimiters. This behavior is appropriate +for use by the text interpreter, which looks for sequences of non-blank +characters, but is inappropriate for use by words like ( , .( , and ." . +Consider the following (flawed) definition of .( : + + +

+	: .(   [CHAR] )  WORD COUNT TYPE ;  IMMEDIATE
+
+ +

+ +This works fine when used in a line like: + + +

+	.( HELLO)   5 .
+
+ +

+ +but consider what happens if the user enters an empty string: + + +

+	.( )   5 .
+
+ +

+ +The definition of .( shown above would treat the ) as a leading +delimiter, skip it, and continue consuming characters until it located +another ) that followed a non-) character, or until the parse area was +empty. In the example shown, the 5 . would be treated as part of the +string to be printed. + +

+ +With PARSE, we could write a correct definition of .( : + + +

+	: .(   [CHAR] ) PARSE TYPE ; IMMEDIATE
+
+ +

+ +This definition avoids the empty string anomaly. + +

+ +b) WORD returns its result as a counted string. This has four bad +effects: + +

+ +1) The characters accepted by WORD must be copied from the input buffer +into a temporary buffer, in order to make room for the count character that +must be at the beginning of the counted string. The copy step is inefficient, +compared to PARSE, which leaves the string in the input buffer and doesn't +need to copy it anywhere. + +

+ +2) WORD must be careful not to store too many characters into the +temporary buffer, thus overwriting something beyond the end of the buffer. +This adds to the overhead of the copy step. (WORD may have to scan a lot of +characters before finding the trailing delimiter.) + +

+ +3) The count character limits the length of the string returned by WORD +to 255 characters (longer strings can easily be stored in blocks!). This +limitation does not exist for PARSE. + +

+ +4) The temporary buffer is typically overwritten by the next use of WORD. +This introduces a temporal dependency; the value returned by WORD is only +valid for a limited duration. PARSE has a temporal dependency, too, related +to the lifetime of the input buffer, but that is less severe in most cases +than WORD's temporal dependency. + +

+ +The behavior of WORD with respect to skipping leading delimiters is +useful for parsing blank-delimited names. Many system implementations +include an additional word for this purpose, similar to PARSE with +respect to the c-addr u return value, but without an explicit +delimiter argument (the delimiter set is implicitly white space), +and which does skip leading delimiters. A common description for this +word is: + + +

+	PARSE-WORD  ( <spaces>name -- c-addr u )
+
+ +

+ +Skip leading spaces and parse name delimited by a space. c-addr is the +address within the input buffer and u is the length of the selected string. +If the parse area is empty, the resulting string has a zero length. + +

+ +If both PARSE and PARSE-WORD are present, the need for WORD is largely +eliminated. + +

+ +


+A.6.2.2030 PICK +

+ +0 PICK is equivalent to +DUP and 1 PICK is equivalent to +OVER. + +

+ +


+A.6.2.2040 QUERY +

+ +The function of QUERY may be performed with +ACCEPT and +EVALUATE. + +

+ +


+A.6.2.2125 REFILL +

+ +This word is a useful generalization of +QUERY. Re-defining QUERY to +meet this specification would have broken existing code. REFILL is +designed to behave reasonably for all possible input sources. If the +input source is coming from the user, as with QUERY, REFILL could still +return a false value if, for instance, a communication channel closes so +that the system knows that no more input will be available. + +

+ +


+A.6.2.2150 ROLL +

+ +2 ROLL is equivalent to +ROT, +1 ROLL is equivalent to +SWAP and 0 ROLL is +a null operation. + +

+ +


+A.6.2.2182 SAVE-INPUT +

+ +SAVE-INPUT and +RESTORE-INPUT +allow the same degree of input source +repositioning within a text file as is available with +BLOCK input. +SAVE-INPUT and RESTORE-INPUT hide the details of the operations +necessary to accomplish this repositioning, and are used the same way +with all input sources. This makes it easier for programs to reposition +the input source, because they do not have to inspect several variables +and take different action depending on the values of those variables. + +

+ +SAVE-INPUT and RESTORE-INPUT are intended for repositioning within a +single input source; for example, the following scenario is NOT allowed +for a Standard Program: + +

+   : XX
+       SAVE-INPUT  CREATE
+       S" RESTORE-INPUT" EVALUATE
+       ABORT" couldn't restore input"
+   ;
+
+ +

+ +This is incorrect because, at the time RESTORE-INPUT is executed, the +input source is the string via +EVALUATE, which is not the same input +source that was in effect when SAVE-INPUT was executed. + +

+ +The following code is allowed: + + +

+: XX
+    SAVE-INPUT  CREATE
+    S" .( Hello)" EVALUATE
+    RESTORE-INPUT ABORT" couldn't restore input"
+;
+
+ +

+ +After EVALUATE returns, the input source specification is restored to +its previous state, thus SAVE-INPUT and RESTORE-INPUT are called with +the same input source in effect. + +

+ +In the above examples, the EVALUATE phrase could have been replaced by a +phrase involving +INCLUDE-FILE +and the same rules would apply. + +

+ +The Standard does not specify what happens if a program violates the +above rules. A Standard System might check for the violation and return +an exception indication from RESTORE-INPUT, or it might fail in an +unpredictable way. + +

+ +The return value from RESTORE-INPUT is primarily intended to report the +case where the program attempts to restore the position of an input +source whose position cannot be restored. The keyboard might be such an +input source. + +

+ +Nesting of SAVE-INPUT and RESTORE-INPUT is allowed. For example, the +following situation works as expected: + +

+: XX
+    SAVE-INPUT
+    S" f1" INCLUDED      \ The file "f1" includes:
+    \   ... SAVE-INPUT ... RESTORE-INPUT ...
+    \ End of file "f1"
+    RESTORE-INPUT  ABORT" couldn't restore input"
+;
+
+ +

+ +In principle, RESTORE-INPUT could be implemented to always fail, e.g.: + +

+: RESTORE-INPUT  ( x1 ... xn n -- flag )
+    0 ?DO DROP LOOP TRUE
+;
+
+ +

+ +Such an implementation would not be useful in most cases. It would be +preferable for a system to leave SAVE-INPUT and RESTORE-INPUT undefined, +rather than to create a useless implementation. In the absence of the +words, the application programmer could choose whether or not to create +dummy implementations or to work-around the problem in some other +way. + +

+ +Examples of how an implementation might use the return values from +SAVE-INPUT to accomplish the save/restore function: + +

+ + +

+Input Source    possible stack values
+------------    ---------------------
+block           >IN @  BLK @  2
+EVALUATE        >IN @  1
+keyboard        >IN @  1
+text file       >IN @  lo-pos  hi-pos  3
+
+ +

+ +These are examples only; a Standard Program may not assume any particular +meaning for the individual stack items returned by SAVE-INPUT. + +

+ +


+A.6.2.2290 TIB +

+ +The function of TIB has been superseded by +SOURCE. + +

+ +


+A.6.2.2295 TO +

+ +Historically, some implementations of TO have not explicitly parsed. +Instead, they set a mode flag that is tested by the subsequent execution +of name. ANS Forth explicitly requires that TO must parse, so that TO's +effect will be predictable when it is used at the end of the parse area. + +

+ +Typical use: x TO name + +

+ +


+A.6.2.2298 TRUE +

+ +TRUE is equivalent to the phrase 0 0=. + +

+ +


+A.6.2.2405 VALUE +

+ +Typical use: + +

+0 VALUE DATA
+
+: EXCHANGE ( n1 -- n2 ) DATA SWAP TO DATA ;
+
+ +

+ +EXCHANGE leaves n1 in DATA and returns the prior value n2. + +

+ +


+A.6.2.2440 WITHIN +

+ +We describe WITHIN without mentioning circular number spaces (an +undefined term) or providing the code. Here is a number line with the +overflow point (o) at the far right and the underflow point (u) at the +far left: + +

+u--------------------------------------------------------------o
+
+ +

+ +There are two cases to consider: either the n2|u2..n3|u3 range straddles +the overflow/underflow points or it does not. Lets examine the +non-straddle case first: + +

+u-------------------[.....................)------------------------o
+
+ +

+ +The [ denotes n2|u2, the ) denotes n3|u3, and the dots and [ are numbers +WITHIN the range. n3|u3 is greater than n2|u2, so the following tests +will determine if n1|u1 is WITHIN n2|u2 and n3|u3: + +

+

+           n2|u2 < n1|u1  and  n1|u1 < n3|u3.
+
+

+ +In the case where the comparison range straddles the overflow/underflow +points: +

+ +u...............)-----------------------------[........................o + +

+ +n3|u3 is less than n2|u2 and the following tests will determine if n1|u1 is +WITHIN n2|u2 and n3|u3: + +

+

+           n2|u2 > n1|u1  and  n1|u1 > n3|u3.
+
+

+ + +WITHIN must work for both signed and unsigned arguments. One obvious +implementation does not work: + +

+: WITHIN  ( test low high -- flag )
+    >R  OVER < 0= ( test flag1 )
+    SWAP R> <     ( flag1 flag2 )
+    AND
+;
+
+ +

+ +Assume two's-complement arithmetic on a 16-bit machine, and consider the +following test: + + +

+	33000  32000 34000  WITHIN
+
+ +

+ +The above implementation returns false for that test, even though the +unsigned number 33000 is clearly within the range {{32000 .. 34000}}. + +

+ +The problem is that, in the incorrect implementation, the signed +comparison +< gives the wrong answer when 32000 is compared to 33000, +because when those numbers are treated as signed numbers, 33000 is +treated as negative 32536, while 32000 remains positive. + +

+ +Replacing < with +U< +in the above implementation makes it work with +unsigned numbers, but causes problems with certain signed number ranges; +in particular, the test: + + +

+	1  -5  5  WITHIN
+
+ +

+ +would give an incorrect answer. + +

+ +For two's-complement machines that ignore arithmetic overflow (most +machines), the following implementation works in all cases: + +

+:  WITHIN  ( test low high -- flag )   OVER - >R - R>  U<  ;
+
+
+

+ +


+A.6.2.2530 [COMPILE] +

+ +Typical use: : name2 ... [COMPILE] name1 ... ; IMMEDIATE + +

+ +


+A.6.2.2535 \ +

+ +Typical use: 5 CONSTANT THAT \ THIS IS A COMMENT ABOUT THAT + +

+ +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansa7.htm b/docs/reference/standards/ans94/dpansa7.htm new file mode 100644 index 00000000..163be09a --- /dev/null +++ b/docs/reference/standards/ans94/dpansa7.htm @@ -0,0 +1,89 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ + +

A.7 The optional Block word set

+ +Early Forth systems ran stand-alone, with no host OS. Blocks of 1024 +bytes were designed as a convenient unit of disk, and most native Forth +systems still use them. It is relatively easy to write a native disk +driver that maps head/track/sector addresses to block numbers. Such +disk drivers are extremely fast in comparison with conventional +file-oriented operating systems, and security is high because there is +no reliance on a disk map. + +

+ +Today many Forth implementations run under host operating systems, +because the compatibility they offer the user outweighs the performance +overhead. Many people who use such systems prefer using host OS files +only; however, people who use both native and non-native Forths need a +compatible way of accessing disk. The Block Word set includes the most +common words for accessing program source and data on disk. + +

+ +In order to guarantee that Standard Programs that need access to mass +storage have a mechanism appropriate for both native and non-native +implementations, ANS Forth requires that the Block word set be available +if any mass storage facilities are provided. On non-native +implementations, blocks normally reside in host OS files. + +

+ +


+ +

A.7.2 Additional terms

+
+ +
block +
Many Forth systems use blocks to contain program source. Conventionally +such blocks are formatted for editing as 16 lines of 64 characters. +Source blocks are often referred to as screens.
+ +

+ +


+ +

A.7.6 Glossary

+
+ + +
+ +A.7.6.2.2190 SCR + +

+ +SCR is short for screen. + +

+ +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansa8.htm b/docs/reference/standards/ans94/dpansa8.htm new file mode 100644 index 00000000..fdfb40c1 --- /dev/null +++ b/docs/reference/standards/ans94/dpansa8.htm @@ -0,0 +1,162 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

A.8 The optional Double-Number word set

+ +Forth systems on 8-bit and 16-bit processors often find it necessary to +deal with double-length numbers. But many Forths on small embedded +systems do not, and many users of Forth on systems with a cell size of +32-bits or more find that the necessity for double-length numbers is +much diminished. Therefore, we have factored the words that manipulate +double-length entities into this optional word set. + +

+ +Please note that the naming convention used in this word set conveys +some important information: + +

+ +1. Words whose names are of the form 2xxx deal with cell pairs, where +the relationship between the cells is unspecified. They may be +two-vectors, double-length numbers, or any pair of cells that it is +convenient to manipulate together. + +

+ +2. Words with names of the form Dxxx deal specifically with +double-length integers. + +

+ +3. Words with names of the form Mxxx deal with some combination of +single and double integers. The order in which these appear on the +stack is determined by long-standing common practice. + +

+ +Refer to +A.3.1 for a discussion of data types in Forth. + +

+ +


+ +

A.8.6 Glossary

+
+ + +
+A.8.6.1.0360 2CONSTANT +

+ +Typical use: x1 x2 2CONSTANT name + +

+ +


+A.8.6.1.0390 2LITERAL +

+ +Typical use: : X ... [ x1 x2 ] 2LITERAL ... ; + +

+ +


+A.8.6.1.0440 2VARIABLE +

+ +Typical use: 2VARIABLE name + +

+ +


+A.8.6.1.1070 D.R +

+ +In D.R, the R is short for RIGHT. + +

+ +


+A.8.6.1.1090 D2* +

+ +See: +A.6.1.0320 2* for applicable +discussion. + +

+ +


+A.8.6.1.1100 D2/ +

+ +See: +A.6.1.0330 2/ for applicable +discussion. + +

+ +


+A.8.6.1.1140 D>S +

+ +There exist number representations, e.g., the sign-magnitude +representation, where reduction from double- to single-precision cannot +simply be done with +DROP. +This word, equivalent to DROP on two's +complement systems, desensitizes application code to number +representation and facilitates portability. + +

+ +


+A.8.6.1.1820 M*/ +

+ +M*/ was once described by Chuck Moore as the most useful arithmetic +operator in Forth. It is the main workhorse in most computations +involving double-cell numbers. Note that some systems allow signed +divisors. This can cost a lot in performance on some CPUs. The +requirement for a positive divisor has not proven to be a problem. + +

+ +


+A.8.6.1.1830 M+ +

+ +M+ is the classical method for integrating. + +

+ +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansa9.htm b/docs/reference/standards/ans94/dpansa9.htm new file mode 100644 index 00000000..2a437d1a --- /dev/null +++ b/docs/reference/standards/ans94/dpansa9.htm @@ -0,0 +1,292 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

A.9 The optional Exception word set

+ +CATCH and +THROW +provide a reliable mechanism for handling exceptions, +without having to propagate exception flags through multiple levels of +word nesting. It is similar in spirit to the non-local return +mechanisms of many other languages, such as C's setjmp() and longjmp(), +and LISP's CATCH and THROW. In the Forth context, THROW may be +described as a multi-level +EXIT, +with CATCH marking a location to +which a THROW may return. + +

+ +Several similar Forth multi-level EXIT exception-handling schemes +have been described and used in past years. It is not possible to +implement such a scheme using only standard words (other than CATCH and +THROW), because there is no portable way to unwind the return +stack to a predetermined place. + +

+ +THROW also provides a convenient implementation technique for the +standard words +ABORT and +ABORT", +allowing an application to define, +through the use of CATCH, the behavior in the event of a system ABORT. + +

+ +This sample implementation of CATCH and THROW uses the non-standard +words described below. They or their equivalents are available in many +systems. Other implementation strategies, including directly saving the +value of +DEPTH, +are possible if such words are not available. + +

+ +SP@ ( -- addr ) returns the +address corresponding to the top of data stack. + +

+ +SP! ( addr -- ) sets the stack pointer to addr, thus restoring the stack +depth to the same depth that existed just before addr was acquired by +executing SP@. + +

+ +RP@ ( -- addr ) returns the address corresponding to the top of return +stack. + +

+ +RP! ( addr -- ) sets the return stack pointer to addr, thus restoring the +return stack depth to the same depth that existed just before addr was +acquired by executing RP@. + +

+VARIABLE HANDLER   0 HANDLER !  \ last exception handler
+
+: CATCH  ( xt -- exception# | 0 ) \ return addr on stack
+    SP@ >R         ( xt ) \ save data stack pointer
+    HANDLER @ >R   ( xt ) \ and previous handler
+    RP@ HANDLER !  ( xt ) \ set current handler
+    EXECUTE        ( )    \ execute returns if no THROW
+    R> HANDLER !   ( )    \ restore previous handler
+    R> DROP        ( )    \ discard saved stack ptr
+    0              ( 0 )  \ normal completion
+;
+
+: THROW  ( ??? exception# -- ??? exception# )
+    ?DUP IF          ( exc# ) \ 0 THROW is no-op
+    HANDLER @ RP!  ( exc# ) \ restore prev return stack
+    R> HANDLER !   ( exc# ) \ restore prev handler
+    R> SWAP >R     ( saved-sp ) \ exc# on return stack
+    SP! DROP R>    ( exc# ) \ restore stack
+        \  Return to the caller of CATCH because return
+        \  stack is restored to the state that existed
+        \  when CATCH began execution
+THEN
+;
+
+ +

+ +In a multi-tasking system, the HANDLER variable should be in the +per-task variable area (i.e., a user variable). + +

+ +This sample implementation does not explicitly handle the case in which +CATCH has never been called (i.e., the ABORT behavior). One solution is +to add the following code after the IF in THROW: + + +

+	HANDLER @ 0= IF ( empty the stack ) QUIT THEN
+
+ +

+ +Another solution is to execute CATCH within +QUIT, so that there is +always an exception handler of last resort present. For example: + +

+: QUIT      ( empty the return stack and )
+            ( set the input source to the user input device )
+    POSTPONE [
+    BEGIN
+      REFILL
+    WHILE
+      ['] INTERPRET CATCH
+      CASE
+      0 OF STATE @ 0= IF ." OK" THEN CR  ENDOF
+     -1 OF ( Aborted) ENDOF
+     -2 OF ( display  message from ABORT" ) ENDOF
+      ( default ) DUP ." Exception # "  .
+      ENDCASE
+    REPEAT BYE
+;
+
+ +

+ +This example assumes the existance of a system-implementation word +INTERPRET that embodies the text interpreter semantics described in +3.4 +The Forth text interpreter. Note that this implementation of QUIT +automatically handles the emptying of the stack and return stack, due to +THROW's inherent restoration of the data and return stacks. Given this +definition of QUIT, it's easy to define: + + +

+	: ABORT  -1 THROW ;
+
+ +

+ +In systems with other stacks in addition to the data and return stacks, +the implementation of CATCH and THROW must save and restore those stack +pointers as well. Such an extended version can be built on top +of this basic implementation. For example, with another stack pointer +accessed with FP@ and FP! only CATCH needs to be redefined: + +

+: CATCH  ( xt -- exception# | 0 )
+    FP@ >R  CATCH  R> OVER IF FP! ELSE DROP THEN ;
+
+ +

+ +No change to THROW is necessary in this case. Note that, as with all +redefinitions, the redefined version of CATCH will only be available to +definitions compiled after the redefinition of CATCH. + +

+ +CATCH and THROW provide a convenient way for an implementation to +clean up the state of open files if an exception occurs during +the text interpretation of a file with +INCLUDE-FILE. The implementation +of INCLUDE-FILE may guard (with CATCH) the word that performs the text +interpretation, and if CATCH returns an exception code, the file may be +closed and the exception reTHROWn so that the files being included at an +outer nesting level may be closed also. Note that the Standard allows, +but does not require, INCLUDE-FILE to close its open files if an +exception occurs. However, it does require INCLUDE-FILE to unnest the +input source specification if an exception is THROWn. + +

+ +


+ +

A.9.3 Additional usage requirements

+
+ +One important use of an exception handler is to maintain program control +under many conditions which +ABORT. This is practicable only if a range +of codes is reserved. Note that an application may overload many +standard words in such a way as to +THROW ambiguous conditions not +normally THROWn by a particular system. + +

+ +


+ +

A.9.3.6 Exception handling

+
+ +The method of accomplishing this coupling is implementation dependent. +For example, +LOAD +could know about +CATCH and +THROW (by using +CATCH itself, for example), or CATCH and THROW could know about +LOAD (by maintaining input source nesting information in a data +structure known to THROW, for example). Under these circumstances it is +not possible for a Standard Program to define words such as LOAD in a +completely portable way. + +

+ +


+ +

A.9.6 Glossary

+
+ + +
+A.9.6.1.2275 THROW +

+ +If THROW is executed with a non zero argument, the effect is as if the +corresponding +CATCH +had returned it. In that case, the stack depth is +the same as it was just before CATCH began execution. The values of the +i*x stack arguments could have been modified arbitrarily during the +execution of xt. In general, nothing useful may be done with those +stack items, but since their number is known (because the stack depth is +deterministic), the application may +DROP them to return to a predictable +stack state. + +

+ +Typical use: + +

+: could-fail ( -- char )
+    KEY DUP [CHAR] Q =  IF  1 THROW THEN ;
+
+: do-it ( a b -- c)   2DROP could-fail ;
+
+: try-it ( --)
+    1 2 ['] do-it  CATCH  IF ( x1 x2 )
+        2DROP ." There was an exception" CR
+    ELSE ." The character was " EMIT CR
+    THEN
+;
+
+: retry-it ( -- )
+    BEGIN  1 2 ['] do-it CATCH  WHILE
+       ( x1 x2) 2DROP  ." Exception, keep trying" CR
+    REPEAT ( char )
+    ." The character was " EMIT CR
+;
+
+ +

+ +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansb.htm b/docs/reference/standards/ans94/dpansb.htm new file mode 100644 index 00000000..07e13af8 --- /dev/null +++ b/docs/reference/standards/ans94/dpansb.htm @@ -0,0 +1,225 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

B. Bibliography (informative annex)

+ + +
+ +

Industry standards

+
+ +Forth-77 Standard, Forth Users Group, FST-780314. + +

+ +Forth-78 Standard, +Forth International Standards Team. + +

+ +Forth-79 Standard, Forth Standards Team. + +

+ +Forth-83 Standard and Appendices, Forth Standards Team. + +

+ +The standards referenced in this section were developed by the Forth +Standards Team, a volunteer group which included both implementors and +users. This was a volunteer organization operating under its own +charter and without any formal ties to ANSI, IEEE or any similar +standards body. Several members of the Forth Standards Team have also +been members of the X3J14 Technical Committee. + +

+ + +


+ +

Books

+
+ +Brodie, L. Starting FORTH (2nd ed). +Englewood Cliffs, NJ: Prentice Hall, +1987. + +

+ +Brodie, L. Thinking FORTH. +Englewood Cliffs, NJ: Prentice Hall, 1984. + +

+ +Feierbach, G. and Thomas, P. Forth Tools & Applications. +Reston, VA: Reston Computer Books, 1985. + +

+ +Haydon, Dr. Glen B. All About FORTH, Third Edition. +La Honda, CA: 1990. + +

+ +Kelly, Mahlon G. and Spies, N. FORTH: A Text and Reference. +Englewood Cliffs, NJ: Prentice Hall, 1986. + +

+ +Knecht, K. Introduction to Forth. Indiana: Howard Sams & Co., +1982. + +

+ +Koopman, P. Stack Computers, The New Wave. +Chichester, West Sussex, +England: Ellis Horwood Ltd. 1989 + +

+ +Martin, Thea, editor. A Bibliography of Forth References, Third +Edition. Rochester, New York: Institute of Applied Forth Research, +1987. + +

+ +McCabe, C. K. Forth Fundamentals (2 volumes/). +Oregon: Dilithium Press, 1983. + +

+ +Pountain, R. Object Oriented Forth. +London, England: Academic Press, 1987. + +

+ +Ouverson, Marlin, editor. Dr. Dobbs Toolbook of Forth. +Redwood City, CA: M&T Press, Vol. 1, 1986; Vol. 2, 1987. + +

+ +Terry, J. D. Library of Forth Routines and Utilities. +New York: Shadow Lawn Press, 1986 + +

+ +Tracy, M. and Anderson, A. Mastering FORTH (revised ed). +New York: Brady Books, 1989. + +

+ +Winfield, A. The Complete Forth. +New York: Wiley Books, 1983. + +

+ +


+ +

Journals, magazines and newsletters

+
+ +Forsley, Lawrence P., Conference Chairman. Rochester Forth Conference +Proceedings. Rochester, New York: Institute of Applied Forth Research, +1981 to present. + +

+ +Forsley, Lawrence P., Editor-in-Chief. The Journal of Forth Application +and Research. Rochester, New York: Institute of Applied Forth Research, +1983 to present. + +

+ +Frenger, Paul, editor. SIGForth Newsletter. New York, NY: Association +for Computing Machinery, 1989 to present. + +

+ +Ouverson, Marlin, editor. Forth Dimensions. San Jose, CA: The Forth +Interest Group, 1978 to present. + +

+ +Reiling, Robert, editor. FORML Conference Proceedings. San Jose, CA: +The Forth Interest Group, 1980 to present. + +

+ +Ting, Dr. C. H., editor. More on Forth Engines. San Mateo, CA: +Offete Enterprises, 1986 to present. + +

+ + +


+ +

Selected articles

+
+ +Hayes, J.R. Postpone Proceedings of the 1989 Rochester Forth +Conference. Rochester, New York: Institute for Applied Forth Research, +1989. + +

+ +Kelly, Guy M. Forth. McGraw-Hill Personal Computer Programming +Encyclopedia - Languages and Operation Systems. New York: McGraw-Hill, +1985. + +

+ +Kogge, P. M. An Architectural Trail to Threaded Code Systems. +IEEE Computer (March, 1982). + +

+ +Moore, C. H. The Evolution of FORTH - An Unusual Language. Byte +(August 1980). + +

+ +Rather, E. D. Forth Programming Language. Encyclopedia of +Physical Science & Technology (Vol. 5). New York: Academic Press, +1987. + +

+ +Rather, E. D. FORTH. Computer Programming Management. Auerbach +Publishers, Inc., 1985. + +

+ +Rather, E. D.; Colburn, D. R.; Moore, C. H. The Evolution of +FORTH. ACM SIGPLAN Notices. (Vol. 28, No. 3, March 1993). + + + +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansc.htm b/docs/reference/standards/ans94/dpansc.htm new file mode 100644 index 00000000..dfa20aac --- /dev/null +++ b/docs/reference/standards/ans94/dpansc.htm @@ -0,0 +1,1042 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

C. Perspective (informative annex)

+ +The purpose of this section is to provide an informal overview of Forth as a +language, illustrating its history, most prominent features, usage, and common +implementation techniques. Nothing in this section should be considered as +binding upon either implementors or users. A list of books and articles is +given in Annex B for those interested in learning more about Forth. + +

+ +


+ +

C.1 Features of Forth

+
+ +Forth provides an interactive programming environment. Its primary uses have +been in scientific and industrial applications such as instrumentation, +robotics, process control, graphics and image processing, artificial +intelligence and business applications. The principal advantages of Forth +include rapid, interactive software development and efficient use of computer +hardware. + +

+ +Forth is often spoken of as a language because that is its most visible +aspect. But in fact, Forth is both more and less than a conventional +programming language: more in that all the capabilities normally associated +with a large portfolio of separate programs (compilers, editors, etc.) are +included within its range and less in that it lacks (deliberately) the complex +syntax characteristic of most high-level languages. + +

+ +The original implementations of Forth were stand-alone systems that included +functions normally performed by separate operating systems, editors, +compilers, assemblers, debuggers and other utilities. A single simple, +consistent set of rules governed this entire range of capabilities. Today, +although very fast stand-alone versions are still marketed for many +processors, there are also many versions that run co-resident with +conventional operating systems such as MS-DOS and UNIX. + +

+ +Forth is not derived from any other language. As a result, its appearance and +internal characteristics may seem unfamiliar to new users. But Forth's +simplicity, extreme modularity, and interactive nature offset the initial +strangeness, making it easy to learn and use. A new Forth programmer must +invest some time mastering its large command repertoire. After a month or so +of full-time use of Forth, that programmer could understand more of its +internal working than is possible with conventional operating systems and +compilers. + +

+ +The most unconventional feature of Forth is its extensibility. The +programming process in Forth consists of defining new words - +actually new commands in the language. These may be defined in terms of +previously defined words, much as one teaches a child concepts by +explaining them in terms of previously understood concepts. Such words +are called high-level definitions. Alternatively, new words may +also be defined in assembly code, since most Forth implementations +include an assembler for the host processor. + +

+ +This extensibility facilitates the development of special application +languages for particular problem areas or disciplines. + +

+ +Forth's extensibility goes beyond just adding new commands to the language. +With equivalent ease, one can also add new kinds of words. That is, one may +create a word which itself will define words. In creating such a defining +word the programmer may specify a specialized behavior for the words it will +create which will be effective at compile time, at run-time, or both. This +capability allows one to define specialized data types, with complete control +over both structure and behavior. Since the run-time behavior of such words +may be defined either in high-level or in code, the words created by this new +defining word are equivalent to all other kinds of Forth words in performance. +Moreover, it is even easy to add new compiler directives to implement special +kinds of loops or other control structures. + +

+ +Most professional implementations of Forth are written in Forth. Many +Forth systems include a meta-compiler which allows the user to +modify the internal structure of the Forth system itself. + +

+ +


+ +

C.2 History of Forth

+
+ +Forth was invented by Charles H. Moore. A direct outgrowth of Moore's work in +the 1960's, the first program to be called Forth was written in about 1970. +The first complete implementation was used in 1971 at the National Radio +Astronomy Observatory's 11-meter radio telescope in Arizona. This system was +responsible for pointing and tracking the telescope, collecting data and +recording it on magnetic tape, and supporting an interactive graphics terminal +on which an astronomer could analyze previously recorded data. The +multi-tasking nature of the system allowed all these functions to be performed +concurrently, without timing conflicts or other interference - a very advanced +concept for that time. + +

+ +The system was so useful that astronomers from all over the world began asking +for copies. Its use spread rapidly, and in 1976 Forth was adopted as a +standard language by the International Astronomical Union. + +

+ +In 1973, Moore and colleagues formed FORTH, Inc. to explore commercial +uses of the language. FORTH, Inc. developed multi-user versions of +Forth on minicomputers for diverse projects ranging from data bases to +scientific applications such as image processing. In 1977, FORTH, Inc. +developed a version for the newly introduced 8-bit microprocessors +called microFORTH, which was successfully used in embedded +microprocessor applications in the United States, Britain and Japan. + +

+ +Stimulated by the volume marketing of microFORTH, a group of computer +hobbyists in Northern California became interested in Forth, and in 1978 +formed the Forth Interest Group (FIG). They developed a simplified model +which they implemented on several microprocessors and published listings and +disks at very low cost. Interest in Forth spread rapidly, and today there are +chapters of the Forth Interest Group throughout the U.S. and in over fifteen +countries. + +

+ +By 1980, a number of new Forth vendors had entered the market with versions of +Forth based upon the FIG model. Primarily designed for personal computers, +these relatively inexpensive Forth systems have been distributed very widely. + +

+ + +


+ +

C.3 Hardware implementations of Forth

+
+ +The internal architecture of Forth simulates a computer with two stacks, a set +of registers, and other standardized features. As a result, it was almost +inevitable that someone would attempt to build a hardware representation of an +actual Forth computer. + +

+ +In the early 1980's, Rockwell produced a 6502-variant with Forth primitives in +on-board ROM, the Rockwell 65F11. This chip has been used successfully in +many embedded microprocessor applications. In the mid-1980's Zilog developed +the z8800 (Super8) which offered ENTER (nest), EXIT (unnest) and NEXT in +microcode. + +

+ +In 1981, Moore undertook to design a chip-level implementation of the Forth +virtual machine. Working first at FORTH, Inc. and subsequently with the +start-up company NOVIX, formed to develop the chip, Moore completed the design +in 1984, and the first prototypes were produced in early 1985. More recently, +Forth processors have been developed by Harris Semiconductor Corp., Johns +Hopkins University, and others. + +

+ + + +


+ +

C.4 Standardization efforts

+
+ +The first major effort to standardize Forth was a meeting in Utrecht in 1977. +The attendees produced a preliminary standard, and agreed to meet the +following year. The 1978 meeting was also attended by members of the newly +formed Forth Interest Group. In 1979 and 1980 a series of meetings attended +by both users and vendors produced a more comprehensive standard called +Forth-79. + +

+ +Although Forth-79 was very influential, many Forth users and vendors found +serious flaws in it, and in 1983 a new standard called Forth-83 was released. + +

+ +Encouraged by the widespread acceptance of Forth-83, a group of users and +vendors met in 1986 to investigate the feasibility of an American National +Standard. The X3J14 Technical Committee for ANS Forth held its first meeting +in 1987. This Standard is the result. + +

+ + +


+ +

C.5 Programming in Forth

+
+ +Forth is an English-like language whose elements (called words) +are named data items, procedures, and defining words capable of creating +data items with customized characteristics. Procedures and defining +words may be defined in terms of previously defined words or in machine +code, using an embedded assembler. + +

+ +Forth words are functionally analogous to subroutines in other +languages. They are also equivalent to commands in other languages - +Forth blurs the distinction between linguistic elements and functional +elements. + +

+ +Words are referred to either from the keyboard or in program source by +name. As a result, the term word is applied both to program (and +linguistic) units and to their text names. In parsing text, Forth +considers a word to be any string of characters bounded by spaces. +There are a few special characters that cannot be included in a word or +start a word: space (the universal delimiter), CR (which ends terminal +input), and backspace or DEL (for backspacing during keyboard input). +Many groups adopt naming conventions to improve readability. Words +encountered in text fall into three categories: defined words (i.e., +Forth routines), numbers, and undefined words. For example, here are +four words: + + +

+	HERE      DOES>      !      8493
+
+ +

+ +The first three are standard-defined words. This means that they have +entries in Forth's dictionary, described below, explaining what Forth is +to do when these words are encountered. The number 8493 will +presumably not be found in the dictionary, and Forth will convert it to +binary and place it on its push-down stack for parameters. When Forth +encounters an undefined word and cannot convert it to a number, the word +is returned to the user with an exception message. + +

+ +Architecturally, Forth words adhere strictly to the principles of +structured programming: + +

    +
  • Words must be defined before they are used. +
  • Logical flow is restricted to sequential, conditional, and +iterative patterns. Words are included to implement the most useful +program control structures. +
  • The programmer works with many small, independent modules +(words) for maximum testability and reliability. +
+

+ +Forth is characterized by five major elements: a dictionary, two +push-down stacks, interpreters, an assembler, and virtual storage. +Although each of these may be found in other systems, the combination +produces a synergy that yields a powerful and flexible system. + +

+ + +


+ +

C.5.1 The Forth dictionary

+
+ +A Forth program is organized into a dictionary that occupies most of the +memory used by the system. This dictionary is a threaded list of +variable-length items, each of which defines a word. The content of +each definition depends upon the type of word (data item, constant, +sequence of operations, etc.). The dictionary is extensible, usually +growing toward high memory. On some multi-user systems individual users +have private dictionaries, each of which is connected to a shared system +dictionary. + +

+ +Words are added to the dictionary by defining words, of which the +most commonly used is : +(colon). +When : is executed, it constructs a +definition for the word that follows it. In classical implementations, +the content of this definition is a string of addresses of previously +defined words which will be executed in turn whenever the word being +defined is invoked. The definition is terminated by ; +(semicolon). +For +example, here is a definition: + + +

+	: RECEIVE  ( -- addr n )  PAD DUP 32 ACCEPT ;
+
+ +

+ +The name of the new word is RECEIVE. The comment (in parentheses) +indicates that it requires no parameters and will return an address and +count on the data stack. When RECEIVE is executed, it will perform the +words in the remainder of the definition in sequence. The word +PAD +places on the stack the address of a scratch pad used to handle strings. +DUP +duplicates the top stack item, so we now have two copies of the +address. The number 32 is also placed on the stack. The word +ACCEPT +takes an address (provided by PAD) and length (32) on the stack, accepts +from the keyboard a string of up to 32 characters which will be placed +at the specified address, and returns the number of characters received. +The copy of the scratch-pad address remains on the stack below the count +so that the routine that called RECEIVE can use it to pick up the +received string. + +

+ + +


+ +

C.5.2 Push-down stacks

+
+ +The example above illustrates the use of push-down stacks for passing +parameters between Forth words. Forth maintains two push-down stacks, +or LIFO lists. These provide communication between Forth words plus an +efficient mechanism for controlling logical flow. A stack contains +16-bit items on 8-bit and 16-bit computers, and 32-bit items on 32-bit +processors. Double-cell numbers occupy two stack positions, with the +most-significant part on top. Items on either stack may be addresses or +data items of various kinds. Stacks are of indefinite size, and usually +grow towards low memory. + +

+ +Although the structure of both stacks is the same, they have very +different uses. The user interacts most directly with the Data Stack, +which contains arguments passed between words. This function replaces +the calling sequences used by conventional languages. It is efficient +internally, and makes routines intrinsically re-entrant. The second +stack is called the Return Stack, as its main function is to hold return +addresses for nested definitions, although other kinds of data are +sometimes kept there temporarily. + +

+ +The use of the Data Stack (often called just the stack) leads to +a notation in which operands precede operators. The word +ACCEPT +in the +example above took an address and count from the stack and left another +address there. Similarly, a word called +BLANK +expects an address and +count, and will place the specified number of space characters (20H) in +the region starting at that address. Thus, + + +

+	PAD 25 BLANK
+
+ +

+ +will fill the scratch region whose address is pushed on the stack by +PAD +with 25 spaces. Application words are usually defined to work +similarly. For example, + + +

+	100 SAMPLES
+
+ +

+ +might be +defined to record 100 measurements in a data array. + +

+ +Arithmetic operators also expect values and leave results on the stack. +For example, ++ +adds the top two numbers on the stack, replacing them +both by their sum. Since results of operations are left on the stack, +operations may be strung together without a need to define variables to +use for temporary storage. + +

+ + +


+ +

C.5.3 Interpreters

+
+ +Forth is traditionally an interpretive system, in that program execution +is controlled by data items rather than machine code. Interpreters can +be slow, but Forth maintains the high speed required of real-time +applications by having two levels of interpretation. + +

+ +The first is the text interpreter, which parses strings from the +terminal or mass storage and looks each word up in the dictionary. When +a word is found it is executed by invoking the second level, the address +interpreter. + +

+ +The second is an address interpreter. Although not all Forth +systems are implemented in this way, it was the first and is still the +primary implementation technology. For a small cost in performance, an +address interpreter can yield a very compact object program, which has +been a major factor in Forth's wide acceptance in embedded systems and +other applications where small object size is desirable. + +

+ +The address interpreter processes strings of addresses or tokens +compiled in definitions created by : +(colon), +by executing the +definition pointed to by each. The content of most definitions is a +sequence of addresses of previously defined words, which will be +executed by the address interpreter in turn. Thus, when the word +RECEIVE (defined above) is executed, the word +PAD, +the word +DUP, the +literal 32, and the word +ACCEPT +will be executed in sequence. The +process is terminated by the +semicolon. This execution requires no +dictionary searches, parsing, or other logic, because when RECEIVE was +compiled the dictionary was searched for each word, and its address (or +other token) was placed in the next successive cell of the entry. The +text was not stored in memory, not even in condensed form. + +

+ +The address interpreter has two important properties. First, it is +fast. Although the actual speed depends upon the specific +implementation, professional implementations are highly optimized, often +requiring only one or two machine instructions per address. On most +benchmarks, a good Forth implementation substantially out-performs +interpretive languages such as BASIC or LISP, and will compare favorably +with other compiled high-level languages. + +

+ +Second, the address interpreter makes Forth definitions extremely +compact, as each reference requires only one cell. In comparison, a +subroutine call constructed by most compilers involves instructions for +handling the calling sequence (unnecessary in Forth because of the +stack) before and after a CALL or JSR instruction and address. + +

+ +Most of the words in a Forth dictionary will be defined by : (colon) and +interpreted by the address interpreter. Most of Forth itself is defined +this way. + +

+ + +


+ +

C.5.4 Assembler

+
+ +Most implementations of Forth include a macro assembler for the CPU on +which they run. By using the defining word +CODE +the programmer can +create a definition whose behavior will consist of executing actual +machine instructions. CODE definitions may be used to do I/O, implement +arithmetic primitives, and do other machine-dependent or time-critical +processing. When using CODE the programmer has full control over the +CPU, as with any other assembler, and CODE definitions run at full +machine speed. + +

+ +This is an important feature of Forth. It permits explicit +computer-dependent code in manageable pieces with specific interfacing +conventions that are machine-independent. To move an application to a +different processor requires re-coding only the CODE words, which will +interact with other Forth words in exactly the same manner. + +

+ +Forth assemblers are so compact (typically a few Kbytes) that they can +be resident in the system (as are the compiler, editor, and other +programming tools). This means that the programmer can type in short +CODE definitions and execute them immediately. This capability is +especially valuable in testing custom hardware. + +

+ + +


+ +

C.5.5 Virtual memory

+
+ +The final unique element of Forth is its way of using disk or other mass +storage as a form of virtual memory for data and program source. +As in the case of the address interpreter, this approach is historically +characteristic of Forth, but is by no means universal. Disk is divided +into 1024-byte blocks. Two or more buffers are provided in memory, into +which blocks are read automatically when referred to. Each block has a +fixed block number, which in native systems is a direct function of its +physical location. If a block is changed in memory, it will be +automatically written out when its buffer must be reused. Explicit +reads and writes are not needed; the program will find the data in +memory whenever it accesses it. + +

+ +Block-oriented disk handling is efficient and easy for native Forth +systems to implement. As a result, blocks provide a completely +transportable mechanism for handling program source and data across both +native and co-resident versions of Forth on different host operating +systems. + +

+ +Definitions in program source blocks are compiled into memory by the +word +LOAD. +Most implementations include an editor, which formats a +block for display into 16 lines of 64 characters each, and provides +commands modifying the source. An example of a Forth source block is +given in Fig. C.1 below. + +

+ +Source blocks have historically been an important element in Forth +style. Just as Forth definitions may be considered the linguistic +equivalent of sentences in natural languages, a block is analogous to a +paragraph. A block normally contains definitions related to a common +theme, such as vector arithmetic. A comment on the top line of +the block identifies this theme. An application may selectively load +the blocks it needs. + +

+ +Blocks are also used to store data. Small records can be combined into +a block, or large records spread over several blocks. The programmer +may allocate blocks in whatever way suits the application, and on native +systems can increase performance by organizing data to minimize disk +head motion. Several Forth vendors have developed sophisticated file +and data base systems based on Forth blocks. + +

+ +Versions of Forth that run co-resident with a host OS often implement +blocks in host OS files. Others use the host files exclusively. The +Standard requires that blocks be available on systems providing any disk +access method, as they are the only means of referencing disk that can +be transportable across both native and co-resident implementations. + +

+ +


+ +

C.5.6 Programming environment

+
+ +Although this Standard does not require it, most Forth systems include a +resident editor. This enables a programmer to edit source and recompile +it into executable form without leaving the Forth environment. As it is +easy to organize an application into layers, it is often possible to +recompile only the topmost layer (which is usually the one currently +under development), a process which rarely takes more than a few +seconds. + +

+ +Most Forth systems also provide resident interactive debugging aids, not +only including words such as those in +15. The optional +Programming-Tools word set, but also having the ability to examine and +change the contents of +VARIABLEs +and other data items and to execute +from the keyboard most of the component words in both the underlying +Forth system and the application under development. + +

+ +The combination of resident editor, integrated debugging tools, and +direct executability of most defined words leads to a very interactive +programming style, which has been shown to shorten development time. + +

+ + +


+ +

C.5.7 Advanced programming features

+
+ +One of the unusual characteristics of Forth is that the words the +programmer defines in building an application become integral elements +of the language itself, adding more and more powerful +application-oriented features. + +

+ +For example, Forth includes the words +VARIABLE and +2VARIABLE to name +locations in which data may be stored, as well as +CONSTANT and +2CONSTANT +to name single and double-cell values. Suppose a programmer finds that +an application needs arrays that would be automatically indexed through +a number of two-cell items. Such an array might be called 2ARRAY. The +prefix 2 in the name indicates that each element in this array +will occupy two cells (as would the contents of a 2VARIABLE or +2CONSTANT). The prefix 2, however, has significance only to a +human and is no more significant to the text interpreter than any other +character that may be used in a definition name. + +

+ +Such a definition has two parts, as there are two behaviors +associated with this new word 2ARRAY, one at compile time, and one at +run or execute time. These are best understood if we look at how 2ARRAY +is used to define its arrays, and then how the array might be used in an +application. In fact, this is how one would design and implement this +word. + +

+ +Beginning the top-down design process, here's how we would like to use +2ARRAY: + + +

+	100 2ARRAY RAW   50 2ARRAY REFINED
+
+ +

+ +In the first case, we are defining an array 100 elements long, whose +name is RAW. In the second, the array is 50 elements long, and is named +REFINED. In each case, a size parameter is supplied to 2ARRAY on the +data stack (Forth's text interpreter automatically puts numbers there +when it encounters them), and the name of the word immediately follows. +This order is typical of Forth defining words. + +

+ +When we use RAW or REFINED, we would like to supply on the stack the +index of the element we want, and get back the address of that element +on the stack. Such a reference would characteristically take place in a +loop. Here's a representative loop that accepts a two-cell value from a +hypothetical application word DATA and stores it in the next element of +RAW: + + +

+	: ACQUIRE 100 0 DO DATA I RAW 2! LOOP ;
+
+ +

+ +The name of this definition is ACQUIRE. The loop begins with +DO, ends +with +LOOP, +and will execute with index values running from 0 through 99. +Within the loop, DATA gets a value. The word +I +returns the current +value of the loop index, which is the argument to RAW. The address of +the selected element, returned by RAW, and the value, which has remained +on the stack since DATA, are passed to the word +2! +(pronounced +two-store), which stores two stack items in the address. + +

+ +Now that we have specified exactly what 2ARRAY does and how the words it +defines are to behave, we are ready to write the two parts of its +definition: +

+ + +

+	: 2ARRAY  ( n -- )
+	   CREATE  2* CELLS ALLOT
+	   DOES>  ( i a -- a')  SWAP  2*
+	CELLS + ;
+
+ +

+ +The part of the definition before the word +DOES> +specifies the +compile-time behavior, that is, what the 2ARRAY will do when it +us used to define a word such as RAW. The comment indicates that this +part expects a number on the stack, which is the size parameter. The +word +CREATE +constructs the definition for the new word. The phrase +2* +CELLS +converts the size parameter from two-cell units to the internal +addressing units of the system (normally characters). +ALLOT +then +allocates the specified amount of memory to contain the data to be +associated with the newly defined array. + +

+ +The second line defines the run-time behavior that will be shared +by all words defined by 2ARRAY, such as RAW and REFINED. The word DOES> +terminates the first part of the definition and begins the second part. +A second comment here indicates that this code expects an index and an +address on the stack, and will return a different address. The index is +supplied on the stack by the caller (of RAW in the example), while the +address of the content of a word defined in this way (the ALLOTted +region) is automatically pushed on top of the stack before this section +of the code is to be executed. This code works as follows: +SWAP +reverses the order of the two stack items, to get the index on top. 2* +CELLS converts the index to the internal addressing units as in the +compile-time section, to yield an offset from the beginning of the +array. The word ++ +then adds the offset to the address of the start of +the array to give the effective address, which is the desired result. + +

+ +Given this basic definition, one could easily modify it to do more +sophisticated things. For example, the compile-time code could be +changed to initialize the array to zeros, spaces, or any other desired +initial value. The size of the array could be compiled at its +beginning, so that the run-time code could compare the index against it +to ensure it is within range, or the entire array could be made to +reside on disk instead of main memory. None of these changes would +affect the run-time usage we have specified in any way. This +illustrates a little of the flexibility available with these defining +words. + +

+ + +


+ +

C.5.8 A programming example

+
+ +Figure C.1 +contains a typical block of Forth source. It represents a +portion of an application that controls a bank of eight LEDs used as +indicator lamps on an instrument, and indicates some of the ways in +which Forth definitions of various kinds combine in an application +environment. This example was coded for a STD-bus system with an 8088 +processor and a millisecond clock, which is also used in the example. + +

+ +The LEDs are interfaced through a single 8-bit port whose address is +40H. This location is defined as a +CONSTANT +on Line 1, so that it may +be referred to by name; should the address change, one need only adjust +the value of this constant. The word LIGHTS returns this address on the +stack. The definition LIGHT takes a value on the stack and sends it to +the device. The nature of this value is a bit mask, whose bits +correspond directly to the individual lights. + +

+ +Thus, the command 255 LIGHT will turn on all lights, while 0 LIGHT will +turn them all off. + +

+ +* +

+Block 180
+  0.      ( LED control )
+  1.      HEX 40 CONSTANT LIGHTS DECIMAL
+  2. : LIGHT ( n -- )  LIGHTS OUTPUT ;
+  3.
+  4. VARIABLE DELAY
+  5. : SLOW  500 DELAY ! ;
+  6. : FAST  100 DELAY ! ;
+  7. : COUNTS 256 0 DO I LIGHT DELAY @ MS  LOOP ;
+  8.
+  9. : LAMP ( n -  )  CREATE ,  DOES> ( a -- n )   @ ;
+ 10. 1 LAMP POWER       2 LAMP HV     4 LAMP TORCH
+ 11. 8 LAMP SAMPLING   16 LAMP IDLING
+ 12.
+ 13. VARIABLE LAMPS
+ 14. : TOGGLE ( n -- ) LAMPS @ XOR DUP LAMPS ! LIGHT ;
+ 15.
+
+

+ +Figure C.1 - Forth source block containing words that control a set of LEDs. + +

+ +Lines 4 - 7 contain a simple diagnostic of the sort one might type in +from the terminal to confirm that everything is working. The variable +DELAY contains a delay time in milliseconds - execution of the word +DELAY returns the address of this variable. Two values of DELAY are set +by the definitions SLOW and FAST, using the Forth operator +! +(pronounced +store) which takes a value and an address, and stores the value +in the address. The definition COUNTS runs a loop from 0 through 255 +(Forth loops of this type are exclusive at the upper end of the range), +sending each value to the lights and then waiting for the period +specified by DELAY. The word +@ +(pronounced fetch) fetches a +value from an address, in this case the address supplied by DELAY. This +value is passed to +MS, +which waits the specified number of milliseconds. +The result of executing COUNTS is that the lights will count from 0 to +255 at the desired rate. To run this, one would type: + + +

+	SLOW COUNTS   or   FAST COUNTS
+
+ +

+ +at the terminal. + +

+ +Line 9 provides the capability of naming individual lamps. In this +application they are being used as indicator lights. The word LAMP is a +defining word which takes as an argument a mask which represents a +particular lamp, and compiles it as a named entity. Lines 10 and 11 +contain five uses of LAMP to name particular indicators. When one of +these words such as POWER is executed, the mask is returned on the +stack. In fact, the behavior of defining a value such that when the +word is invoked the value is returned, is identical to the behavior of a +Forth CONSTANT. We created a new defining word here, however, to +illustrate how this would be done. + +

+ +Finally, on lines 13 and 14, we have the words that will control the +light panel. LAMPS is a variable that contains the current state of the +lamps. The word TOGGLE takes a mask (which might be supplied by one of +the LAMP words) and changes the state of that particular lamp, saving +the result in LAMPS. + +

+ +In the remainder of the application, the lamp names and TOGGLE are +probably the only words that will be executed directly. The usage there +will be, for example: + + +

+	POWER TOGGLE   or   SAMPLING TOGGLE
+
+ +

+ +as appropriate, whenever the system indicators need to be changed. + +

+ +The time to compile this block of code on that system was about half a +second, including the time to fetch it from disk. So it is quite +practical (and normal practice) for a programmer to simply type in a +definition and try it immediately. + +

+ +In addition, one always has the capability of communicating with +external devices directly. The first thing one would do when told about +the lamps would be to type: + + +

+	HEX FF 40 OUTPUT
+
+ +

+ +and see if all the lamps come on. If not, the presumption is that +something is amiss with the hardware, since this phrase directly +transmits the all ones mask to the device. This type of direct +interaction is useful in applications involving custom hardware, as it +reduces hardware debugging time. + +

+ + +


+ +

C.6 Multiprogrammed systems

+
+ +Multiprogrammed Forth systems have existed since about 1970. The +earliest public Forth systems propagated the hooks for this +capability despite the fact that many did not use them. Nevertheless +the underlying assumptions have been common knowledge in the community, +and there exists considerable common ground among these multiprogrammed +systems. These systems are not just language processors, but contain +operating system characteristics as well. Many of these integrated +systems run entirely stand-alone, performing all necessary operating +system functions. + +

+ +Some Forth systems are very fast, and can support both multi-tasking and +multi-user operation even on computers whose hardware is usually thought +incapable of such advanced operation. For example, one producer of +telephone switchboards is running over 50 tasks on a Z80. There are +several multiprogrammed products for PC's, some of which even support +multiple users. Even on computers that are commonly used in multi-user +operations, the number of users that can be supported may be much larger +than expected. One large data-base application running on a single +68000 has over 100 terminals updating and querying its data-base, with +no significant degradation. + +

+ +Multi-user systems may also support multiple programmers, each of which +has a private dictionary, stacks, and a set of variables controlling +that task. The private dictionary is linked to a shared, re-entrant +dictionary containing all the standard Forth functions. The private +dictionary can be used to develop application code which may later be +integrated into the shared dictionary. It may also be used to perform +functions requiring text interpretation, including compilation and +execution of source code. + +

+ +


+ +

C.7 Design and management considerations

+
+ +Just as the choice of building materials has a strong effect on the +design and construction of a building, the choice of language and +operating system will affect both application design and project +management decisions. + +

+ +Conventionally, software projects progress through four stages: +analysis, design, coding, and testing. A Forth project necessarily +incorporates these activities as well. Forth is optimized for a +project-management methodology featuring small teams of skilled +professionals. Forth encourages an iterative process of successive +prototyping wherein high-level Forth is used as an executable design +tool, with stubs replacing lower-level routines as necessary +(e.g., for hardware that isn't built yet). + +

+ +In many cases successive prototyping can produce a sounder, more useful +product. As the project progresses, implementors learn things that +could lead to a better design. Wiser decisions can be made if true +relative costs are known, and often this isn't possible until prototype +code can be written and tried. + +

+ +Using Forth can shorten the time required for software development, and +reduce the level of effort required for maintenance and modifications +during the life of the product as well. + +

+ + +


+ +

C.8 Conclusion

+
+ +Forth has produced some remarkable achievements in a variety of +application areas. In the last few years its acceptance has grown +rapidly, particularly among programmers looking for ways to improve +their productivity and managers looking for ways to simplify new +software-development projects. + +

+ + + +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansd.htm b/docs/reference/standards/ans94/dpansd.htm new file mode 100644 index 00000000..2d37fe49 --- /dev/null +++ b/docs/reference/standards/ans94/dpansd.htm @@ -0,0 +1,1155 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

D. Compatibility analysis of ANS Forth (informative annex)

+ +Prior to ANS Forth, there were several industry standards for Forth. +The most influential are listed here in chronological order, along with +the major differences between ANS Forth and the most recent, Forth-83. + +

+ + +


+ +

D.1 FIG Forth (circa 1978)

+
+ +FIG Forth was a model implementation of the Forth language +developed by the Forth Interest Group (FIG). In FIG Forth, a relatively +small number of words were implemented in processor-dependent machine +language and the rest of the words were implemented in Forth. The FIG +model was placed in the public domain, and was ported to a wide variety +of computer systems. Because the bulk of the FIG Forth implementation +was the same across all machines, programs written in FIG Forth enjoyed +a substantial degree of portability, even for system-level +programs that directly manipulate the internals of the Forth system +implementation. + +

+ +FIG Forth implementations were influential in increasing the number of +people interested in using Forth. Many people associate the +implementation techniques embodied in the FIG Forth model with the +nature of Forth. + +

+ +However, FIG Forth was not necessarily representative of commercial +Forth implementations of the same era. Some of the most successful +commercial Forth systems used implementation techniques different from +the FIG Forth model. + +

+ + +


+ +

D.2 Forth-79

+
+ +The Forth-79 Standard resulted from a series of meetings from 1978 to +1980, by the Forth Standards Team, an international group of Forth users +and vendors (interim versions known as Forth 77 and Forth 78 were also +released by the group). + +

+ +Forth-79 described a set of words defined on a 16-bit, twos-complement, +unaligned, linear byte-addressing virtual machine. It prescribed an +implementation technique known as indirect threaded code, and +used the ASCII character set. + +

+ +The Forth-79 Standard served as the basis for several public domain and +commercial implementations, some of which are still available and +supported today. + +

+ +


+ +

D.3 Forth-83

+
+ +The Forth-83 Standard, also by the Forth Standards Team, was released in +1983. Forth-83 attempted to fix some of the deficiencies of Forth-79. + +

+ +Forth-83 was similar to Forth-79 in most respects. However, Forth-83 +changed the definition of several well-defined features of Forth-79. +For example, the rounding behavior of integer division, the base value +of the operands of +PICK +and +ROLL, +the meaning of the address returned by +', +the compilation behavior of ', the value of a true flag, the +meaning of +NOT, +and the chaining behavior of words defined by +VOCABULARY were all changed. Forth-83 relaxed the implementation +restrictions of Forth-79 to allow any kind of threaded code, but it did +not fully allow compilation to native machine code (this was not +specifically prohibited, but rather was an indirect consequence of +another provision). + +

+ +Many new Forth implementations were based on the Forth-83 Standard, but +few strictly compliant Forth-83 implementations exist. + +

+ +Although the incompatibilities resulting from the changes between +Forth-79 and Forth-83 were usually relatively easy to fix, a number of +successful Forth vendors did not convert their implementations to be +Forth-83 compliant. For example, the most successful commercial Forth +for Apple Macintosh computers is based on Forth-79. + +

+ +


+ +

D.4 Recent developments

+
+ +Since the Forth-83 Standard was published, the computer industry has +undergone rapid and profound changes. The speed, memory capacity, and +disk capacity of affordable personal computers have increased by factors +of more than 100. 8-bit processors have given way to 16-bit processors, +and now 32-bit processors are commonplace. + +

+ +The operating systems and programming-language environments of small +systems are much more powerful than they were in the early 80's. + +

+ +The personal-computer marketplace has changed from a predominantly +hobbyist market to a mature business and commercial market. + +

+ +Improved technology for designing custom microprocessors has resulted in +the design of numerous Forth chips, computers optimized for the +execution of the Forth language. + +

+ +The market for ROM-based embedded control computers has grown +substantially. + +

+ +In order to take full advantage of this evolving technology, and to +better compete with other programming languages, many recent Forth +implementations have ignored some of the rules of previous Forth +standards. In particular: + +

    +
  • 32-bit Forth implementations are now common. +
  • Some Forth systems adopt the address-alignment restrictions of the +hardware on which they run. +
  • Some Forth systems use native-code generation, microcode +generation, and optimization techniques, rather than the traditional +threaded code. +
  • Some Forth systems exploit segmented addressing architectures, +placing portions of the Forth dictionary in different segments. +
  • More and more Forth systems now run in the environment of +another standard operating system, using OS text files for source +code, rather than the traditional Forth blocks. +
  • Some Forth systems allow external operating system software, +windowing software, terminal concentrators, or communications channels +to handle or preprocess user input, resulting in deviations from the +input editing, character set availability, and screen management +behavior prescribed by Forth-83. +
+

+ +Competitive pressure from other programming languages (predominantly +C) and from other Forth vendors have led Forth vendors to +optimizations that do not fit in well with the virtual machine +model implied by existing Forth standards. + +

+ + +


+ +

D.5 ANS Forth approach

+
+ +The ANS Forth committee addressed the serious fragmentation of the Forth +community caused by the differences between Forth-79 and Forth-83, and +the divergence from either of these two industry standards caused by +marketplace pressures. + +

+ +Consequently, the committee has chosen to base its compatibility +decisions not upon a strict comparison with the Forth-83 Standard, but +instead upon consideration of the variety of existing implementations, +especially those with substantial user bases and/or considerable success +in the marketplace. + +

+ +The committee feels that, if ANS Forth prescribes stringent requirements +upon the virtual machine model, as did the previous standards, then many +implementors will chose not to comply with ANS Forth. The committee +hopes that ANS Forth will serve to unify rather than to further divide +the Forth community, and thus has chosen to encompass rather than +invalidate popular implementation techniques. + +

+ +Many of the changes from Forth-83 are justified by this rationale. Most +fall into the category that an ANS Forth Standard Program may not +assume x, where x is an entitlement resulting from the +virtual machine model prescribed by the Forth-83 Standard. The +committee feels that these restrictions are reasonable, especially +considering that a substantial number of existing Forth implementations +do not correctly implement the Forth-83 virtual model, thus the Forth-83 +entitlements exist in theory but not in practice. + +

+ +Another way of looking at this is that while ANS Forth acknowledges the +diversity of current Forth practice, it attempts to document the +similarity therein. In some sense, ANS Forth is thus a description +of reality rather than a prescription for a particular virtual +machine. + +

+ +Since there is no previous American National Standard for Forth, the +action requirements prescribed by section 3.4 of X3/SD-9, Policy and +Guidelines, regarding previous standards do not apply. + +

+ +The following discussion describes differences between ANS Forth and +Forth-83. In most cases, Forth-83 is representative of Forth-79 and FIG +Forth for the purposes of this discussion. In many of these cases, +however, ANS Forth is more representative of the existing state of the +Forth industry than the previously-published standards. + +

+ +


+ +

D.6 Differences from Forth-83

+
+ + + +
+ +

D.6.1 Stack width

+
+ +Forth-83 specifies that stack items occupy 16 bits. This includes +addresses, flags, and numbers. ANS Forth specifies that stack items are +at least 16 bits; the actual size must be documented by the +implementation. + +

+ +Words affected: all arithmetic, logical and addressing +operators + +

+ +Reason: 32-bit machines are becoming +commonplace. A 16-bit Forth system on a 32-bit machine is not competitive. + +

+ +Impact: Programs that assume 16-bit stack +width will continue to run on 16-bit machines; ANS Forth does not require a +different stack width, but simply allows it. Many programs will be unaffected +(but see address unit). + +

+ +Transition/Conversion: Programs which use bit masks with the high bits set +may have to be changed, substituting either an implementation-defined bit-mask +constant, or a procedure to calculate a bit mask in a stack-width-independent +way. Here are some procedures for constructing width-independent bit masks: + +

+ + +

+1  CONSTANT LO-BIT
+TRUE 1 RSHIFT  INVERT  CONSTANT HI-BIT
+
+: LO-BITS  ( n -- mask )
+    0 SWAP  0 ?DO  1 LSHIFT  LO-BIT OR  LOOP ;
+
+: HI-BITS  ( n -- mask )
+    0 SWAP  0 ?DO  1 RSHIFT  HI-BIT OR  LOOP ;
+
+ +

+ +Programs that depend upon the modulo 65536 behavior implicit in +16-bit arithmetic operations will need to be rewritten to explicitly +perform the modulus operation in the appropriate places. The committee +believes that such assumptions occur infrequently. Examples: some +checksum or CRC calculations, some random number generators and most +fixed-point fractional math. + +

+ + +


+ +

D.6.2 Number representation

+
+ +Forth-83 specifies two's-complement number representation and +arithmetic. ANS Forth also allows one's-complement and +signed-magnitude. + +

+ +Words affected: all arithmetic and logical operators, +LOOP, ++LOOP +

+ + +Reason: Some computers use one's-complement or signed-magnitude. The +committee did not wish to force Forth implementations for those machines +to emulate two's-complement arithmetic, and thus incur severe +performance penalties. The experience of some committee members with +such machines indicates that the usage restrictions necessary to support +their number representations are not overly burdensome. + +

+ +Impact: An ANS Forth Standard Program may declare an environmental +dependency on two's-complement arithmetic. This means that the +otherwise-Standard Program is only guaranteed to work on +two's-complement machines. Effectively, this is not a severe +restriction, because the overwhelming majority of current computers use +two's-complement. The committee knows of no Forth-83 compliant +implementations for non-two's-complement machines at present, so +existing Forth-83 programs will still work on the same class of machines +on which they currently work. + +

+ +Transition/Conversion: Existing programs wishing to take advantage of +the possibility of ANS Forth Standard Systems on non-two's-complement +machines may do so by eliminating the use of arithmetic operators to +perform logical functions, by deriving bit-mask constants from bit +operations as described in the section about stack width, by restricting +the usage range of unsigned numbers to the range of positive numbers, +and by using the provided operators for conversion from single numbers +to double numbers. + +

+ + +


+ +

D.6.3 Address units

+
+ +Forth-83 specifies that each unique address refers to an 8-bit byte in +memory. ANS Forth specifies that the size of the item referred to by +each unique address is implementation-defined, but, by default, is the +size of one character. Forth-83 describes many memory operations in +terms of a number of bytes. ANS Forth describes those operations in +terms of a number of either characters or address units. + +

+ +Words affected: those with address unit arguments +

+ +Reason: Some machines, including the most popular Forth chip, address +16-bit memory locations instead of 8-bit bytes. + +

+ +Impact: Programs may choose to declare an environmental dependency on +byte addressing, and will continue to work on the class of machines for +which they now work. In order for a Forth implementation on a +word-addressed machine to be Forth-83 compliant, it would have to +simulate byte addressing at considerable cost in speed and memory +efficiency. The committee knows of no such Forth-83 implementations for +such machines, thus an environmental dependency on byte addressing does +not restrict a Standard Program beyond its current de facto +restrictions. + +

+ +Transition/Conversion: The new +CHARS +and +CHAR+ +address arithmetic +operators should be used for programs that require portability to +non-byte-addressed machines. The places where such conversion is +necessary may be identified by searching for occurrences of words that +accept a number of address units as an argument (e.g., +MOVE, +ALLOT). + +

+ + +


+ +

D.6.4 Address increment for a cell is no longer two

+
+ +As a consequence of Forth-83's simultaneous specification of 16-bit +stack width and byte addressing, the number two could reliably be used +in address calculations involving memory arrays containing items from +the stack. Since ANS Forth requires neither 16-bit stack width nor byte +addressing, the number two is no longer necessarily appropriate for such +calculations. + +

+ +Words +affected: +@ +! ++! +2+ +2* +2- ++LOOP + +

+ +Reason: See reasons for Address Units and Stack Width +

+ +Impact: In this respect, existing programs will continue to work on +machines where a stack cell occupies two address units when stored in +memory. This includes most machines for which Forth-83 compliant +implementations currently exist. In principle, it would also include +16-bit-word-addressed machines with 32-bit stack width, but the +committee knows of no examples of such machines. + +

+ +Transition/Conversion: The new +CELLS +and +CELL+ +address arithmetic +operators should be used for portable programs. The places where such +conversion is necessary may be identified by searching for the character +2 and determining whether or not it is used as part of an address +calculation. The following substitutions are appropriate within address +calculations: + +

+ + +

+Old                     New
+---                     ---
+2+  or  2 +             CELL+
+2*  or  2 *             CELLS
+2-  or  2 -             1 CELLS -
+2/  or  2 /             1 CELLS /
+2                       1 CELLS
+
+ +

+ +The number 2 by itself is sometimes used for address calculations +as an argument to ++LOOP, +when the loop index is an address. When +converting the word +2/ +which operates on negative dividends, one should +be cognizant of the rounding method used. + +

+ + +


+ +

D.6.5 Address alignment

+
+ +Forth-83 imposes no restriction upon the alignment of addresses to any +boundary. ANS Forth specifies that a Standard System may require +alignment of addresses for use with various @ and ! +operators. + +

+ +Words Affected: +! ++! +2! +2@ +@ +? +, +

+ +Reason: Many computers have hardware restrictions that favor the use of +aligned addresses. On some machines, the native memory-access +instructions will cause an exception trap if used with an unaligned +address. Even on machines where unaligned accesses do not cause +exception traps, aligned accesses are usually faster. + +

+ +Impact: All of the ANS Forth words that return addresses suitable for +use with aligned @ and ! words must return aligned +addresses. In most cases, there will be no problem. Problems can arise +from the use of user-defined data structures containing a mixture of +character data and cell-sized data. + +

+ +Many existing Forth systems, especially those currently in use on +computers with strong alignment requirements, already require alignment. +Much existing Forth code that is currently in use on such machines has +already been converted for use in an aligned environment. + +

+ +Transition/Conversion: There are two possible approaches to conversion +of programs for use on a system requiring address alignment. + +

+ +The easiest approach is to redefine the system's aligned @ and +! operators so that they do not require alignment. For example, +on a 16-bit little-endian byte-addressed machine, unaligned @ and +! could be defined: + + +

+	: @  ( addr -- x )  DUP C@ SWAP CHAR+ C@ 8 LSHIFT OR  ;
+	: !  ( x addr -- )  OVER 8 RSHIFT OVER CHAR+ C! C!  ;
+
+

+ +These definitions, and similar ones for +!, 2@, 2!, +,, and ? as needed, can be compiled before an unaligned +application, which will then work as expected. + +

+ +This approach may conserve memory if the application uses substantial +numbers of data structures containing unaligned fields. + +

+ +Another approach is to modify the application's source code to eliminate +unaligned data fields. The ANS Forth words +ALIGN +and +ALIGNED +may be +used to force alignment of data fields. The places where such alignment +is needed may be determined by inspecting the parts of the application +where data structures (other than simple variables) are defined, or by +smart compiler techniques (see the Smart Compiler +discussion below). + +

+ +This approach will probably result in faster application execution +speed, at the possible expense of increased memory utilization for data +structures. + +

+ +Finally, it is possible to combine the preceding techniques by +identifying exactly those data fields that are unaligned, and using +unaligned versions of the memory access operators for only those +fields. This hybrid approach affects a compromise between +execution speed and memory utilization. + +

+ + +


+ +

D.6.6 Division/modulus rounding direction

+
+ +Forth-79 specifies that division rounds toward 0 and the remainder +carries the sign of the dividend. Forth-83 specifies that division +rounds toward negative infinity and the remainder carries the sign of +the divisor. ANS Forth allows either behavior for the division +operators listed below, at the discretion of the implementor, and +provides a pair of division primitives to allow the user to synthesize +either explicit behavior. + +

+ +Words Affected: +/ +MOD +/MOD +*/MOD +*/ +

+ +Reason: The difference between the division behaviors in Forth-79 and +Forth-83 was a point of much contention, and many Forth implementations +did not switch to the Forth-83 behavior. Both variants have vocal +proponents, citing both application requirements and execution +efficiency arguments on both sides. After extensive debate spanning +many meetings, the committee was unable to reach a consensus for +choosing one behavior over the other, and chose to allow either behavior +as the default, while providing a means for the user to explicitly use +both behaviors as needed. Since implementors are allowed to choose +either behavior, they are not required to change the behavior exhibited +by their current systems, thus preserving correct functioning of +existing programs that run on those systems and depend on a particular +behavior. New implementations could choose to supply the behavior that +is supported by the native CPU instruction set, thus maximizing +execution speed, or could choose the behavior that is most appropriate +for the intended application domain of the system. + +

+ +Impact: The issue only affects programs that use a negative dividend +with a positive divisor, or a positive dividend with a negative divisor. +The vast majority of uses of division occur with both a positive +dividend and a positive divisor; in that case, the results are the same +for both allowed division behaviors. + +

+ +Transition/Conversion: For programs that require a specific rounding +behavior with division operands of mixed sign, the division operators +used by the program may be redefined in terms of one of the new ANS +Forth division primitives +SM/REM +(symmetrical division, i.e., round +toward zero) or +FM/MOD +(floored division, i.e., round toward negative +infinity). Then the program may be recompiled without change. For +example, the Forth-83 style division operators may be defined by: + +

+ + +

+: /MOD  ( n1 n2 -- n3 n4 )     >R S>D R> FM/MOD  ;
+: MOD   ( n1 n2 -- n3 )        /MOD DROP  ;
+: /     ( n1 n2 -- n3 )        /MOD SWAP DROP   ;
+: */MOD ( n1 n2 n3 -- n4 n5 )  >R M* R> FM/MOD  ;
+: */    ( n1 n2 n3 -- n4 n5 )  */MOD SWAP DROP  ;
+
+ +

+ +


+ +

D.6.7 Immediacy

+
+ +Forth-83 specified that a number of compiling words are +immediate, meaning that they are executed instead of compiled +during compilation. ANS Forth is less specific about most of these +words, stating that their behavior is only defined during compilation, +and specifying their results rather than their specific compile-time +actions. + +

+ +To force the compilation of a word that would normally be executed, +Forth-83 provided the words COMPILE , used with non-immediate words, and +[COMPILE] , +used with immediate words. ANS Forth provides the single +word +POSTPONE , +which is used with both immediate and non-immediate +words, automatically selecting the appropriate behavior. + +

+ +Words Affected: +COMPILE [COMPILE] +['] +' +

+ +Reason: The designation of particular words as either immediate or not +depends upon the implementation technique chosen for the Forth system. +With traditional threaded code implementations, the choice was +generally quite clear (with the single exception of the word +LEAVE), and +the standard could specify which words should be immediate. However, +some of the currently popular implementation techniques, such as +native-code generation with optimization, require the immediacy +attribute on a different set of words than the set of immediate words of +a threaded code implementation. ANS Forth, acknowledging the validity +of these other implementation techniques, specifies the immediacy +attribute in as few cases as possible. + +

+ +When the membership of the set of immediate words is unclear, the +decision about whether to use COMPILE or [COMPILE] becomes unclear. +Consequently, ANS Forth provides a general purpose replacement +word POSTPONE that serves the purpose of the vast majority of uses of +both COMPILE and [COMPILE], without requiring that the user know whether +or not the postponed word is immediate. + +

+ +Similarly, the use of ' and ['] with compiling words is unclear if the +precise compilation behavior of those words is not specified, so ANS +Forth does not permit a Standard Program to use ' or ['] with compiling +words. + +

+ +The traditional (non-immediate) definition of the word COMPILE has an +additional problem. Its traditional definition assumes a threaded code +implementation technique, and its behavior can only be properly +described in that context. In the context of ANS Forth, which permits +other implementation techniques in addition to threaded code, it is very +difficult, if not impossible, to describe the behavior of the +traditional COMPILE. Rather than changing its behavior, and thus +breaking existing code, ANS Forth does not include the word COMPILE. +This allows existing implementations to continue to supply the word +COMPILE with its traditional behavior, if that is appropriate for the +implementation. + +

+ +Impact: [COMPILE] remains in ANS Forth, since its proper use does not +depend on knowledge of whether or not a word is immediate (Use of +[COMPILE] with a non-immediate word is and has always been a no-op). +Whether or not you need to use [COMPILE] requires knowledge of whether +or not its target word is immediate, but it is always safe to use +[COMPILE]. [COMPILE] is no longer in the (required) core word set, +having been moved to the Core Extensions word set, but the committee +anticipates that most vendors will supply it anyway. + +

+ +In nearly all cases, it is correct to replace both [COMPILE] and COMPILE +with POSTPONE. Uses of [COMPILE] and COMPILE that are not suitable for +mindless replacement by POSTPONE are quite infrequent, and fall +into the following two categories: + +

+ +a) Use of [COMPILE] with non-immediate words. This is sometimes done +with the words '-(tick, which was immediate in Forth-79 but not in Forth-83) +and LEAVE (which was immediate in Forth-83 but not in Forth-79), in order to +force the compilation of those words without regard to whether you are using a +Forth-79 or Forth-83 system. + +

+ +b) Use of the phrase COMPILE [COMPILE] <immediate word> to +doubly +postpone an immediate word. + +

+ +Transition/Conversion: Many ANS Forth implementations will continue to +implement both [COMPILE] and COMPILE in forms compatible with existing usage. +In those environments, no conversion is necessary. + +

+ +For complete portability, uses of COMPILE and [COMPILE] should be +changed to POSTPONE , except in the rare cases indicated above. Uses of +[COMPILE] with non-immediate words may be left as-is, and the program +may declare a requirement for the word [COMPILE] from the Core +Extensions word set, or the [COMPILE] before the non-immediate word may +be simply deleted if the target word is known to be non-immediate. + +

+ +Uses of the phrase COMPILE [COMPILE] <immediate-word> may be handled by +introducing an intermediate word (XX in the example below) and +then postponing that word. For example: + + +

+
+	: ABC  COMPILE [COMPILE] IF  ;
+
+
+

+ +changes to: +

+ + +

+	: XX  POSTPONE IF  ;
+	: ABC  POSTPONE XX  ;
+
+

+ +A non-standard case can occur with programs that switch out of +compilation state to explicitly compile a thread in the dictionary +following a COMPILE . For example: + + +

+	: XYZ  COMPILE  [ ' ABC , ]  ;
+
+

+ +This depends heavily on knowledge of exactly how COMPILE and the +threaded-code implementation works. Cases like this cannot be handled +mechanically; they must be translated by understanding exactly what the +code is doing, and rewriting that section according to ANS Forth +restrictions. + +

+ +Use the phrase POSTPONE [COMPILE] +to replace [COMPILE] [COMPILE]. + +

+ +


+ +

D.6.8 Input character set

+
+ +Forth-83 specifies that the full 7-bit ASCII character set is available +through +KEY. +ANS Forth restricts it to the graphic characters of the +ASCII set, with codes from hex 20 to hex 7E inclusive. + +

+ +Words Affected: +KEY +

+ +Reason: Many system environments consume certain control +characters for such purposes as input editing, job control, or flow +control. A Forth implementation cannot always control this system +behavior. + +

+ +Impact: Standard Programs which require the ability to receive +particular control characters through KEY must declare an environmental +dependency on the input character set. + +

+ +Transition/Conversion: For maximum portability, programs should restrict +their required input character set to only the graphic characters. +Control characters may be handled if available, but complete program +functionality should be accessible using only graphic characters. + +

+ +As stated above, an environmental dependency on the input character set +may be declared. Even so, it is recommended that the program should +avoid the requirement for particularly-troublesome control characters, +such as control-S and control-Q (often used for flow control, sometimes +by communication hardware whose presence may be difficult to detect), +ASCII NUL (difficult to type on many keyboards), and the distinction +between carriage return and line feed (some systems translate carriage +returns into line feeds, or vice versa). + +

+ +


+ +

D.6.9 Shifting with UM/MOD

+
+ +Given Forth-83's two's-complement nature, and its requirement for +floored (round toward minus infinity) division, shifting is equivalent +to division. Also, two's-complement representation implies that +unsigned division by a power of two is equivalent to logical +right-shifting, so UM/MOD could be used to perform a logical +right-shift. + +

+ +Words Affected: +UM/MOD +

+ +Reason: The problem with UM/MOD is a result of allowing +non-two's-complement number representations, as already described. + +

+ +ANS Forth provides the words +LSHIFT and +RSHIFT +to perform logical +shifts. This is usually more efficient, and certainly more descriptive, +than the use of UM/MOD for logical shifting. + +

+ +Impact: Programs running on ANS Forth systems with two's-complement +arithmetic (the majority of machines), will not experience any +incompatibility with UM/MOD . Existing Forth-83 Standard programs +intended to run on non-two's-complement machines will not be able to use +UM/MOD for shifting on a non-two's-complement ANS Forth system. This +should not affect a significant number of existing programs (perhaps +none at all), since the committee knows of no existing Forth-83 +implementations on non-two's-complement machines. + +

+ +Transition/Conversion: A program that requires UM/MOD to behave as a +shift operation may declare an environmental dependency on +two's-complement arithmetic. + +

+ +A program that cannot declare an environmental dependency on +two's-complement arithmetic may require editing to replace incompatible +uses of UM/MOD with other operators defined within the application. + +

+ +


+ +

D.6.10 Vocabularies / wordlists

+
+ +ANS Forth does not define the words VOCABULARY, CONTEXT, and CURRENT , +which were present in Forth-83. Instead, ANS Forth defines a primitive +word set for search order specification and control, including words +which have not existed in any previous standard. + +

+ +Forth-83's +ALSO/ONLY +experimental search order word set is +specified for the most part as the extension portion of the ANS Forth +Search Order word set. + +

+ +Words Affected: +VOCABULARY CONTEXT CURRENT +

+ +Reason: Vocabularies are an area of much divergence among existing +systems. Considering major vendors' systems and previous standards, +there are at least 5 different and mutually incompatible behaviors of +words defined by VOCABULARY. Forth-83 took a step in the direction of +run-time search-order specification by declining to specify a +specific relationship between the hierarchy of compiled vocabularies and +the run-time search order. Forth-83 also specified an experimental +mechanism for run-time search-order specification, the ALSO/ONLY scheme. +ALSO/ONLY was implemented in numerous systems, and has achieved some +measure of popularity in the Forth community. + +

+ +However, several vendors refuse to implement it, citing technical +limitations. In an effort to address those limitations and thus +hopefully make ALSO/ONLY more palatable to its critics, the committee +specified a simple primitive word set that not only fixes some of +the objections to ALSO/ONLY, but also provides sufficient power to +implement ALSO/ONLY and all of the other search-order word sets that are +currently popular. + +

+ +The Forth-83 ALSO/ONLY word set is provided as an optional extension to +the search-order word set. This allows implementors that are so +inclined to provide this word set, with well-defined standard behavior, +but does not compel implementors to do so. Some vendors have publicly +stated that they will not implement ALSO/ONLY, no matter what, and one +major vendor stated an unwillingness to implement ANS Forth at all if +ALSO/ONLY is mandated. The committee feels that its actions are +prudent, specifying ALSO/ONLY to the extent possible without mandating +its inclusion in all systems, and also providing a primitive +search-order word set that vendors may be more likely to implement, and +which can be used to synthesize ALSO/ONLY. + +

+ +Transition/Conversion: Since Forth-83 did not mandate precise semantics +for VOCABULARY, existing Forth-83 Standard programs cannot use it except +in a trivial way. Programs can declare a dependency on the existence of +the Search Order word set, and can implement whatever semantics are +required using that word set's primitives. Forth-83 programs that need +ALSO/ONLY can declare a dependency on the Search Order Extensions word +set, or can implement the extensions in terms of the Search Order word +set itself. + +

+ +


+ +

D.6.11 Multiprogramming impact

+
+ +Forth-83 marked words with multiprogramming impact by the letter +M in the first lines of their descriptions. ANS Forth has +removed the M designation from the word descriptions, moving the +discussion of multiprogramming impact to this non-normative annex. + +

+ +Words affected: none +

+ +Reason: The meaning of multiprogramming impact is precise only in +the context of a specific model for multiprogramming. Although many +Forth systems do provide multiprogramming capabilities using a +particular round-robin, cooperative, block-buffer sharing model, that +model is not universal. Even assuming the classical model, the M +designations did not contain enough information to enable writing of +applications that interacted in a multiprogrammed system. + +

+ +Practically speaking, the M designations in Forth-83 served to +document usage rules for block buffer addresses in multiprogrammed +systems. These addresses often become meaningless after a task has +relinquished the CPU for any reason, most often for the purposes of +performing I/O, awaiting an event, or voluntarily sharing CPU resources +using the word PAUSE. It was essential that portable applications +respect those usage rules to make it practical to run them on +multiprogrammed systems; failure to adhere to the rules could easily +compromise the integrity of other applications running on those systems +as well as the applications actually in error. Thus, M appeared +on all words that by design gave up the CPU, with the understanding that +other words NEVER gave it up. + +

+ +These usage rules have been explicitly documented in the Block word set +where they are relevant. The M designations have been removed +entirely. + +

+ +Impact: In practice, none. +

+ +In the sense that any application that depends on multiprogramming must +consist of at least two tasks that share some resource(s) and +communicate between themselves, Forth-83 did not contain enough +information to enable writing of a standard program that DEPENDED on +multiprogramming. This is also true of ANS Forth. + +

+ +Non-multiprogrammed applications in Forth-83 were required to respect +usage rules for +BLOCK +so that they could be run properly on +multiprogrammed systems. The same is true of ANS Forth. + +

+ +The only difference is the documentation method used to define the BLOCK +usage rules. The Technical Committee believes that the current method +is clearer than the concept of multiprogramming impact. + +

+ +Transition/Conversion: +none needed. + +

+ +


+ +

D.6.12 Words not provided in executable form

+
+ +ANS Forth allows an implementation to supply some words in source code +or load as needed form, rather than requiring all supplied words +to be available with no additional programmer action. + +

+ +Words affected: all +

+ +Reason: Forth systems are often used in environments where memory space +is at a premium. Every word included in the system in executable form +consumes memory space. The committee believes that allowing standard +words to be provided in source form will increase the probability that +implementors will provide complete ANS Forth implementations even in +systems designed for use in constrained environments. + +

+ +Impact: In order to use a Standard Program with a given ANS Forth +implementation, it may be necessary to precede the program with an +implementation-dependent preface to make source form words +executable. This is similar to the methods that other computer +languages require for selecting the library routines needed by a +particular application. + +

+ +In languages like C, the goal of eliminating unnecessary routines from +the memory image of an application is usually accomplished by providing +libraries of routines, using a linker program to incorporate only +the necessary routines into an executable application. The method of +invoking and controlling the linker is outside the scope of the language +definition. + +

+ +Transition/Conversion: Before compiling a program, the programmer may +need to perform some action to make the words required by that program +available for execution. +

+ +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpanse.htm b/docs/reference/standards/ans94/dpanse.htm new file mode 100644 index 00000000..ea567ccc --- /dev/null +++ b/docs/reference/standards/ans94/dpanse.htm @@ -0,0 +1,631 @@ + +DPANS94 + + + + + + + + +
+ + + + +Table of Contents +
+

+


+ +

E. ANS Forth portability guide (informative +annex)

+ + +
+ +

E.1 Introduction

+
+ +The most popular architectures used to implement Forth have had +byte-addressed memory, 16-bit operations, and two's-complement number +representation. The Forth-83 Standard dictates that these particular +features must be present in a Forth-83 Standard system and that Forth-83 +programs may exploit these features freely. + +

+ +However, there are many beasts in the architectural jungle that are bit +addressed or cell addressed, or prefer 32-bit operations, or represent +numbers in one's complement. Since one of Forth's strengths is its +usefulness in strange environments on unusual hardware +with peculiar features, it is important that a Standard Forth run +on these machines too. + +

+ +A primary goal of the ANS Forth Standard is to increase the types of +machines that can support a Standard Forth. This is accomplished by +allowing some key Forth terms to be implementation-defined (e.g., how +big is a cell?) and by providing Forth operators (words) that conceal +the implementation. This frees the implementor to produce the Forth +system that most effectively utilizes the native hardware. The machine +independent operators, together with some programmer discipline, enable +a programmer to write Forth programs that work on a wide variety of +machines. + +

+ +The remainder of this Annex provides guidelines for writing portable ANS +Forth programs. The first section describes ways to make a program +hardware independent. It is difficult for someone familiar with only +one machine architecture to imagine the problems caused by transporting +programs between dissimilar machines. Consequently, examples of +specific architectures with their respective problems are given. The +second section describes assumptions about Forth implementations that +many programmers make, but can't be relied upon in a portable program. + +

+ + +


+ +

E.2 Hardware peculiarities

+
+ + +
+ +

E.2.1 Data/memory abstraction

+
+ +Data and memory are the stones and mortar of program construction. +Unfortunately, each computer treats data and memory differently. The +ANS Forth Systems Standard gives definitions of data and memory that +apply to a wide variety of computers. These definitions give us a way +to talk about the common elements of data and memory while ignoring the +details of specific hardware. Similarly, ANS Forth programs that use +data and memory in ways that conform to these definitions can also +ignore hardware details. The following sections discuss the definitions +and describe how to write programs that are independent of the +data/memory peculiarities of different computers. +

+ + + +


+ +

E.2.2 Definitions

+
+ +Three terms defined by ANS Forth are address unit, cell, and character. +The address space of an ANS Forth system is divided into an array of +address units; an address unit is the smallest collection of bits that +can be addressed. In other words, an address unit is the number of bits +spanned by the addresses addr and addr+1. The most prevalent machines +use 8-bit address units. Such byte addressed machines include +the Intel 8086 and Motorola 68000 families. However, other address unit +sizes exist. There are machines that are bit addressed and machines +that are 4-bit nibble addressed. There are also machines with address +units larger than 8-bits. For example, several Forth-in-hardware +computers are cell addressed. + +

+ +The cell is the fundamental data type of a Forth system. A cell can be +a single-cell integer or a memory address. Forth's parameter and return +stacks are stacks of cells. Forth-83 specifies that a cell is 16-bits. +In ANS Forth the size of a cell is an implementation-defined number of +address units. Thus, an ANS Forth implemented on a 16-bit +microprocessor could use a 16-bit cell and an implementation on a 32-bit +machine could use a 32-bit cell. Also 18-bit machines, 36-bit machines, +etc., could support ANS Forth systems with 18 or 36-bit cells +respectively. In all of these systems, +DUP +does the same thing: it +duplicates the top of the data stack. +! (store) +behaves consistently +too: given two cells on the data stack it stores the second cell in the +memory location designated by the top cell. + +

+ +Similarly, the definition of a character has been generalized to be an +implementation-defined number of address units (but at least eight +bits). This removes the need for a Forth implementor to provide 8-bit +characters on processors where it is inappropriate. For example, on an +18-bit machine with a 9-bit address unit, a 9-bit character would be +most convenient. Since, by definition, you can't address anything +smaller than an address unit, a character must be at least as big as an +address unit. This will result in big characters on machines with large +address units. An example is a 16-bit cell addressed machine where a +16-bit character makes the most sense. + +

+ + +


+ +

E.2.3 Addressing memory

+
+ +ANS Forth eliminates many portability problems by using the above +definitions. One of the most common portability problems is addressing +successive cells in memory. Given the memory address of a cell, how do +you find the address of the next cell? In Forth-83 this is easy: 2 + . +This code assumes that memory is addressed in 8-bit units (bytes) and a +cell is 16-bits wide. On a byte-addressed machine with 32-bit cells the +code to find the next cell would be 4 + . The code would be 1+ on a +cell-addressed processor and 16+ on a bit-addressed processor with +16-bit cells. ANS Forth provides a next-cell operator named +CELL+ +that +can be used in all of these cases. Given an address, CELL+ adjusts the +address by the size of a cell (measured in address units). A related +problem is that of addressing an array of cells in an arbitrary order. +A defining word to create an array of cells using Forth-83 would be: + + +
+	: ARRAY   CREATE  2* ALLOT  DOES> SWAP 2* + ;
+
+ +

+ +Use of +2* +to scale the array index assumes byte addressing and 16-bit +cells again. As in the example above, different versions of the code +would be needed for different machines. ANS Forth provides a portable +scaling operator named +CELLS. +Given a number n, CELLS returns the +number of address units needed to hold n cells. A portable definition +of array is: + +

+	: ARRAY   CREATE  CELLS ALLOT
+	   DOES> SWAP CELLS + ;
+
+

+ +There are also portability problems with addressing arrays of +characters. In Forth-83 (and in the most common ANS Forth +implementations), the size of a character will equal the size of an +address unit. Consequently addresses of successive characters in memory +can be found using +1+ +and scaling indices into a character array is a +no-op (i.e., 1 *). However, there are cases where a character is larger +than an address unit. Examples include (1) systems with small address +units (e.g., bit- and nibble-addressed systems), and (2) systems with +large character sets (e.g., 16-bit characters on a byte-addressed +machine). +CHAR+ +and +CHARS +operators, analogous to CELL+ and CELLS are +available to allow maximum portability. +

+ +ANS Forth generalizes the definition of some Forth words that operate on +chunks of memory to use address units. One example is +ALLOT. By +prefixing ALLOT with the appropriate scaling operator (CELLS, CHARS, +etc.), space for any desired data structure can be allocated (see +definition of array above). For example: + +

+	CREATE ABUFFER 5 CHARS ALLOT ( allot 5 character buffer)
+
+

+ +The memory-block-move +word also uses address units: + + +

+	source destination 8 CELLS MOVE  (  move 8 cells)
+
+

+ + +


+ +

E.2.4 Alignment problems

+
+ +Not all addresses are created equal. Many processors have restrictions +on the addresses that can be used by memory access instructions. This +Standard does not require an implementor of an ANS Forth to make +alignment transparent; on the contrary, it requires (in +Section 3.3.3.1 +Address alignment) that an ANS Forth program assume that character and +cell alignment may be required. + +

+ +One of the most common problems caused by alignment restrictions is in +creating tables containing both characters and cells. When +, (comma) or +C, +is used to initialize a table, data is stored at the data-space +pointer. Consequently, it must be suitably aligned. For example, a +non-portable table definition would be: + + +

+	CREATE ATABLE   1 C,  X ,  2 C,  Y ,
+
+ +

+ +On a machine that restricts 16-bit fetches to even addresses, +CREATE +would leave the data space pointer at an even address, the 1 C, would +make the data space pointer odd, and , (comma) would violate the address +restriction by storing X at an odd address. A portable way to create +the table is: + + +

+	CREATE ATABLE   1 C,  ALIGN X ,  2 C,  ALIGN Y ,
+
+ +

+ +ALIGN +adjusts the data space pointer to the first aligned address +greater than or equal to its current address. An aligned address is +suitable for storing or fetching characters, cells, cell pairs, or +double-cell numbers. + +

+ +After initializing the table, we would also like to read values from the +table. For example, assume we want to fetch the first cell, X, from the +table. ATABLE CHAR+ gives the address of the first thing after the +character. However this may not be the address of X since we aligned +the dictionary pointer between the C, and the ,. The portable way to +get the address of X is: + + +

+	ATABLE CHAR+ ALIGNED
+
+ +

+ +ALIGNED +adjusts the address on top of the stack to the first aligned +address greater than or equal to its current value. + +

+ + +


+ +

E.3 Number representation

+
+ +Different computers represent numbers in different ways. An awareness +of these differences can help a programmer avoid writing a program that +depends on a particular representation. + +

+ + +


+ +

E.3.1 Big endian vs. little endian

+
+ +The constituent bits of a number in memory are kept in different orders +on different machines. Some machines place the most-significant part of +a number at an address in memory with less-significant parts following +it at higher addresses. Other machines do the opposite the +least-significant part is stored at the lowest address. For example, +the following code for a 16-bit 8086 little endian Forth would +produce the answer 34 (hex): + + +
+	VARIABLE FOO   HEX 1234 FOO !   FOO C@
+
+

+ +The same code on a 16-bit 68000 big endian Forth would produce +the answer 12 (hex). A portable program cannot exploit the +representation of a number in memory. + +

+ +A related issue is the representation of cell pairs and double-cell +numbers in memory. When a cell pair is moved from the stack to memory +with +2!, +the cell that was on top of the stack is placed at the lower +memory address. It is useful and reasonable to manipulate the +individual cells when they are in memory. + +

+ + +


+ +

E.3.2 ALU organization

+
+ +Different computers use different bit patterns to represent integers. +Possibilities include binary representations (two's complement, one's +complement, sign magnitude, etc.) and decimal representations (BCD, +etc.). Each of these formats creates advantages and disadvantages in +the design of a computer's arithmetic logic unit (ALU). The most +commonly used representation, two's complement, is popular because of +the simplicity of its addition and subtraction algorithms. + +

+ +Programmers who have grown up on two's complement machines tend to +become intimate with their representation of numbers and take some +properties of that representation for granted. For example, a trick to +find the remainder of a number divided by a power of two is to mask off +some bits with +AND. +A common application of this trick is to test a +number for oddness using 1 AND. However, this will not work on a one's +complement machine if the number is negative (a portable technique is 2 +MOD). + +

+ +The remainder of this section is a (non-exhaustive) list of things to +watch for when portability between machines with binary representations +other than two's complement is desired. + +

+ +To convert a single-cell number to a double-cell number, ANS Forth +provides the operator +S>D. +To convert a double-cell number to +single-cell, Forth programmers have traditionally used +DROP. +However, +this trick doesn't work on sign-magnitude machines. For portability a +D>S +operator is available. Converting an unsigned single-cell number to +a double-cell number can be done portably by pushing a zero on the +stack. + +

+ + +


+ +

E.4 Forth system implementation

+
+ +During Forth's history, an amazing variety of implementation techniques +have been developed. The ANS Forth Standard encourages this diversity +and consequently restricts the assumptions a user can make about the +underlying implementation of an ANS Forth system. Users of a particular +Forth implementation frequently become accustomed to aspects of the +implementation and assume they are common to all Forths. This section +points out many of these incorrect assumptions. + +

+ + +


+ +

E.4.1 Definitions

+
+ +Traditionally, Forth definitions have consisted of the name of the Forth +word, a dictionary search link, data describing how to execute the +definition, and parameters describing the definition itself. These +components are called the name, link, code, and parameter fields. No +method for accessing these fields has been found that works across all +of the Forth implementations currently in use. Therefore, ANS Forth +severely restricts how the fields may be used. Specifically, a portable +ANS Forth program may not use the name, link, or code field in any way. +Use of the parameter field (renamed to data field for clarity) is +limited to the operations described below. + +

+ +Only words defined with +CREATE +or with other defining words that call +CREATE have data fields. The other defining words in the Standard +(VARIABLE, +CONSTANT, +:, +etc.) might not be implemented with CREATE. +Consequently, a Standard Program must assume that words defined by +VARIABLE, CONSTANT, : , etc., may have no data fields. There is no way +for a Standard Program to modify the value of a constant or to change +the meaning of a colon definition. The +DOES> +part of a defining word +operates on a data field. Since only CREATEd words have data fields, +DOES> can only be paired with CREATE or words that call CREATE. + +

+ +In ANS Forth, +FIND, +['] and +' (tick) +return an unspecified entity called +an execution token. There are only a few things that may be done +with an execution token. The token may be passed to +EXECUTE +to execute +the word ticked or compiled into the current definition with +COMPILE,. +The token can also be stored in a variable and used later. Finally, if +the word ticked was defined via CREATE, +>BODY +converts the execution +token into the word's data-field address. + +

+ +One thing that definitely cannot be done with an execution token is use +! +or +, +to store it into the object code of a Forth definition. This +technique is sometimes used in implementations where the object code is +a list of addresses (threaded code) and an execution token is also an +address. However, ANS Forth permits native code implementations where +this will not work. + +

+ + +


+ +

E.4.2 Stacks

+
+ +In some Forth implementations, it is possible to find the address of a +stack in memory and manipulate the stack as an array of cells. This +technique is not portable, however. On some systems, especially +Forth-in-hardware systems, the stacks might be in a part of memory that +can't be addressed by the program or might not be in memory at all. +Forth's parameter and return stacks must be treated as stacks. + +

+ +A Standard Program may use the return stack directly only for +temporarily storing values. Every value examined or removed from the +return stack using +R@, +R>, or +2R> +must have been put on the stack +explicitly using +>R or +2>R. +Even this must be done carefully since the +system may use the return stack to hold return addresses and +loop-control parameters. +Section 3.2.3.3 Return stack of the Standard +has a list of restrictions. + +

+ + +


+ +

E.5 ROMed application disciplines and conventions

+
+ +When a Standard System provides a data space which is uniformly readable +and writeable we may term this environment RAM-only. + +

+ +Programs designed for ROMed application must divide data space into at +least two parts: a writeable and readable uninitialized part, called +RAM, and a read-only initialized part, called ROM. A +third possibility, a writeable and readable initialized part, normally +called initialized RAM, is not addressed by this discipline. A +Standard Program must explicitly initialize the RAM data space as +needed. + +

+ +The separation of data space into RAM and ROM is meaningful only during +the generation of the ROMed program. If the ROMed program is itself a +standard development system, it has the same taxonomy as an ordinary +RAM-only system. + +

+ +The words affected by conversion from a RAM-only to a mixed RAM and ROM +environment are: + +

+, (comma) +ALIGN +ALIGNED +ALLOT +C, +CREATE +HERE +UNUSED +

+ +(VARIABLE always +accesses the RAM data space.) + +

+ +With the exception of , (comma) and C, +these words are meaningful in both RAM +and ROM data space. + +

+ +To select the data space, these words could be preceded by selectors RAM +and ROM. For example: + + +

+	ROM  CREATE ONES  32 ALLOT  ONES 32 1 FILL  RAM
+
+ +

+ +would create a table of ones in the ROM data space. The storage of data +into RAM data space when generating a program for ROM would be an +ambiguous condition. + +

+ +A straightforward implementation of these selectors would maintain +separate address counters for each space. A counter value would be +returned by HERE and altered by , (comma), C,, ALIGN, and ALLOT, with +RAM and ROM simply selecting the appropriate address counter. This +technique could be extended to additional partitions of the data space. + +

+ + +


+ +

E.6 Summary

+
+ +The ANS Forth Standard cannot and should not force anyone to write a +portable program. In situations where performance is paramount, the +programmer is encouraged to use every trick in the book. On the other +hand, if portability to a wide variety of systems is needed, ANS Forth +provides the tools to accomplish this. There is probably no such thing +as a completely portable program. A programmer, using this guide, +should intelligently weigh the tradeoffs of providing portability to +specific machines. For example, machines that use sign-magnitude +numbers are rare and probably don't deserve much thought. But, systems +with different cell sizes will certainly be encountered and should be +provided for. In general, making a program portable clarifies both the +programmer's thinking process and the final program. + +

+ + +


+ Table of Contents +
+ +Next Section +

+ + diff --git a/docs/reference/standards/ans94/dpansf.htm b/docs/reference/standards/ans94/dpansf.htm new file mode 100644 index 00000000..595b3edf --- /dev/null +++ b/docs/reference/standards/ans94/dpansf.htm @@ -0,0 +1,430 @@ + +DPANS94 + + + + + + + + +
+ + + +Table of Contents +
+

+


+ +

F. Alphabetic list of words (informative +annex)

+ +In the following list, the last, four-digit, part of the reference number +establishes a sequence corresponding to the alphabetic ordering of all +standard words. The first two or three parts indicate the word set and +glossary section in which the word is defined. + + +
+          .6.1.0010   !           store                 CORE
+          .6.1.0030   #           number-sign           CORE
+          .6.1.0040   #>          number-sign-greater   CORE
+          .6.1.0050   #S          number-sign-s         CORE
+          .6.2.0060   #TIB        number-t-i-b          CORE EXT
+          .6.1.0070   '           tick                  CORE
+          .6.1.0080   (           paren                 CORE
+        11.6.1.0080   (           paren                 FILE
+        13.6.1.0086   (LOCAL)     paren-local-paren     LOCAL
+          .6.1.0090   *           star                  CORE
+          .6.1.0100   */          star-slash            CORE
+          .6.1.0110   */MOD       star-slash-mod        CORE
+          .6.1.0120   +           plus                  CORE
+          .6.1.0130   +!          plus-store            CORE
+          .6.1.0140   +LOOP       plus-loop             CORE
+          .6.1.0150   ,           comma                 CORE
+          .6.1.0160   -           minus                 CORE
+        17.6.1.0170   -TRAILING   dash-trailing         STRING
+          .6.1.0180   .           dot                   CORE
+          .6.1.0190   ."          dot-quote             CORE
+          .6.2.0200   .(          dot-paren             CORE EXT
+          .6.2.0210   .R          dot-r                 CORE EXT
+        15.6.1.0220   .S          dot-s                 TOOLS
+          .6.1.0230   /           slash                 CORE
+          .6.1.0240   /MOD        slash-mod             CORE
+        17.6.1.0245   /STRING     slash-string          STRING
+          .6.1.0250   0<          zero-less             CORE
+          .6.2.0260   0<>         zero-not-equals       CORE EXT
+          .6.1.0270   0=          zero-equals           CORE
+          .6.2.0280   0>          zero-greater          CORE EXT
+          .6.1.0290   1+          one-plus              CORE
+          .6.1.0300   1-          one-minus             CORE
+          .6.1.0310   2!          two-store             CORE
+          .6.1.0320   2*          two-star              CORE
+          .6.1.0330   2/          two-slash             CORE
+          .6.2.0340   2>R         two-to-r              CORE EXT
+          .6.1.0350   2@          two-fetch             CORE
+         8.6.1.0360   2CONSTANT   two-constant          DOUBLE
+          .6.1.0370   2DROP       two-drop              CORE
+          .6.1.0380   2DUP        two-dupe              CORE
+         8.6.1.0390   2LITERAL    two-literal           DOUBLE
+          .6.1.0400   2OVER       two-over              CORE
+          .6.2.0410   2R>         two-r-from            CORE EXT
+          .6.2.0415   2R@         two-r-fetch           CORE EXT
+         8.6.2.0420   2ROT        two-rote              DOUBLE EXT
+          .6.1.0430   2SWAP       two-swap              CORE
+         8.6.1.0440   2VARIABLE   two-variable          DOUBLE
+          .6.1.0450   :           colon                 CORE
+          .6.2.0455   :NONAME     colon-no-name         CORE EXT
+          .6.1.0460   ;           semicolon             CORE
+        15.6.2.0470   ;CODE       semicolon-code        TOOLS EXT
+          .6.1.0480   <           less-than             CORE
+          .6.1.0490   <#          less-number-sign      CORE
+          .6.2.0500   <>          not-equals            CORE EXT
+          .6.1.0530   =           equals                CORE
+          .6.1.0540   >           greater-than          CORE
+          .6.1.0550   >BODY       to-body               CORE
+        12.6.1.0558   >FLOAT      to-float              FLOATING
+          .6.1.0560   >IN         to-in                 CORE
+          .6.1.0570   >NUMBER     to-number             CORE
+          .6.1.0580   >R          to-r                  CORE
+        15.6.1.0600   ?           question              TOOLS
+          .6.2.0620   ?DO         question-do           CORE EXT
+          .6.1.0630   ?DUP        question-dupe         CORE
+          .6.1.0650   @           fetch                 CORE
+          .6.1.0670   ABORT                             CORE
+         9.6.2.0670   ABORT                             EXCEPTION EXT
+          .6.1.0680   ABORT"      abort-quote           CORE
+         9.6.2.0680   ABORT"      abort-quote           EXCEPTION EXT
+          .6.1.0690   ABS         abs                   CORE
+          .6.1.0695   ACCEPT                            CORE
+          .6.2.0700   AGAIN                             CORE EXT
+        15.6.2.0702   AHEAD                             TOOLS EXT
+          .6.1.0705   ALIGN                             CORE
+          .6.1.0706   ALIGNED                           CORE
+        14.6.1.0707   ALLOCATE                          MEMORY
+          .6.1.0710   ALLOT                             CORE
+        16.6.2.0715   ALSO                              SEARCH EXT
+          .6.1.0720   AND                               CORE
+        15.6.2.0740   ASSEMBLER                         TOOLS EXT
+        10.6.1.0742   AT-XY       at-x-y                FACILITY
+          .6.1.0750   BASE                              CORE
+          .6.1.0760   BEGIN                             CORE
+        11.6.1.0765   BIN                               FILE
+          .6.1.0770   BL          b-l                   CORE
+        17.6.1.0780   BLANK                             STRING
+         7.6.1.0790   BLK         b-l-k                 BLOCK
+         7.6.1.0800   BLOCK                             BLOCK
+         7.6.1.0820   BUFFER                            BLOCK
+        15.6.2.0830   BYE                               TOOLS EXT
+          .6.1.0850   C!          c-store               CORE
+          .6.2.0855   C"          c-quote               CORE EXT
+          .6.1.0860   C,          c-comma               CORE
+          .6.1.0870   C@          c-fetch               CORE
+          .6.2.0873   CASE                              CORE EXT
+         9.6.1.0875   CATCH                             EXCEPTION
+          .6.1.0880   CELL+       cell-plus             CORE
+          .6.1.0890   CELLS                             CORE
+          .6.1.0895   CHAR        char                  CORE
+          .6.1.0897   CHAR+       char-plus             CORE
+          .6.1.0898   CHARS       chars                 CORE
+        11.6.1.0900   CLOSE-FILE                        FILE
+        17.6.1.0910   CMOVE       c-move                STRING
+        17.6.1.0920   CMOVE>      c-move-up             STRING
+        15.6.2.0930   CODE                              TOOLS EXT
+        17.6.1.0935   COMPARE                           STRING
+          .6.2.0945   COMPILE,    compile-comma         CORE EXT
+          .6.1.0950   CONSTANT                          CORE
+          .6.2.0970   CONVERT                           CORE EXT
+          .6.1.0980   COUNT                             CORE
+          .6.1.0990   CR          c-r                   CORE
+          .6.1.1000   CREATE                            CORE
+        11.6.1.1010   CREATE-FILE                       FILE
+        15.6.2.1015   CS-PICK     c-s-pick              TOOLS EXT
+        15.6.2.1020   CS-ROLL     c-s-roll              TOOLS EXT
+         8.6.1.1040   D+          d-plus                DOUBLE
+         8.6.1.1050   D-          d-minus               DOUBLE
+         8.6.1.1060   D.          d-dot                 DOUBLE
+         8.6.1.1070   D.R         d-dot-r               DOUBLE
+         8.6.1.1075   D0<         d-zero-less           DOUBLE
+         8.6.1.1080   D0=         d-zero-equals         DOUBLE
+         8.6.1.1090   D2*         d-two-star            DOUBLE
+         8.6.1.1100   D2/         d-two-slash           DOUBLE
+         8.6.1.1110   D<          d-less-than           DOUBLE
+         8.6.1.1120   D=          d-equals              DOUBLE
+        12.6.1.1130   D>F         d-to-f                FLOATING
+         8.6.1.1140   D>S         d-to-s                DOUBLE
+         8.6.1.1160   DABS        d-abs                 DOUBLE
+          .6.1.1170   DECIMAL                           CORE
+        16.6.1.1180   DEFINITIONS                       SEARCH
+        11.6.1.1190   DELETE-FILE                       FILE
+          .6.1.1200   DEPTH                             CORE
+        12.6.2.1203   DF!         d-f-store             FLOATING EXT
+        12.6.2.1204   DF@         d-f-fetch             FLOATING EXT
+        12.6.2.1205   DFALIGN     d-f-align             FLOATING EXT
+        12.6.2.1207   DFALIGNED   d-f-aligned           FLOATING EXT
+        12.6.2.1208   DFLOAT+     d-float-plus          FLOATING EXT
+        12.6.2.1209   DFLOATS     d-floats              FLOATING EXT
+         8.6.1.1210   DMAX        d-max                 DOUBLE
+         8.6.1.1220   DMIN        d-min                 DOUBLE
+         8.6.1.1230   DNEGATE     d-negate              DOUBLE
+          .6.1.1240   DO                                CORE
+          .6.1.1250   DOES>       does                  CORE
+          .6.1.1260   DROP                              CORE
+         8.6.2.1270   DU<         d-u-less              DOUBLE EXT
+        15.6.1.1280   DUMP                              TOOLS
+          .6.1.1290   DUP         dupe                  CORE
+        15.6.2.1300   EDITOR                            TOOLS EXT
+        10.6.2.1305   EKEY        e-key                 FACILITY EXT
+        10.6.2.1306   EKEY>CHAR   e-key-to-char         FACILITY EXT
+        10.6.2.1307   EKEY?       e-key-question        FACILITY EXT
+          .6.1.1310   ELSE                              CORE
+          .6.1.1320   EMIT                              CORE
+        10.6.2.1325   EMIT?       emit-question         FACILITY EXT
+         7.6.2.1330   EMPTY-BUFFERS                     BLOCK EXT
+          .6.2.1342   ENDCASE     end-case              CORE EXT
+          .6.2.1343   ENDOF       end-of                CORE EXT
+          .6.1.1345   ENVIRONMENT?environment-query     CORE
+          .6.2.1350   ERASE                             CORE EXT
+          .6.1.1360   EVALUATE                          CORE
+         7.6.1.1360   EVALUATE                          BLOCK
+          .6.1.1370   EXECUTE                           CORE
+          .6.1.1380   EXIT                              CORE
+          .6.2.1390   EXPECT                            CORE EXT
+        12.6.1.1400   F!          f-store               FLOATING
+        12.6.1.1410   F*          f-star                FLOATING
+        12.6.2.1415   F**         f-star-star           FLOATING EXT
+        12.6.1.1420   F+          f-plus                FLOATING
+        12.6.1.1425   F-          f-minus               FLOATING
+        12.6.2.1427   F.          f-dot                 FLOATING EXT
+        12.6.1.1430   F/          f-slash               FLOATING
+        12.6.1.1440   F0<         f-zero-less-than      FLOATING
+        12.6.1.1450   F0=         f-zero-equals         FLOATING
+        12.6.1.1460   F<          f-less-than           FLOATING
+        12.6.1.1470   F>D         f-to-d                FLOATING
+        12.6.1.1472   F@          f-fetch               FLOATING
+        12.6.2.1474   FABS        f-abs                 FLOATING EXT
+        12.6.2.1476   FACOS       f-a-cos               FLOATING EXT
+        12.6.2.1477   FACOSH      f-a-cosh              FLOATING EXT
+        12.6.1.1479   FALIGN      f-align               FLOATING
+        12.6.1.1483   FALIGNED    f-aligned             FLOATING
+        12.6.2.1484   FALOG       f-a-log               FLOATING EXT
+          .6.2.1485   FALSE                             CORE EXT
+        12.6.2.1486   FASIN       f-a-sine              FLOATING EXT
+        12.6.2.1487   FASINH      f-a-cinch             FLOATING EXT
+        12.6.2.1488   FATAN       f-a-tan               FLOATING EXT
+        12.6.2.1489   FATAN2      f-a-tan-two           FLOATING EXT
+        12.6.2.1491   FATANH      f-a-tan-h             FLOATING EXT
+        12.6.1.1492   FCONSTANT   f-constant            FLOATING
+        12.6.2.1493   FCOS        f-cos                 FLOATING EXT
+        12.6.2.1494   FCOSH       f-cosh                FLOATING EXT
+        12.6.1.1497   FDEPTH      f-depth               FLOATING
+        12.6.1.1500   FDROP       f-drop                FLOATING
+        12.6.1.1510   FDUP        f-dupe                FLOATING
+        12.6.2.1513   FE.         f-e-dot               FLOATING EXT
+        12.6.2.1515   FEXP        f-e-x-p               FLOATING EXT
+        12.6.2.1516   FEXPM1      f-e-x-p-m-one         FLOATING EXT
+        11.6.1.1520   FILE-POSITION                     FILE
+        11.6.1.1522   FILE-SIZE                         FILE
+        11.6.2.1524   FILE-STATUS                       FILE EXT
+          .6.1.1540   FILL                              CORE
+          .6.1.1550   FIND                              CORE
+        16.6.1.1550   FIND                              SEARCH
+        12.6.1.1552   FLITERAL    f-literal             FLOATING
+        12.6.2.1553   FLN         f-l-n                 FLOATING EXT
+        12.6.2.1554   FLNP1       f-l-n-p-one           FLOATING EXT
+        12.6.1.1555   FLOAT+      float-plus            FLOATING
+        12.6.1.1556   FLOATS                            FLOATING
+        12.6.2.1557   FLOG        f-log                 FLOATING EXT
+        12.6.1.1558   FLOOR                             FLOATING
+         7.6.1.1559   FLUSH                             BLOCK
+        11.6.2.1560   FLUSH-FILE                        FILE EXT
+          .6.1.1561   FM/MOD      f-m-slash-mod         CORE
+        12.6.1.1562   FMAX        f-max                 FLOATING
+        12.6.1.1565   FMIN        f-min                 FLOATING
+        12.6.1.1567   FNEGATE     f-negate              FLOATING
+        15.6.2.1580   FORGET                            TOOLS EXT
+        16.6.2.1590   FORTH                             SEARCH EXT
+        16.6.1.1595   FORTH-WORDLIST                    SEARCH
+        12.6.1.1600   FOVER       f-over                FLOATING
+        14.6.1.1605   FREE                              MEMORY
+        12.6.1.1610   FROT        f-rote                FLOATING
+        12.6.1.1612   FROUND      f-round               FLOATING
+        12.6.2.1613   FS.         f-s-dot               FLOATING EXT
+        12.6.2.1614   FSIN        f-sine                FLOATING EXT
+        12.6.2.1616   FSINCOS     f-sine-cos            FLOATING EXT
+        12.6.2.1617   FSINH       f-cinch               FLOATING EXT
+        12.6.2.1618   FSQRT       f-square-root         FLOATING EXT
+        12.6.1.1620   FSWAP       f-swap                FLOATING
+        12.6.2.1625   FTAN        f-tan                 FLOATING EXT
+        12.6.2.1626   FTANH       f-tan-h               FLOATING EXT
+        12.6.1.1630   FVARIABLE   f-variable            FLOATING
+        12.6.2.1640   F~          f-proximate           FLOATING EXT
+        16.6.1.1643   GET-CURRENT                       SEARCH
+        16.6.1.1647   GET-ORDER                         SEARCH
+          .6.1.1650   HERE                              CORE
+          .6.2.1660   HEX                               CORE EXT
+          .6.1.1670   HOLD                              CORE
+          .6.1.1680   I                                 CORE
+          .6.1.1700   IF                                CORE
+          .6.1.1710   IMMEDIATE                         CORE
+        11.6.1.1717   INCLUDE-FILE                      FILE
+        11.6.1.1718   INCLUDED                          FILE
+          .6.1.1720   INVERT                            CORE
+          .6.1.1730   J                                 CORE
+          .6.1.1750   KEY                               CORE
+        10.6.1.1755   KEY?        key-question          FACILITY
+          .6.1.1760   LEAVE                             CORE
+         7.6.2.1770   LIST                              BLOCK EXT
+          .6.1.1780   LITERAL                           CORE
+         7.6.1.1790   LOAD                              BLOCK
+        13.6.2.1795   LOCALS|     locals-bar            LOCAL EXT
+          .6.1.1800   LOOP                              CORE
+          .6.1.1805   LSHIFT      l-shift               CORE
+          .6.1.1810   M*          m-star                CORE
+         8.6.1.1820   M*/         m-star-slash          DOUBLE
+         8.6.1.1830   M+          m-plus                DOUBLE
+          .6.2.1850   MARKER                            CORE EXT
+          .6.1.1870   MAX                               CORE
+          .6.1.1880   MIN                               CORE
+          .6.1.1890   MOD                               CORE
+          .6.1.1900   MOVE                              CORE
+        10.6.2.1905   MS                                FACILITY EXT
+          .6.1.1910   NEGATE                            CORE
+          .6.2.1930   NIP                               CORE EXT
+          .6.2.1950   OF                                CORE EXT
+        16.6.2.1965   ONLY                              SEARCH EXT
+        11.6.1.1970   OPEN-FILE                         FILE
+          .6.1.1980   OR                                CORE
+        16.6.2.1985   ORDER                             SEARCH EXT
+          .6.1.1990   OVER                              CORE
+          .6.2.2000   PAD                               CORE EXT
+        10.6.1.2005   PAGE                              FACILITY
+          .6.2.2008   PARSE                             CORE EXT
+          .6.2.2030   PICK                              CORE EXT
+          .6.1.2033   POSTPONE                          CORE
+        12.6.2.2035   PRECISION                         FLOATING EXT
+        16.6.2.2037   PREVIOUS                          SEARCH EXT
+          .6.2.2040   QUERY                             CORE EXT
+          .6.1.2050   QUIT                              CORE
+        11.6.1.2054   R/O         r-o                   FILE
+        11.6.1.2056   R/W         r-w                   FILE
+          .6.1.2060   R>          r-from                CORE
+          .6.1.2070   R@          r-fetch               CORE
+        11.6.1.2080   READ-FILE                         FILE
+        11.6.1.2090   READ-LINE                         FILE
+          .6.1.2120   RECURSE                           CORE
+          .6.2.2125   REFILL                            CORE EXT
+         7.6.2.2125   REFILL                            BLOCK EXT
+        11.6.2.2125   REFILL                            FILE EXT
+        11.6.2.2130   RENAME-FILE                       FILE EXT
+          .6.1.2140   REPEAT                            CORE
+        11.6.1.2142   REPOSITION-FILE                   FILE
+        12.6.1.2143   REPRESENT                         FLOATING
+        14.6.1.2145   RESIZE                            MEMORY
+        11.6.1.2147   RESIZE-FILE                       FILE
+          .6.2.2148   RESTORE-INPUT                     CORE EXT
+          .6.2.2150   ROLL                              CORE EXT
+          .6.1.2160   ROT         rote                  CORE
+          .6.1.2162   RSHIFT      r-shift               CORE
+          .6.1.2165   S"          s-quote               CORE
+        11.6.1.2165   S"          s-quote               FILE
+          .6.1.2170   S>D         s-to-d                CORE
+         7.6.1.2180   SAVE-BUFFERS                      BLOCK
+          .6.2.2182   SAVE-INPUT                        CORE EXT
+         7.6.2.2190   SCR         s-c-r                 BLOCK EXT
+        17.6.1.2191   SEARCH                            STRING
+        16.6.1.2192   SEARCH-WORDLIST                   SEARCH
+        15.6.1.2194   SEE                               TOOLS
+        16.6.1.2195   SET-CURRENT                       SEARCH
+        16.6.1.2197   SET-ORDER                         SEARCH
+        12.6.2.2200   SET-PRECISION                     FLOATING EXT
+        12.6.2.2202   SF!         s-f-store             FLOATING EXT
+        12.6.2.2203   SF@         s-f-fetch             FLOATING EXT
+        12.6.2.2204   SFALIGN     s-f-align             FLOATING EXT
+        12.6.2.2206   SFALIGNED   s-f-aligned           FLOATING EXT
+        12.6.2.2207   SFLOAT+     s-float-plus          FLOATING EXT
+        12.6.2.2208   SFLOATS     s-floats              FLOATING EXT
+          .6.1.2210   SIGN                              CORE
+        17.6.1.2212   SLITERAL                          STRING
+          .6.1.2214   SM/REM      s-m-slash-rem         CORE
+          .6.1.2216   SOURCE                            CORE
+          .6.2.2218   SOURCE-ID   source-i-d            CORE EXT
+        11.6.1.2218   SOURCE-ID   source-i-d            FILE
+          .6.1.2220   SPACE                             CORE
+          .6.1.2230   SPACES                            CORE
+          .6.2.2240   SPAN                              CORE EXT
+          .6.1.2250   STATE                             CORE
+        15.6.2.2250   STATE                             TOOLS EXT
+          .6.1.2260   SWAP                              CORE
+          .6.1.2270   THEN                              CORE
+         9.6.1.2275   THROW                             EXCEPTION
+         7.6.2.2280   THRU                              BLOCK EXT
+          .6.2.2290   TIB         t-i-b                 CORE EXT
+        10.6.2.2292   TIME&DATE   time-and-date         FACILITY EXT
+          .6.2.2295   TO                                CORE EXT
+        13.6.1.2295   TO                                LOCAL
+          .6.2.2298   TRUE                              CORE EXT
+          .6.2.2300   TUCK                              CORE EXT
+          .6.1.2310   TYPE                              CORE
+          .6.1.2320   U.          u-dot                 CORE
+          .6.2.2330   U.R         u-dot-r               CORE EXT
+          .6.1.2340   U<          u-less-than           CORE
+          .6.2.2350   U>          u-greater-than        CORE EXT
+          .6.1.2360   UM*         u-m-star              CORE
+          .6.1.2370   UM/MOD      u-m-slash-mod         CORE
+          .6.1.2380   UNLOOP                            CORE
+          .6.1.2390   UNTIL                             CORE
+          .6.2.2395   UNUSED                            CORE EXT
+         7.6.1.2400   UPDATE                            BLOCK
+          .6.2.2405   VALUE                             CORE EXT
+          .6.1.2410   VARIABLE                          CORE
+        11.6.1.2425   W/O         w-o                   FILE
+          .6.1.2430   WHILE                             CORE
+          .6.2.2440   WITHIN                            CORE EXT
+          .6.1.2450   WORD                              CORE
+        16.6.1.2460   WORDLIST                          SEARCH
+        15.6.1.2465   WORDS                             TOOLS
+        11.6.1.2480   WRITE-FILE                        FILE
+        11.6.1.2485   WRITE-LINE                        FILE
+          .6.1.2490   XOR         x-or                  CORE
+          .6.1.2500   [           left-bracket          CORE
+          .6.1.2510   [']         bracket-tick          CORE
+          .6.1.2520   [CHAR]      bracket-char          CORE
+          .6.2.2530   [COMPILE]   bracket-compile       CORE EXT
+        15.6.2.2531   [ELSE]      bracket-else          TOOLS EXT
+        15.6.2.2532   [IF]        bracket-if            TOOLS EXT
+        15.6.2.2533   [THEN]      bracket-then          TOOLS EXT
+          .6.2.2535   \           backslash             CORE EXT
+         7.6.2.2535   \           backslash             BLOCK EXT
+          .6.1.2540   ]           right-bracket         CORE
+
+

+ +Available from the American National Standards Institute, 11 West 42nd +Street, Newyork, NY 10036 +

+ +Other common implementation techniques include direct translation to code +and other types of tokens. +

+ +These terms are not defined in the Standard. They are mentioned here for +historical continuity. +Collating Sequence: + + +

+! " # $ % & ' ( ) * + , - . / digits : ; < = > ? @ ALPHA [ \ ] ^ _ ` alpha { |
+} ~
+
+ + + +
+ Table of Contents +

+ +