ficl standards compliance

From f4e75c6395310fa4b119d3eaa9a4a9f8913df200 Mon Sep 17 00:00:00 2001 From: "Pedro F. Giffuni" Date: Tue, 12 May 2015 03:27:06 +0000 Subject: Update to ficl 4.1.0 (latest release on sourceforge) --- doc/dpans.html | 1037 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1037 insertions(+) create mode 100644 doc/dpans.html (limited to 'doc/dpans.html') diff --git a/doc/dpans.html b/doc/dpans.html new file mode 100644 index 000000000000..d6bc87acb8e3 --- /dev/null +++ b/doc/dpans.html @@ -0,0 +1,1037 @@ + + + + + + +ficl standards compliance + + + + + + + + + + + + + + + +

+ + + +ficl standards compliance + +

+Index

+ANS
+API
+Debugger
+Download
+Licensing
+Links
+Locals
+OOP In Ficl
+Parse Steps
+Release History
+Upgrading To 4.0
+

+ + +
+

+ + +

+ + +ANS Required Information +

+ + + + +The following documentation is necessary to comply for Ficl +to comply with the DPANS94 standard. It describes what areas +of the standard Ficl implements, what areas it does not, and +how it behaves in areas undefined by the standard. + +
+ + +
+
+ + +
+ + +ANS Forth System +
+ + + + + +Providing names from the Core Extensions word set +
+ +Providing names from the Double-Number word set +
+ +Providing the Exception word set +
+ +Providing the Exception Extensions word set +
+ +Providing the File-Access word set +
+ +Providing the File-Access Extensions word set +
+ +Providing names from the Floating-Point word set +
+ +Providing the Locals word set +
+ +Providing the Locals Extensions word set +
+ +Providing the Memory Allocation word set +
+ +Providing the Programming-Tools word set +
+ +Providing names from the Programming-Tools Extensions word set +
+ +Providing the Search-Order word set +
+ +Providing the Search-Order Extensions word set +
+ +Providing names from the String Extensions word set +
+ + + + + + + + +
+
+ + +
+ + +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 the Standard are met. A system shall +document the values for, or behaviors of, each item. + +
+ +
+aligned address requirements (3.1.3.3 Addresses) +
+ + + +System dependent. You can change the default address alignment by +defining FICL_ALIGN on your compiler's command line, +or in platform.h. +The default value is set to 2 in ficl.h. +This causes dictionary entries and ALIGN and +ALIGNED to align on 4 byte +boundaries. To align on 2ⁿ byte boundaries, +set FICL_ALIGN to n. + + +
+behavior of 6.1.1320 EMIT for non-graphic characters +
+ + + +Depends on target system, C runtime library, and your +implementation of ficlTextOut(). + + +
+character editing of 6.1.0695 ACCEPT and 6.2.1390 EXPECT +
+ + + +None implemented in the versions supplied in primitives.c. +Because ficlEvaluate() is supplied a text buffer +externally, it's up to your system to define how that buffer will +be obtained. + + +
+character set (3.1.2 Character types, 6.1.1320 EMIT, 6.1.1750 KEY) +
+ + + +Depends on target system and implementation of ficlTextOut(). + + +
+character-aligned address requirements (3.1.3.3 Addresses) +
+ + + +Ficl characters are one byte each. There are no alignment requirements. + + +
+character-set-extensions matching characteristics (3.4.2 Finding definition names) +
+ + + +No special processing is performed on characters beyond case-folding. Therefore, +extended characters will not match their unaccented counterparts. + + +
+conditions under which control characters match a space delimiter (3.4.1.1 Delimiters) +
+ + + +Ficl uses the Standard C function isspace() to distinguish space characters. + + +
+format of the control-flow stack (3.2.3.2 Control-flow stack) +
+ + + +Uses the data stack. + + +
+conversion of digits larger than thirty-five (3.2.1.2 Digit conversion) +
+ + + +The maximum supported value of BASE is 36. +Ficl will fail via assertion in function ltoa() of utility.c +if the base is found to be larger than 36 or smaller than 2. There will be no effect +if NDEBUG is defined, however, other than possibly unexpected behavior. + + +
+display after input terminates in 6.1.0695 ACCEPT and 6.2.1390 EXPECT +
+ + + +Target system dependent. + + +
+exception abort sequence (as in 6.1.0680 ABORT") +
+ + + +Calls ABORT to exit. + + +
+input line terminator (3.2.4.1 User input device) +
+ + + +Target system dependent (implementation of outer loop that calls ficlEvaluate()). + + +
+maximum size of a counted string, in characters (3.1.3.4 Counted strings, 6.1.2450 WORD) +
+ + + +Counted strings are limited to 255 characters. + + +
+maximum size of a parsed string (3.4.1 Parsing) +
+ + + +Limited by available memory and the maximum unsigned value that can fit in a cell (2³²-1). + + +
+maximum size of a definition name, in characters (3.3.1.2 Definition names) +
+ + + +Ficl stores the first 31 characters of a definition name. + + +
+maximum string length for 6.1.1345 ENVIRONMENT?, in characters +
+ + + +Same as maximum definition name length. + + +
+method of selecting 3.2.4.1 User input device +
+ + + +None supported. This is up to the target system. + + +
+method of selecting 3.2.4.2 User output device +
+ + + +None supported. This is up to the target system. + + +
+methods of dictionary compilation (3.3 The Forth dictionary) +
+ + + +Okay, we don't know what this means. If you understand what they're asking for here, +please call the home office. + + +
+number of bits in one address unit (3.1.3.3 Addresses) +
+ + + +Target system dependent, either 32 or 64 bits. + + +
+number representation and arithmetic (3.2.1.1 Internal number representation) +
+ + + +System dependent. Ficl represents a CELL internally as a union that can hold a ficlInteger32 +(a signed 32 bit scalar value), a ficlUnsigned32 (32 bits unsigned), +and an untyped pointer. No specific byte ordering is assumed. + + +
+ranges for n, +n, u, d, +d, and ud (3.1.3 Single-cell types, 3.1.4 Cell-pair types) +
+ + + +System dependent. +Assuming a 32 bit implementation, range for signed single-cell values is [-2³¹, 2³¹-1]. +Range for unsigned single cell values is [0, 2³²-1]. +Range for signed double-cell values is [-2⁶³, 2⁶³-1]. +Range for unsigned double cell values is [0, 2⁶⁴-1]. + + +
+read-only data-space regions (3.3.3 Data space) +
+ + + +None. + + +
+size of buffer at 6.1.2450 WORD (3.3.3.6 Other transient regions) +
+ + + +Default is 255. Depends on the setting of FICL_PAD_SIZE in ficl.h. + + +
+size of one cell in address units (3.1.3 Single-cell types) +
+ + + +System dependent, generally 4. + + +
+size of one character in address units (3.1.2 Character types) +
+ + + +System dependent, generally 1. + + +
+size of the keyboard terminal input buffer (3.3.3.5 Input buffers) +
+ + + +This buffer is supplied by the host program. Ficl imposes no practical limit. + + +
+size of the pictured numeric output string buffer (3.3.3.6 Other transient regions) +
+ + + +Default is 255. Depends on the setting of FICL_PAD_SIZE in ficl.h. + + +
+size of the scratch area whose address is returned by 6.2.2000 PAD (3.3.3.6 Other transient regions) +
+ + + +Default is 255. Depends on the setting of FICL_PAD_SIZE in ficl.h. + + +
+system case-sensitivity characteristics (3.4.2 Finding definition names) +
+ + + +The Ficl dictionary is not case-sensitive. + + +
+system prompt (3.4 The Forth text interpreter, 6.1.2050 QUIT) +
+ + + +ok> + + +
+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) +
+ + + +Symmetric. + + +
+values of 6.1.2250 STATE when true +
+ + + +1. + + +
+values returned after arithmetic overflow (3.2.2.2 Other integer operations) +
+ + + +System dependent. Ficl makes no special checks for overflow. + + +
+whether the current definition can be found after 6.1.1250 DOES> (6.1.0450 :) +
+ + +No. Definitions are unsmudged after ; only, and only then if no control structure matching problems have been detected. + +
+ + + +
+
+ + +
+ + +Ambiguous Conditions +
+ + + +
+ +
+a name is neither a valid definition name nor a valid number during text interpretation (3.4 The Forth text interpreter) +
+ + + +Ficl calls ABORT then prints the name followed by not found. + + +
+a definition name exceeded the maximum length allowed (3.3.1.2 Definition names) +
+ + + +Ficl stores the first 31 characters of the definition name, and uses all characters of the name +in computing its hash code. The actual length of the name, up to 255 characters, is stored in +the definition's length field. + + +
+addressing a region not listed in 3.3.3 Data Space +
+ + + +No problem: all addresses in Ficl are absolute. You can reach any 32 bit address in Ficl's address space. + + +
+argument type incompatible with specified input parameter, e.g., passing a flag to a word expecting an n (3.1 Data types) +
+ + + +Ficl makes no check for argument type compatibility. Effects of a mismatch vary widely depending on the specific problem and operands. + + +
+attempting to obtain the execution token, (e.g., with 6.1.0070 ', 6.1.1550 FIND, etc.) of a definition with undefined interpretation semantics +
+ + + +Ficl returns a valid token, but the result of executing that token while interpreting may be undesirable. + + +
+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*/) +
+ + + +Results are target procesor dependent. Generally, Ficl makes no check for divide-by-zero. The target processor will probably throw an exception. + + +
+insufficient data-stack space or return-stack space (stack overflow) +
+ + + +With FICL_ROBUST (defined in ficl.h) set to a value of 2 or greater, +most data, float, and return stack operations are checked for underflow and overflow. + + +
+insufficient space for loop-control parameters +
+ + + +This is not checked, and bad things will happen. + + +
+insufficient space in the dictionary +
+ + + +Ficl generates an error message if the dictionary is too full to create +a definition header. It checks ALLOT as well, but it is possible +to make an unchecked allocation request that will overflow the dictionary. + + +
+interpreting a word with undefined interpretation semantics +
+ + + +Ficl protects all ANS Forth words with undefined interpretation semantics from being executed while in interpret state. +It is possible to defeat this protection using ' (tick) and EXECUTE though. + + +
+modifying the contents of the input buffer or a string literal (3.3.3.4 Text-literal regions, 3.3.3.5 Input buffers) +
+ + + +Varies depending on the nature of the buffer. The input buffer is supplied by ficl's host function, and may reside +in read-only memory. If so, writing the input buffer can ganerate an exception. +String literals are stored in the dictionary, and are writable. + + +
+overflow of a pictured numeric output string +
+ + + +In the unlikely event you are able to construct a pictured numeric string of more +than FICL_PAD_LENGTH characters, the system will be corrupted unpredictably. +The buffer area that holds pictured numeric output is at the end of the virtual machine. +Whatever is mapped after the offending VM in memory will be trashed, along with the heap +structures that contain it. + + +
+parsed string overflow +
+ + + +Ficl does not copy parsed strings unless asked to. Ordinarily, a string parsed from the input buffer during +normal interpretation is left in-place, so there is no possibility of overflow. +If you ask to parse a string into the dictionary, as in SLITERAL, you need to have enough +room for the string, otherwise bad things may happen. This is usually not a problem. + + +
+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*/) +
+ + + +Value will be truncated. + + +
+reading from an empty data stack or return stack (stack underflow) +
+ + + +Most stack underflows are detected and prevented if FICL_ROBUST (defined in sysdep.h) is set to 2 or greater. +Otherwise, the stack pointer and size are likely to be trashed. + + +
+unexpected end of input buffer, resulting in an attempt to use a zero-length string as a name +
+ + + +Ficl returns for a new input buffer until a non-empty one is supplied. + + +
+ + +The following specific ambiguous conditions are noted in the glossary entries of the relevant words: + +
+ +
+>IN greater than size of input buffer (3.4.1 Parsing) +
+ + + +Memory corruption will occur—the exact behavior is unpredictable +because the input buffer is supplied by the host program's outer loop. + + +
+6.1.2120 RECURSE appears after 6.1.1250 DOES> +
+ + + +It finds the address of the definition before DOES> + + +
+argument input source different than current input source for 6.2.2148 RESTORE-INPUT +
+ + + +Not implemented. + + +
+data space containing definitions is de-allocated (3.3.3.2 Contiguous regions) +
+ + + +This is okay until the cells are overwritten with something else. +The dictionary maintains a hash table, and the table must be updated +in order to de-allocate words without corruption. + + +
+data space read/write with incorrect alignment (3.3.3.1 Address alignment) +
+ + + +Target processor dependent. Consequences include: none (Intel), address error exception (68K). + + +
+data-space pointer not properly aligned (6.1.0150 ,, 6.1.0860 C,) +
+ + + +See above on data space read/write alignment. + +
+less than u+2 stack items (6.2.2030 PICK, 6.2.2150 ROLL) +
+ + + +If FICL_ROBUST is two or larger, Ficl will detect a stack underflow, report it, and execute ABORT to +exit execution. Otherwise the error will not be detected, and memory corruption will occur. + + +
+loop-control parameters not available ( 6.1.0140 +LOOP, 6.1.1680 I, 6.1.1730 J, 6.1.1760 LEAVE, 6.1.1800 LOOP, 6.1.2380 UNLOOP) +
+ + + +Loop initiation words are responsible for checking the stack and guaranteeing that the control parameters are pushed. +Any underflows will be detected early if FICL_ROBUST is set to 2 or greater. +Note however that Ficl only checks for return stack underflows at the end of each line of text. + +
+most recent definition does not have a name (6.1.1710 IMMEDIATE) +
+ + + +No problem. + + +
+name not defined by 6.2.2405 VALUE used by 6.2.2295 TO +
+ + + +Ficl's version of TO works correctly with words defined with: +
+ +
VALUE +
2VALUE +
FVALUE +
F2VALUE +
CONSTANT +
FCONSTANT +
2CONSTANT +
F2CONSTANT +
VARIABLE +
2VARIABLE +
+as well as with all "local" variables. + +
+name not found (6.1.0070 ', 6.1.2033 POSTPONE, 6.1.2510 ['], 6.2.2530 [COMPILE]) +
+ + + +Ficl prints an error message and executes ABORT + +
+parameters are not of the same type (6.1.1240 DO, 6.2.0620 ?DO, 6.2.2440 WITHIN) +
+ + + +Not detected. Results vary depending on the specific problem. + + +
+6.1.2033 POSTPONE or 6.2.2530 [COMPILE] applied to 6.2.2295 TO +
+ + + +The word is postponed correctly. + + +
+string longer than a counted string returned by 6.1.2450 WORD +
+ + + +Ficl stores the first FICL_COUNTED_STRING_MAX - 1 characters in the +destination buffer. +(The extra character is the trailing space required by the standard. Yuck.) + +
+u greater than or equal to the number of bits in a cell (6.1.1805 LSHIFT, 6.1.2162 RSHIFT) +
+ + + +Depends on target process or and C runtime library implementations of the << and >> operators +on unsigned values. For I386, the processor appears to shift modulo the number of bits in a cell. + +
+word not defined via 6.1.1000 CREATE (6.1.0550 >BODY, 6.1.1250 DOES>) +
+ + + +
+words improperly used outside 6.1.0490 <# and 6.1.0040 #> (6.1.0030 #, 6.1.0050 #S, 6.1.1670 HOLD, 6.1.2210 SIGN) +
+ + + +Undefined. CREATE reserves a field in words it builds for DOES> to fill in. +If you use DOES> on a word not made by CREATE it will overwrite the first +cell of its parameter area. That's probably not what you want. Likewise, pictured numeric words +assume that there is a string under construction in the VM's scratch buffer. If that's not the case, +results may be unpleasant. + + +
+ + +
+
+ + +
+ + +Locals Implementation-Defined Options +
+ + + +
+ +
+maximum number of locals in a definition (13.3.3 Processing locals, 13.6.2.1795 LOCALS|) +
+ + + +Default is 64—unused locals are cheap. Change by redefining FICL_MAX_LOCALS (defined in ficl.h). + +
+ + + +
+
+ + +
+ + +Locals Ambiguous conditions +
+ + + +
+ +
+executing a named local while in interpretation state (13.6.1.0086 (LOCAL)) +
+ + + +Locals can be found in interpretation state while in the context of a definition under +construction. Under these circumstances, locals behave correctly. Locals are not visible +at all outside the scope of a definition. + +
+name not defined by VALUE or LOCAL (13.6.1.2295 TO) +
+ + + +See the CORE ambiguous conditions, above (no change). + +
+ + + +
+
+ + +
+ + +Programming Tools Implementation-Defined Options +
+ + + + +
+ +
+source and format of display by 15.6.1.2194 SEE +
+ + + +SEE de-compiles definitions from the dictionary. Ficl words are stored as a combination +of things: +
+ +
bytecodes (identified as "instructions"), +
addresses of native Ficl functions, and +
arguments to both of the above. + +
+Colon definitions are decompiled. Branching instructions indicate their destination, +but target labels are not reconstructed. +Literals and string literals are so noted, and their contents displayed. + +
+ + + +
+
+ + +
+ + +Search Order Implementation-Defined Options +
+ + + + +
+ +
+maximum number of word lists in the search order (16.3.3 Finding definition names, 16.6.1.2197 SET-ORDER) +
+ + + +Defaults to 16. Can be changed by redefining FICL_MAX_WORDLISTS (declared in ficl.h). + + +
+minimum search order (16.6.1.2197 SET-ORDER, 16.6.2.1965 ONLY) +
+ + + +Equivalent to FORTH-WORDLIST 1 SET-ORDER + +
+ + + + +
+
+ + +
+ + +Search Order Ambiguous Conditions +
+ + + + +
+
+changing the compilation word list (16.3.3 Finding definition names) +
+ + + +Ficl stores a link to the current definition independently of the compile wordlist while +it is being defined, and links it into the compile wordlist only after the definition completes +successfully. Changing the compile wordlist mid-definition will cause the definition to link +into the new compile wordlist. + + +
+search order empty (16.6.2.2037 PREVIOUS) +
+ + + +Ficl prints an error message if the search order underflows, and resets the order to its default state. + + +
+too many word lists in search order (16.6.2.0715 ALSO) +
+ + + +Ficl prints an error message if the search order overflows, and resets the order to its default state. + +
+ + + +

+ + -- cgit v1.3