--- gforth/Attic/gforth.ds 1995/02/22 18:40:15 1.11 +++ gforth/Attic/gforth.ds 1995/06/03 14:24:42 1.16 @@ -286,7 +286,7 @@ that has become a de-facto standard for @table @var @item word The name of the word. BTW, GNU Forth is case insensitive, so you can -type the words in in lower case. +type the words in in lower case (However, @pxref{core-idef}). @item Stack effect The stack effect is written in the notation @code{@var{before} -- @@ -409,6 +409,11 @@ doc-sm/rem @node Double precision, Floating Point, Mixed precision, Arithmetic @subsection Double precision + +The outer (aka text) interpreter converts numbers containing a dot into +a double precision number. Note that only numbers with the dot as last +character are standard-conforming. + doc-d+ doc-d- doc-dnegate @@ -419,6 +424,19 @@ doc-dmax @node Floating Point, , Double precision, Arithmetic @subsection Floating Point +The format of floating point numbers recognized by the outer (aka text) +interpreter is: a signed decimal number, possibly containing a decimal +point (@code{.}), followed by @code{E} or @code{e}, optionally followed +by a signed integer (the exponent). E.g., @code{1e} ist the same as +@code{+1.0e+1}. Note that a number without @code{e} +is not interpreted as floating-point number, but as double (if the +number contains a @code{.}) or single precision integer. Also, +conversions between string and floating point numbers always use base +10, irrespective of the value of @code{BASE}. If @code{BASE} contains a +value greater then 14, the @code{E} may be interpreted as digit and the +number will be interpreted as integer, unless it has a signed exponent +(both @code{+} and @code{-} are allowed as signs). + Angles in floating point operations are given in radians (a full circle has 2 pi radians). Note, that gforth has a separate floating point stack, but we use the unified notation. @@ -1050,7 +1068,7 @@ poses the following questions: @menu * Where are locals visible by name?:: -* How long do locals live? :: +* How long do locals live?:: * Programming Style:: * Implementation:: @end menu @@ -1320,8 +1338,8 @@ efficiency reasons, e.g., @code{@@local0 compile the right specialized version, or the general version, as appropriate: -doc-compile-@@local -doc-compile-f@@local +doc-compile-@local +doc-compile-f@local doc-compile-lp+! Combinations of conditional branches and @code{lp+!#} like @@ -1487,6 +1505,10 @@ locals wordset. @node Defining Words, Wordlists, Locals, Words @section Defining Words +@menu +* Values:: +@end menu + @node Values, , Defining Words, Defining Words @subsection Values @@ -1619,9 +1641,1030 @@ doc-does-code! doc-does-handler! doc-/does-handler + + @node ANS conformance, Model, Words, Top @chapter ANS conformance +To the best of our knowledge, gforth is an + +ANS Forth System +@itemize +@item providing the Core Extensions word set +@item providing the Block word set +@item providing the Block Extensions word set +@item providing the Double-Number word set +@item providing the Double-Number Extensions word set +@item providing the Exception word set +@item providing the Exception Extensions word set +@item providing the Facility word set +@item providing @code{MS} and @code{TIME&DATE} from the Facility Extensions word set +@item providing the File Access word set +@item providing the File Access Extensions word set +@item providing the Floating-Point word set +@item providing the Floating-Point Extensions word set +@item providing the Locals word set +@item providing the Locals Extensions word set +@item providing the Memory-Allocation word set +@item providing the Memory-Allocation Extensions word set (that one's easy) +@item providing the Programming-Tools word set +@item providing @code{AHEAD}, @code{BYE}, @code{CS-PICK}, @code{CS-ROLL}, @code{STATE}, @code{[ELSE]}, @code{[IF]}, @code{[THEN]} from the Programming-Tools Extensions word set +@item providing the Search-Order word set +@item providing the Search-Order Extensions word set +@item providing the String word set +@item providing the String Extensions word set (another easy one) +@end itemize + +In addition, ANS Forth systems are required to document certain +implementation choices. This chapter tries to meet these +requirements. In many cases it gives a way to ask the system for the +information instead of providing the information directly, in +particular, if the information depends on the processor, the operating +system or the installation options chosen, or if they are likely to +change during the maintenance of gforth. + +@comment The framework for the rest has been taken from pfe. + +@menu +* The Core Words:: +* The optional Block word set:: +* The optional Double Number word set:: +* The optional Exception word set:: +* The optional Facility word set:: +* The optional File-Access word set:: +* The optional Floating-Point word set:: +* The optional Locals word set:: +* The optional Memory-Allocation word set:: +* The optional Programming-Tools word set:: +* The optional Search-Order word set:: +@end menu + + +@c ===================================================================== +@node The Core Words, The optional Block word set, ANS conformance, ANS conformance +@comment node-name, next, previous, up +@section The Core Words +@c ===================================================================== + +@menu +* core-idef:: Implementation Defined Options +* core-ambcond:: Ambiguous Conditions +* core-other:: Other System Documentation +@end menu + +@c --------------------------------------------------------------------- +@node core-idef, core-ambcond, The Core Words, The Core Words +@subsection Implementation Defined Options +@c --------------------------------------------------------------------- + +@table @i + +@item (Cell) aligned addresses: +processor-dependent. Gforths alignment words perform natural alignment +(e.g., an address aligned for a datum of size 8 is divisible by +8). Unaligned accesses usually result in a @code{-23 THROW}. + +@item @code{EMIT} and non-graphic characters: +The character is output using the C library function (actually, macro) +@code{putchar}. + +@item character editing of @code{ACCEPT} and @code{EXPECT}: +This is modeled on the GNU readline library (@pxref{Readline +Interaction, , Command Line Editing, readline, The GNU Readline +Library}) with Emacs-like key bindings. @kbd{Tab} deviates a little by +producing a full word completion every time you type it (instead of +producing the common prefix of all completions). + +@item character set: +The character set of your computer and display device. Gforth is +8-bit-clean (but some other component in your system may make trouble). + +@item Character-aligned address requirements: +installation-dependent. Currently a character is represented by a C +@code{unsigned char}; in the future we might switch to @code{wchar_t} +(Comments on that requested). + +@item character-set extensions and matching of names: +Any character except 0 can be used in a name. Matching is +case-insensitive. The matching is performed using the C function +@code{strncasecmp}, whose function is probably influenced by the +locale. E.g., the @code{C} locale does not know about accents and +umlauts, so they are matched case-sensitively in that locale. For +portability reasons it is best to write programs such that they work in +the @code{C} locale. Then one can use libraries written by a Polish +programmer (who might use words containing ISO Latin-2 encoded +characters) and by a French programmer (ISO Latin-1) in the same program +(of course, @code{WORDS} will produce funny results for some of the +words (which ones, depends on the font you are using)). Also, the locale +you prefer may not be available in other operating systems. Hopefully, +Unicode will solve these problems one day. + +@item conditions under which control characters match a space delimiter: +If @code{WORD} is called with the space character as a delimiter, all +white-space characters (as identified by the C macro @code{isspace()}) +are delimiters. @code{PARSE}, on the other hand, treats space like other +delimiters. @code{PARSE-WORD} treats space like @code{WORD}, but behaves +like @code{PARSE} otherwise. @code{(NAME)}, which is used by the outer +interpreter (aka text interpreter) by default, treats all white-space +characters as delimiters. + +@item format of the control flow stack: +The data stack is used as control flow stack. The size of a control flow +stack item in cells is given by the constant @code{cs-item-size}. At the +time of this writing, an item consists of a (pointer to a) locals list +(third), an address in the code (second), and a tag for identifying the +item (TOS). The following tags are used: @code{defstart}, +@code{live-orig}, @code{dead-orig}, @code{dest}, @code{do-dest}, +@code{scopestart}. + +@item conversion of digits > 35 +The characters @code{[\]^_'} are the digits with the decimal value +36@minus{}41. There is no way to input many of the larger digits. + +@item display after input terminates in @code{ACCEPT} and @code{EXPECT}: +The cursor is moved to the end of the entered string. If the input is +terminated using the @kbd{Return} key, a space is typed. + +@item exception abort sequence of @code{ABORT"}: +The error string is stored into the variable @code{"error} and a +@code{-2 throw} is performed. + +@item input line terminator: +For interactive input, @kbd{C-m} and @kbd{C-j} terminate lines. One of +these characters is typically produced when you type the @kbd{Enter} or +@kbd{Return} key. + +@item maximum size of a counted string: +@code{s" /counted-string" environment? drop .}. Currently 255 characters +on all ports, but this may change. + +@item maximum size of a parsed string: +Given by the constant @code{/line}. Currently 255 characters. + +@item maximum size of a definition name, in characters: +31 + +@item maximum string length for @code{ENVIRONMENT?}, in characters: +31 + +@item method of selecting the user input device: +The user input device is the standard input. There is current no way to +change it from within gforth. However, the input can typically be +redirected in the command line that starts gforth. + +@item method of selecting the user output device: +The user output device is the standard output. It cannot be redirected +from within gforth, but typically from the command line that starts +gforth. Gforth uses buffered output, so output on a terminal does not +become visible before the next newline or buffer overflow. Output on +non-terminals is invisible until the buffer overflows. + +@item methods of dictionary compilation: +Waht are we expected to document here? + +@item number of bits in one address unit: +@code{s" address-units-bits" environment? drop .}. 8 in all current +ports. + +@item number representation and arithmetic: +Processor-dependent. Binary two's complement on all current ports. + +@item ranges for integer types: +Installation-dependent. Make environmental queries for @code{MAX-N}, +@code{MAX-U}, @code{MAX-D} and @code{MAX-UD}. The lower bounds for +unsigned (and positive) types is 0. The lower bound for signed types on +two's complement and one's complement machines machines can be computed +by adding 1 to the upper bound. + +@item read-only data space regions: +The whole Forth data space is writable. + +@item size of buffer at @code{WORD}: +@code{PAD HERE - .}. 104 characters on 32-bit machines. The buffer is +shared with the pictured numeric output string. If overwriting +@code{PAD} is acceptable, it is as large as the remaining dictionary +space, although only as much can be sensibly used as fits in a counted +string. + +@item size of one cell in address units: +@code{1 cells .}. + +@item size of one character in address units: +@code{1 chars .}. 1 on all current ports. + +@item size of the keyboard terminal buffer: +Varies. You can determine the size at a specific time using @code{lp@ +tib - .}. It is shared with the locals stack and TIBs of files that +include the current file. You can change the amount of space for TIBs +and locals stack at gforth startup with the command line option +@code{-l}. + +@item size of the pictured numeric output buffer: +@code{PAD HERE - .}. 104 characters on 32-bit machines. The buffer is +shared with @code{WORD}. + +@item size of the scratch area returned by @code{PAD}: +The remainder of dictionary space. You can even use the unused part of +the data stack space. The current size can be computed with @code{sp@ +pad - .}. + +@item system case-sensitivity characteristics: +Dictionary searches are case insensitive. However, as explained above +under @i{character-set extensions}, the matching for non-ASCII +characters is determined by the locale you are using. In the default +@code{C} locale all non-ASCII characters are matched case-sensitively. + +@item system prompt: +@code{ ok} in interpret state, @code{ compiled} in compile state. + +@item division rounding: +installation dependent. @code{s" floored" environment? drop .}. We leave +the choice to gcc (what to use for @code{/}) and to you (whether to use +@code{fm/mod}, @code{sm/rem} or simply @code{/}). + +@item values of @code{STATE} when true: +-1. + +@item values returned after arithmetic overflow: +On two's complement machines, arithmetic is performed modulo +2**bits-per-cell for single arithmetic and 4**bits-per-cell for double +arithmetic (with appropriate mapping for signed types). Division by zero +typically results in a @code{-55 throw} (floatingpoint unidentified +fault), although a @code{-10 throw} (divide by zero) would be more +appropriate. + +@item whether the current definition can be found after @t{DOES>}: +No. + +@end table + +@c --------------------------------------------------------------------- +@node core-ambcond, core-other, core-idef, The Core Words +@subsection Ambiguous conditions +@c --------------------------------------------------------------------- + +@table @i + +@item a name is neither a word nor a number: +@code{-13 throw} (Undefined word) + +@item a definition name exceeds the maximum length allowed: +@code{-19 throw} (Word name too long) + +@item addressing a region not inside the various data spaces of the forth system: +The stacks, code space and name space are accessible. Machine code space is +typically readable. Accessing other addresses gives results dependent on +the operating system. On decent systems: @code{-9 throw} (Invalid memory +address). + +@item argument type incompatible with parameter: +This is usually not caught. Some words perform checks, e.g., the control +flow words, and issue a @code{ABORT"} or @code{-12 THROW} (Argument type +mismatch). + +@item attempting to obtain the execution token of a word with undefined execution semantics: +You get an execution token representing the compilation semantics +instead. + +@item dividing by zero: +typically results in a @code{-55 throw} (floating point unidentified +fault), although a @code{-10 throw} (divide by zero) would be more +appropriate. + +@item insufficient data stack or return stack space: +Not checked. This typically results in mysterious illegal memory +accesses, producing @code{-9 throw} (Invalid memory address) or +@code{-23 throw} (Address alignment exception). + +@item insufficient space for loop control parameters: +like other return stack overflows. + +@item insufficient space in the dictionary: +Not checked. Similar results as stack overflows. However, typically the +error appears at a different place when one inserts or removes code. + +@item interpreting a word with undefined interpretation semantics: +For some words, we defined interpretation semantics. For the others: +@code{-14 throw} (Interpreting a compile-only word). Note that this is +checked only by the outer (aka text) interpreter; if the word is +@code{execute}d in some other way, it will typically perform it's +compilation semantics even in interpret state. (We could change @code{'} +and relatives not to give the xt of such words, but we think that would +be too restrictive). + +@item modifying the contents of the input buffer or a string literal: +These are located in writable memory and can be modified. + +@item overflow of the pictured numeric output string: +Not checked. + +@item parsed string overflow: +@code{PARSE} cannot overflow. @code{WORD} does not check for overflow. + +@item producing a result out of range: +On two's complement machines, arithmetic is performed modulo +2**bits-per-cell for single arithmetic and 4**bits-per-cell for double +arithmetic (with appropriate mapping for signed types). Division by zero +typically results in a @code{-55 throw} (floatingpoint unidentified +fault), although a @code{-10 throw} (divide by zero) would be more +appropriate. @code{convert} and @code{>number} currently overflow +silently. + +@item reading from an empty data or return stack: +The data stack is checked by the outer (aka text) interpreter after +every word executed. If it has underflowed, a @code{-4 throw} (Stack +underflow) is performed. Apart from that, the stacks are not checked and +underflows can result in similar behaviour as overflows (of adjacent +stacks). + +@item unexepected end of the input buffer, resulting in an attempt to use a zero-length string as a name: +@code{Create} and its descendants perform a @code{-16 throw} (Attempt to +use zero-length string as a name). Words like @code{'} probably will not +find what they search. Note that it is possible to create zero-length +names with @code{nextname} (should it not?). + +@item @code{>IN} greater than input buffer: +The next invocation of a parsing word returns a string wih length 0. + +@item @code{RECURSE} appears after @code{DOES>}: +Compiles a recursive call to the defining word not to the defined word. + +@item argument input source different than current input source for @code{RESTORE-INPUT}: +!!???If the argument input source is a valid input source then it gets +restored. Otherwise causes @code{-12 THROW} which unless caught issues +the message "argument type mismatch" and aborts. + +@item data space containing definitions gets de-allocated: +Deallocation with @code{allot} is not checked. This typically resuls in +memory access faults or execution of illegal instructions. + +@item data space read/write with incorrect alignment: +Processor-dependent. Typically results in a @code{-23 throw} (Address +alignment exception). Under Linux on a 486 or later processor with +alignment turned on, incorrect alignment results in a @code{-9 throw} +(Invalid memory address). There are reportedly some processors with +alignment restrictions that do not report them. + +@item data space pointer not properly aligned, @code{,}, @code{C,}: +Like other alignment errors. + +@item less than u+2 stack items (@code{PICK} and @code{ROLL}): +Not checked. May cause an illegal memory access. + +@item loop control parameters not available: +Not checked. The counted loop words simply assume that the top of return +stack items are loop control parameters and behave accordingly. + +@item most recent definition does not have a name (@code{IMMEDIATE}): +@code{abort" last word was headerless"}. + +@item name not defined by @code{VALUE} used by @code{TO}: +@code{-32 throw} (Invalid name argument) + +@item name not found (@code{'}, @code{POSTPONE}, @code{[']}, @code{[COMPILE]}): +@code{-13 throw} (Undefined word) + +@item parameters are not of the same type (@code{DO}, @code{?DO}, @code{WITHIN}): +Gforth behaves as if they were of the same type. I.e., you can predict +the behaviour by interpreting all parameters as, e.g., signed. + +@item @code{POSTPONE} or @code{[COMPILE]} applied to @code{TO}: +Assume @code{: X POSTPONE TO ; IMMEDIATE}. @code{X} is equivalent to +@code{TO}. + +@item String longer than a counted string returned by @code{WORD}: +Not checked. The string will be ok, but the count will, of course, +contain only the least significant bits of the length. + +@item u greater than or equal to the number of bits in a cell (@code{LSHIFT}, @code{RSHIFT}): +Processor-dependent. Typical behaviours are returning 0 and using only +the low bits of the shift count. + +@item word not defined via @code{CREATE}: +@code{>BODY} produces the PFA of the word no matter how it was defined. + +@code{DOES>} changes the execution semantics of the last defined word no +matter how it was defined. E.g., @code{CONSTANT DOES>} is equivalent to +@code{CREATE , DOES>}. + +@item words improperly used outside @code{<#} and @code{#>}: +Not checked. As usual, you can expect memory faults. + +@end table + + +@c --------------------------------------------------------------------- +@node core-other, , core-ambcond, The Core Words +@subsection Other system documentation +@c --------------------------------------------------------------------- + +@table @i + +@item nonstandard words using @code{PAD}: +None. + +@item operator's terminal facilities available: +!!?? + +@item program data space available: +@code{sp@ here - .} gives the space remaining for dictionary and data +stack together. + +@item return stack space available: +!!?? + +@item stack space available: +@code{sp@ here - .} gives the space remaining for dictionary and data +stack together. + +@item system dictionary space required, in address units: +Type @code{here forthstart - .} after startup. At the time of this +writing, this gives 70108 (bytes) on a 32-bit system. +@end table + + +@c ===================================================================== +@node The optional Block word set, The optional Double Number word set, The Core Words, ANS conformance +@section The optional Block word set +@c ===================================================================== + +@menu +* block-idef:: Implementation Defined Options +* block-ambcond:: Ambiguous Conditions +* block-other:: Other System Documentation +@end menu + + +@c --------------------------------------------------------------------- +@node block-idef, block-ambcond, The optional Block word set, The optional Block word set +@subsection Implementation Defined Options +@c --------------------------------------------------------------------- + +@table @i + +@item the format for display by @code{LIST}: +First the screen number is displayed, then 16 lines of 64 characters, +each line preceded by the line number. + +@item the length of a line affected by @code{\}: +64 characters. +@end table + + +@c --------------------------------------------------------------------- +@node block-ambcond, block-other, block-idef, The optional Block word set +@subsection Ambiguous conditions +@c --------------------------------------------------------------------- + +@table @i + +@item correct block read was not possible: +Typically results in a @code{throw} of some OS-derived value (between +-512 and -2048). If the blocks file was just not long enough, blanks are +supplied for the missing portion. + +@item I/O exception in block transfer: +Typically results in a @code{throw} of some OS-derived value (between +-512 and -2048). + +@item invalid block number: +@code{-35 throw} (Invalid block number) + +@item a program directly alters the contents of @code{BLK}: +The input stream is switched to that other block, at the same +position. If the storing to @code{BLK} happens when interpreting +non-block input, the system will get quite confused when the block ends. + +@item no current block buffer for @code{UPDATE}: +@code{UPDATE} has no effect. + +@end table + + +@c --------------------------------------------------------------------- +@node block-other, , block-ambcond, The optional Block word set +@subsection Other system documentation +@c --------------------------------------------------------------------- + +@table @i + +@item any restrictions a multiprogramming system places on the use of buffer addresses: +No restrictions (yet). + +@item the number of blocks available for source and data: +depends on your disk space. + +@end table + + +@c ===================================================================== +@node The optional Double Number word set, The optional Exception word set, The optional Block word set, ANS conformance +@section The optional Double Number word set +@c ===================================================================== + +@menu +* double-ambcond:: Ambiguous Conditions +@end menu + + +@c --------------------------------------------------------------------- +@node double-ambcond, , The optional Double Number word set, The optional Double Number word set +@subsection Ambiguous conditions +@c --------------------------------------------------------------------- + +@table @i + +@item @var{d} outside of range of @var{n} in @code{D>S}: +The least significant cell of @var{d} is produced. + +@end table + + +@c ===================================================================== +@node The optional Exception word set, The optional Facility word set, The optional Double Number word set, ANS conformance +@section The optional Exception word set +@c ===================================================================== + +@menu +* exception-idef:: Implementation Defined Options +@end menu + + +@c --------------------------------------------------------------------- +@node exception-idef, , The optional Exception word set, The optional Exception word set +@subsection Implementation Defined Options +@c --------------------------------------------------------------------- + +@table @i +@item @code{THROW}-codes used in the system: +The codes -256@minus{}-511 are used for reporting signals (see +@file{errore.fs}). The codes -512@minus{}-2047 are used for OS errors +(for file and memory allocation operations). The mapping from OS error +numbers to throw code is -512@minus{}@var{errno}. One side effect of +this mapping is that undefined OS errors produce a message with a +strange number; e.g., @code{-1000 THROW} results in @code{Unknown error +488} on my system. +@end table + +@c ===================================================================== +@node The optional Facility word set, The optional File-Access word set, The optional Exception word set, ANS conformance +@section The optional Facility word set +@c ===================================================================== + +@menu +* facility-idef:: Implementation Defined Options +* facility-ambcond:: Ambiguous Conditions +@end menu + + +@c --------------------------------------------------------------------- +@node facility-idef, facility-ambcond, The optional Facility word set, The optional Facility word set +@subsection Implementation Defined Options +@c --------------------------------------------------------------------- + +@table @i + +@item encoding of keyboard events (@code{EKEY}): +Not yet implemeted. + +@item duration of a system clock tick +System dependent. With respect to @code{MS}, the time is specified in +microseconds. How well the OS and the hardware implement this, is +another question. + +@item repeatability to be expected from the execution of @code{MS}: +System dependent. On Unix, a lot depends on load. If the system is +lightly loaded, and the delay is short enough that gforth does not get +swapped out, the performance should be acceptable. Under MS-DOS and +other single-tasking systems, it should be good. + +@end table + + +@c --------------------------------------------------------------------- +@node facility-ambcond, , facility-idef, The optional Facility word set +@subsection Ambiguous conditions +@c --------------------------------------------------------------------- + +@table @i + +@item @code{AT-XY} can't be performed on user output device: +Largely terminal dependant. No range checks are done on the arguments. +No errors are reported. You may see some garbage appearing, you may see +simply nothing happen. + +@end table + + +@c ===================================================================== +@node The optional File-Access word set, The optional Floating-Point word set, The optional Facility word set, ANS conformance +@section The optional File-Access word set +@c ===================================================================== + +@menu +* file-idef:: Implementation Defined Options +* file-ambcond:: Ambiguous Conditions +@end menu + + +@c --------------------------------------------------------------------- +@node file-idef, file-ambcond, The optional File-Access word set, The optional File-Access word set +@subsection Implementation Defined Options +@c --------------------------------------------------------------------- + +@table @i + +@item File access methods used: +@code{R/O}, @code{R/W} and @code{BIN} work as you would +expect. @code{W/O} translates into the C file opening mode @code{w} (or +@code{wb}): The file is cleared, if it exists, and created, if it does +not (both with @code{open-file} and @code{create-file}). Under Unix +@code{create-file} creates a file with 666 permissions modified by your +umask. + +@item file exceptions: +The file words do not raise exceptions (except, perhaps, memory access +faults when you pass illegal addresses or file-ids). + +@item file line terminator: +System-dependent. Gforth uses C's newline character as line +terminator. What the actual character code(s) of this are is +system-dependent. + +@item file name format +System dependent. Gforth just uses the file name format of your OS. + +@item information returned by @code{FILE-STATUS}: +@code{FILE-STATUS} returns the most powerful file access mode allowed +for the file: Either @code{R/O}, @code{W/O} or @code{R/W}. If the file +cannot be accessed, @code{R/O BIN} is returned. @code{BIN} is applicable +along with the retured mode. + +@item input file state after an exception when including source: +All files that are left via the exception are closed. + +@item @var{ior} values and meaning: +The @var{ior}s returned by the file and memory allocation words are +intended as throw codes. They typically are in the range +-512@minus{}-2047 of OS errors. The mapping from OS error numbers to +@var{ior}s is -512@minus{}@var{errno}. + +@item maximum depth of file input nesting: +limited by the amount of return stack, locals/TIB stack, and the number +of open files available. This should not give you troubles. + +@item maximum size of input line: +@code{/line}. Currently 255. + +@item methods of mapping block ranges to files: +Currently, the block words automatically access the file +@file{blocks.fb} in the currend working directory. More sophisticated +methods could be implemented if there is demand (and a volunteer). + +@item number of string buffers provided by @code{S"}: +1 + +@item size of string buffer used by @code{S"}: +@code{/line}. currently 255. + +@end table + +@c --------------------------------------------------------------------- +@node file-ambcond, , file-idef, The optional File-Access word set +@subsection Ambiguous conditions +@c --------------------------------------------------------------------- + +@table @i + +@item attempting to position a file outside it's boundaries: +@code{REPOSITION-FILE} is performed as usual: Afterwards, +@code{FILE-POSITION} returns the value given to @code{REPOSITION-FILE}. + +@item attempting to read from file positions not yet written: +End-of-file, i.e., zero characters are read and no error is reported. + +@item @var{file-id} is invalid (@code{INCLUDE-FILE}): +An appropriate exception may be thrown, but a memory fault or other +problem is more probable. + +@item I/O exception reading or closing @var{file-id} (@code{include-file}, @code{included}): +The @var{ior} produced by the operation, that discovered the problem, is +thrown. + +@item named file cannot be opened (@code{included}): +The @var{ior} produced by @code{open-file} is thrown. + +@item requesting an unmapped block number: +There are no unmapped legal block numbers. On some operating systems, +writing a block with a large number may overflow the file system and +have an error message as consequence. + +@item using @code{source-id} when @code{blk} is non-zero: +@code{source-id} performs its function. Typically it will give the id of +the source which loaded the block. (Better ideas?) + +@end table + + +@c ===================================================================== +@node The optional Floating-Point word set, The optional Locals word set, The optional File-Access word set, ANS conformance +@section The optional Floating-Point word set +@c ===================================================================== + +@menu +* floating-idef:: Implementation Defined Options +* floating-ambcond:: Ambiguous Conditions +@end menu + + +@c --------------------------------------------------------------------- +@node floating-idef, floating-ambcond, The optional Floating-Point word set, The optional Floating-Point word set +@subsection Implementation Defined Options +@c --------------------------------------------------------------------- + +@table @i + +@item format and range of floating point numbers: +System-dependent; the @code{double} type of C. + +@item results of @code{REPRESENT} when @var{float} is out of range: +System dependent; @code{REPRESENT} is implemented using the C library +function @code{ecvt()} and inherits its behaviour in this respect. + +@item rounding or truncation of floating-point numbers: +What's the question?!! + +@item size of floating-point stack: +@code{s" FLOATING-STACK" environment? drop .}. Can be changed at startup +with the command-line option @code{-f}. + +@item width of floating-point stack: +@code{1 floats}. + +@end table + + +@c --------------------------------------------------------------------- +@node floating-ambcond, , floating-idef, The optional Floating-Point word set +@subsection Ambiguous conditions +@c --------------------------------------------------------------------- + +@table @i + +@item @code{df@@} or @code{df!} used with an address that is not double-float aligned: +System-dependent. Typically results in an alignment fault like other +alignment violations. + +@item @code{f@@} or @code{f!} used with an address that is not float aligned: +System-dependent. Typically results in an alignment fault like other +alignment violations. + +@item Floating-point result out of range: +System-dependent. Can result in a @code{-55 THROW} (Floating-point +unidentified fault), or can produce a special value representing, e.g., +Infinity. + +@item @code{sf@@} or @code{sf!} used with an address that is not single-float aligned: +System-dependent. Typically results in an alignment fault like other +alignment violations. + +@item BASE is not decimal (@code{REPRESENT}, @code{F.}, @code{FE.}, @code{FS.}): +The floating-point number is converted into decimal nonetheless. + +@item Both arguments are equal to zero (@code{FATAN2}): +System-dependent. @code{FATAN2} is implemented using the C library +function @code{atan2()}. + +@item Using ftan on an argument @var{r1} where cos(@var{r1}) is zero: +System-dependent. Anyway, typically the cos of @var{r1} will not be zero +because of small errors and the tan will be a very large (or very small) +but finite number. + +@item @var{d} cannot be presented precisely as a float in @code{D>F}: +The result is rounded to the nearest float. + +@item dividing by zero: +@code{-55 throw} (Floating-point unidentified fault) + +@item exponent too big for conversion (@code{DF!}, @code{DF@@}, @code{SF!}, @code{SF@@}): +System dependent. On IEEE-FP based systems the number is converted into +an infinity. + +@item @var{float}<1 (@code{facosh}): +@code{-55 throw} (Floating-point unidentified fault) + +@item @var{float}=<-1 (@code{flnp1}): +@code{-55 throw} (Floating-point unidentified fault). On IEEE-FP systems +negative infinity is typically produced for @var{float}=-1. + +@item @var{float}=<0 (@code{fln}, @code{flog}): +@code{-55 throw} (Floating-point unidentified fault). On IEEE-FP systems +negative infinity is typically produced for @var{float}=0. + +@item @var{float}<0 (@code{fasinh}, @code{fsqrt}): +@code{-55 throw} (Floating-point unidentified fault). @code{fasinh} +produces values for these inputs on my Linux box (Bug in the C library?) + +@item |@var{float}|>1 (@code{facos}, @code{fasin}, @code{fatanh}): +@code{-55 throw} (Floating-point unidentified fault). + +@item integer part of float cannot be represented by @var{d} in @code{f>d}: +@code{-55 throw} (Floating-point unidentified fault). + +@item string larger than pictured numeric output area (@code{f.}, @code{fe.}, @code{fs.}): +This does not happen. +@end table + + + +@c ===================================================================== +@node The optional Locals word set, The optional Memory-Allocation word set, The optional Floating-Point word set, ANS conformance +@section The optional Locals word set +@c ===================================================================== + +@menu +* locals-idef:: Implementation Defined Options +* locals-ambcond:: Ambiguous Conditions +@end menu + + +@c --------------------------------------------------------------------- +@node locals-idef, locals-ambcond, The optional Locals word set, The optional Locals word set +@subsection Implementation Defined Options +@c --------------------------------------------------------------------- + +@table @i + +@item maximum number of locals in a definition: +@code{s" #locals" environment? drop .}. Currently 15. This is a lower +bound, e.g., on a 32-bit machine there can be 41 locals of up to 8 +characters. The number of locals in a definition is bounded by the size +of locals-buffer, which contains the names of the locals. + +@end table + + +@c --------------------------------------------------------------------- +@node locals-ambcond, , locals-idef, The optional Locals word set +@subsection Ambiguous conditions +@c --------------------------------------------------------------------- + +@table @i + +@item executing a named local in interpretation state: +@code{-14 throw} (Interpreting a compile-only word). + +@item @var{name} not defined by @code{VALUE} or @code{(LOCAL)} (@code{TO}): +@code{-32 throw} (Invalid name argument) + +@end table + + +@c ===================================================================== +@node The optional Memory-Allocation word set, The optional Programming-Tools word set, The optional Locals word set, ANS conformance +@section The optional Memory-Allocation word set +@c ===================================================================== + +@menu +* memory-idef:: Implementation Defined Options +@end menu + + +@c --------------------------------------------------------------------- +@node memory-idef, , The optional Memory-Allocation word set, The optional Memory-Allocation word set +@subsection Implementation Defined Options +@c --------------------------------------------------------------------- + +@table @i + +@item values and meaning of @var{ior}: +The @var{ior}s returned by the file and memory allocation words are +intended as throw codes. They typically are in the range +-512@minus{}-2047 of OS errors. The mapping from OS error numbers to +@var{ior}s is -512@minus{}@var{errno}. + +@end table + +@c ===================================================================== +@node The optional Programming-Tools word set, The optional Search-Order word set, The optional Memory-Allocation word set, ANS conformance +@section The optional Programming-Tools word set +@c ===================================================================== + +@menu +* programming-idef:: Implementation Defined Options +* programming-ambcond:: Ambiguous Conditions +@end menu + + +@c --------------------------------------------------------------------- +@node programming-idef, programming-ambcond, The optional Programming-Tools word set, The optional Programming-Tools word set +@subsection Implementation Defined Options +@c --------------------------------------------------------------------- + +@table @i + +@item ending sequence for input following @code{;code} and @code{code}: +Not implemented (yet). + +@item manner of processing input following @code{;code} and @code{code}: +Not implemented (yet). + +@item search order capability for @code{EDITOR} and @code{ASSEMBLER}: +Not implemented (yet). If they were implemented, they would use the +search order wordset. + +@item source and format of display by @code{SEE}: +The source for @code{see} is the intermediate code used by the inner +interpreter. The current @code{see} tries to output Forth source code +as well as possible. + +@end table + +@c --------------------------------------------------------------------- +@node programming-ambcond, , programming-idef, The optional Programming-Tools word set +@subsection Ambiguous conditions +@c --------------------------------------------------------------------- + +@table @i + +@item deleting the compilation wordlist (@code{FORGET}): +Not implemented (yet). + +@item fewer than @var{u}+1 items on the control flow stack (@code{CS-PICK}, @code{CS-ROLL}): +This typically results in an @code{abort"} with a descriptive error +message (may change into a @code{-22 throw} (Control structure mismatch) +in the future). You may also get a memory access error. If you are +unlucky, this ambiguous condition is not caught. + +@item @var{name} can't be found (@code{forget}): +Not implemented (yet). + +@item @var{name} not defined via @code{CREATE}: +@code{;code} is not implemented (yet). If it were, it would behave like +@code{DOES>} in this respect, i.e., change the execution semantics of +the last defined word no matter how it was defined. + +@item @code{POSTPONE} applied to @code{[IF]}: +After defining @code{: X POSTPONE [IF] ; IMMEDIATE}. @code{X} is +equivalent to @code{[IF]}. + +@item reaching the end of the input source before matching @code{[ELSE]} or @code{[THEN]}: +Continue in the same state of conditional compilation in the next outer +input source. Currently there is no warning to the user about this. + +@item removing a needed definition (@code{FORGET}): +Not implemented (yet). + +@end table + + +@c ===================================================================== +@node The optional Search-Order word set, , The optional Programming-Tools word set, ANS conformance +@section The optional Search-Order word set +@c ===================================================================== + +@menu +* search-idef:: Implementation Defined Options +* search-ambcond:: Ambiguous Conditions +@end menu + + +@c --------------------------------------------------------------------- +@node search-idef, search-ambcond, The optional Search-Order word set, The optional Search-Order word set +@subsection Implementation Defined Options +@c --------------------------------------------------------------------- + +@table @i + +@item maximum number of word lists in search order: +@code{s" wordlists" environment? drop .}. Currently 16. + +@item minimum search order: +@code{root root}. + +@end table + +@c --------------------------------------------------------------------- +@node search-ambcond, , search-idef, The optional Search-Order word set +@subsection Ambiguous conditions +@c --------------------------------------------------------------------- + +@table @i + +@item changing the compilation wordlist (during compilation): +The definition is put into the wordlist that is the compilation wordlist +when @code{REVEAL} is executed (by @code{;}, @code{DOES>}, +@code{RECURSIVE}, etc.). + +@item search order empty (@code{previous}): +@code{abort" Vocstack empty"}. + +@item too many word lists in search order (@code{also}): +@code{abort" Vocstack full"}. + +@end table + + @node Model, Emacs and GForth, ANS conformance, Top @chapter Model