SourceForge Logo

SPF ANS support

SPF ANS support

System documentation as required by ANS standard section 4.

Last update: $Date: 2008/01/04 12:42:24 $


Contents


General notes

Maximum ANS conformity is achieved by including lib/include/ansi.f. Additional words are defined, some of them dummies, etc.

Also, a non-standard optimization of FILE wordset is fixed - OPEN-FILE, CREATE-FILE and other implicitly treat the input string as zero-ended (ignoring the length parameter). lib/include/ansi-file.f will add an extra zero byte in such case, after copying the file name to the dynamic buffer, which remains allocated for future use. You don't really need such behaviour when defining file names with string literal S" or string libraries ~ac/lib/str*.f, as they ensure there is an extra zero byte. Though it can be helpful for using non-SPF libraries.


Implementation-defined options

  • aligned address requirements (3.1.3.3 Addresses);

    No requirements. You can access data at any address. Though CREATE aligns code to even adresses for more speed.

  • behavior of 6.1.1320 EMIT for non-graphic characters;

    TYPE and EMIT fully depend on the OS API for handling special chracters, on Windows this results in performing special assigned actions such as Line Feed, Carriage Return, Beep etc

  • character editing of 6.1.0695 ACCEPT and 6.2.1390 EXPECT;

    EXPECT is not available (obsolete). ACCEPT fully depends on the capabilities of the shell. On Windows by default it provides command history and convenient one line editing with arrows, Ins, Del, Bksp etc

  • character set (3.1.2 Character types, 6.1.1320 EMIT, 6.1.1750 KEY);

    ?

  • character-aligned address requirements (3.1.3.3 Addresses);

    No requirements are imposed. Character aligned data can start at any address.

  • character-set-extensions matching characteristics (3.4.2 Finding definition names);

    The definition name matches the search string when and only when the corresponding characters in both strings are equal. As a consequence, SPF is case-sensitive.

  • conditions under which control characters match a space delimiter (3.4.1.1 Delimiters);

    Parser treats all characters with ascii code less or equal to 32 (BL) as delimiters. This behaviour doesn't depend on the input source.

  • format of the control-flow stack (3.2.3.2 Control-flow stack);

    Control flow stack is available and implemented using the data stack. Separate control flow stack implementation is available as an extension ~mak/lib/a_if.f.

  • conversion of digits larger than thirty-five (3.2.1.2 Digit conversion);

    SPF converts digits according to the ASCII character table, so 50 BASE ! a 0[ DECIMAL . . will produce 36 42.

  • display after input terminates in 6.1.0695 ACCEPT and 6.2.1390 EXPECT;

    Depends on the shell, by default the input is echoed while typing and remains on the screen at the same position when input is finished, with additional carriage return.

  • exception abort sequence (as in 6.1.0680 ABORT");

    ?

  • input line terminator (3.2.4.1 User input device);

    Input line is terminated with the sequence of two characters CRLF (ASCII codes hex 0D 0A). UNIX-LINES switches to LF (ASCII hex 0x0A), DOS-LINES restores default behavior. Current input line terminator is EOLN ( -- a u ).

  • maximum size of a counted string, in characters (3.1.3.4 Counted strings, 6.1.2450 WORD);

    255 characters

  • maximum size of a parsed string (3.4.1 Parsing);

    255 characters ?

  • maximum size of a definition name, in characters (3.3.1.2 Definition names);

    255 characters ?

  • maximum string length for 6.1.1345 ENVIRONMENT?, in characters;

    not limited by implementation of ENVIRONMENT?

  • method of selecting 3.2.4.1 User input device;

    User input is taken from file handle H-STDIN. By default it is a standard input stream, i.e. console.

  • method of selecting 3.2.4.2 User output device;

    TYPE outputs to the file which handle is H-STDOUT. By default it goes to standard output i.e. console window.

  • methods of dictionary compilation (3.3 The Forth dictionary);

  • number of bits in one address unit (3.1.3.3 Addresses);

    8 bits in one address unit.

  • 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);

    -2147483648 <= n <= 2147483647
    0 <= +n <= 2147483647
    0 <= u <= 4294967295
    -2^63 <= d <= 2^63 - 1
    0 <= +d <= 2^63 - 1
    0 <= ud <= 2^64 - 1

  • 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);

    255 bytes.

  • size of one cell in address units (3.1.3 Single-cell types);

    4 address units

  • size of one character in address units (3.1.2 Character types);

    1 address unit

  • size of the keyboard terminal input buffer (3.3.3.5 Input buffers);

    1024 bytes

  • size of the pictured numeric output string buffer (3.3.3.6 Other transient regions);

    4096 bytes

  • size of the scratch area whose address is returned by 6.2.2000 PAD (3.3.3.6 Other transient regions);

    1024 bytes

  • system case-sensitivity characteristics (3.4.2 Finding definition names);

    SPF kernel is case sensitive. Extension lib/ext/caseins.f replaces SEARCH-WORDLIST to perform case-insensitive search.

  • system prompt (3.4 The Forth text interpreter, 6.1.2050 QUIT);

    None

  • 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;

    TRUE i.e. -1

  • 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 :).

  • Values used in the system by 9.6.1.0875 CATCH and 9.6.1.2275 THROW (9.3.1 THROW values, 9.3.5 Possible actions on an ambiguous condition).

  • encoding of keyboard events (10.6.2.1305 EKEY);

    byte    value
    0       AsciiChar
    2       ScanCod
    3       KeyDownFlag
    
  • duration of a system clock tick;

    ?

  • repeatability to be expected from execution of 10.6.2.1905 MS.

    not implemented

  • file access methods used by 11.6.1.0765 BIN, 11.6.1.1010 CREATE-FILE, 11.6.1.1970 OPEN-FILE, 11.6.1.2054 R/O, 11.6.1.2056 R/W, and 11.6.1.2425 W/O;

  • file exceptions;

  • file line terminator (11.6.1.2090 READ-LINE);

    See input line terminator explanation.

  • file name format (11.3.1.4 File names);

    File paths can contain forward and backslashes as directory separators.

  • information returned by 11.6.2.1524 FILE-STATUS;

    Not implemented.

  • input file state after an exception (11.6.1.1717 INCLUDE-FILE, 11.6.1.1718 INCLUDED);

  • ior values and meaning (11.3.1.2 I/O results);

    ior values can be THROWn directly.

  • maximum depth of file input nesting (11.3.4 Input source);

    SPF allows at most 64 INCLUDED nestings.

  • maximum size of input line (11.3.6 Parsing);

  • methods for mapping block ranges to files (11.3.2 Blocks in files);

    Not implemented.

  • number of string buffers provided (11.6.1.2165 S");

    1

  • size of string buffer used by 11.6.1.2165 S".

    The same as for the input line.

  • 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);

    6

  • width of floating-point stack (12.3.3 Floating-point stack).

    10 bytes. Float values can be represented in memory as 4, 8 and 10 byte values.

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

    Not limited by implementation of locals lib/ext/locals.f

  • values and meaning of ior (14.3.1 I/O Results data type, 14.6.1.0707 ALLOCATE, 14.6.1.1605 FREE, 14.6.1.2145 RESIZE).

  • ending sequence for input following 15.6.2.0470 ;CODE and 15.6.2.0930 CODE;

  • manner of processing input following 15.6.2.0470 ;CODE and 15.6.2.0930 CODE;

  • search-order capability for 15.6.2.1300 EDITOR and 15.6.2.0740 ASSEMBLER (15.3.3 The Forth dictionary);

  • source and format of display by 15.6.1.2194 SEE.

    SEE is implemented as a disassembler in the lib/ext/disasm.f extension.

  • maximum number of word lists in the search order (16.3.3 Finding definition names, 16.6.1.2197 SET-ORDER);

    16

  • minimum search order (16.6.1.2197 SET-ORDER, 16.6.2.1965 ONLY).

    FORTH-WORDLIST


Ambiguous conditions

  • a name is neither a valid definition name nor a valid number during text interpretation (3.4 The Forth text interpreter);

    Context vocabulary is searched for the NOTFOUND word. If it is present - it is executed with the name in question as a parameter. More details in intro. If the word is not processed by NOTFOUND or NOTFOUND itself is missing - exception -2003 is thrown. By default exception is caught by main handler and system QUITs.

  • a definition name exceeded the maximum length allowed (3.3.1.2 Definition names);

    exception

  • 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);

    No types verification available. Everything on the data stack is a cell.

  • attempting to obtain the execution token, (e.g., with 6.1.0070 ', 6.1.1550 FIND, etc.) of a definition with undefined interpretation semantics;

    Returns execution token which will fail when executed

  • 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*/);

    Exception 0xC0000094

  • insufficient data-stack space or return-stack space (stack overflow);

    Data stack and return stack share the same space (data stack grows up from the start, return stack grows down from the end), so stack overflow results in overwriting another stack, leading to strange behavior or system exception. Extension ~ss/ext/stack-guard.f tries to detect stack overflow and throw the appropriate exception.

  • insufficient space for loop-control parameters;

    ?

  • insufficient space in the dictionary;

    Ordinary dictionary size is limited by the size of data space. On overflow AV exception occurs (0xC0000005). Data space size can be increased by N bytes before SAVEing new system with

    HERE IMAGE-BASE - N + TO IMAGE-SIZE
    

    This will take effect only after SAVEing and launching saved system.

    It is possible to reallocate data space in live system (?)

  • interpretating a word with undefined interpretation semantics;

    Usually it will raise exception -312 (Compilation mode only), but can be an undefined behaviour

  • modifying the contents of the input buffer or a string literal (3.3.3.4 Text-literal regions, 3.3.3.5 Input buffers);

    no problems as long as you don't exceed the buffer space

  • overflow of a pictured numeric output string;

    AV

  • parsed string overflow;

    AV

  • 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*/);

    silent truncation modulo maximum value size (2^32, 2^64)

  • reading from an empty data stack or return stack (stack underflow);

    data stack underflow results in exception -4, underflowing return stack will either do nothing or silently take down the system

  • unexpected end of input buffer, resulting in an attempt to use a zero-length string as a name;

  • >IN greater than size of input buffer (3.4.1 Parsing);

  • 6.1.2120 RECURSE appears after 6.1.1250 DOES>;

  • argument input source different than current input source for 6.2.2148 RESTORE-INPUT;

  • data space containing definitions is de-allocated (3.3.3.2 Contiguous regions);

  • data space read/write with incorrect alignment (3.3.3.1 Address alignment);

    Ok

  • data-space pointer not properly aligned (6.1.0150 ,, 6.1.0860 C,);

    Ok

  • less than u+2 stack items (6.2.2030 PICK, 6.2.2150 ROLL);

    Silently returns some random number

  • 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);

  • most recent definition does not have a name (6.1.1710 IMMEDIATE);

    AV

  • name not defined by 6.2.2405 VALUE used by 6.2.2295 TO;

    AV

  • name not found (6.1.0070 ', 6.1.2033 POSTPONE, 6.1.2510 ['], 6.2.2530 [COMPILE]);

    exception -321 (Not found)

  • parameters are not of the same type (6.1.1240 DO, 6.2.0620 ?DO, 6.2.2440 WITHIN);

    not verified, all types are treated the same

  • 6.1.2033 POSTPONE or 6.2.2530 [COMPILE] applied to 6.2.2295 TO;

    ?

  • string longer than a counted string returned by 6.1.2450 WORD;

    ?

  • u greater than or equal to the number of bits in a cell (6.1.1805 LSHIFT, 6.1.2162 RSHIFT);

    the number of bits is taken modulo 32

  • word not defined via 6.1.1000 CREATE (6.1.0550 >BODY, 6.1.1250 DOES>);

    undefined behaviour

  • 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).

    UB

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

    not available in core SPF. Extension-implementation-defined

  • attempting to position a file outside its boundaries (11.6.1.2142 REPOSITION-FILE);

    Ok

  • attempting to read from file positions not yet written (11.6.1.2080 READ-FILE, 11.6.1.2090 READ-LINE);

    Ok (nothing is read)

  • fileid is invalid (11.6.1.1717 INCLUDE-FILE);

    exception (invalid handle)

  • I/O exception reading or closing fileid (11.6.1.1717 INCLUDE-FILE, 11.6.1.1718 INCLUDED);

  • named file cannot be opened (11.6.1.1718 INCLUDED);

    exception 2 (file not found)

  • requesting an unmapped block number (11.3.2 Blocks in files);

    not implemented

  • using 11.6.1.2218 SOURCE-ID when 7.6.1.0790 BLK is not zero.

    ?

  • DF@ or DF! is used with an address that is not double-float aligned;

    Ok

  • F@ or F! is used with an address that is not float aligned;

    Ok

  • SF@ or SF! is used with an address that is not single-float aligned;

    Ok

  • floating point result out of range (e.g., in 12.6.1.1430 F/);

  • BASE is not decimal (12.6.1.2143 REPRESENT, 12.6.2.1427 F., 12.6.2.1513 FE., 12.6.2.1613 FS.);

    prints number in hexadecimal

  • both arguments equal zero (12.6.2.1489 FATAN2);

    result is zero

  • cosine of argument is zero for 12.6.2.1625 FTAN;

  • d can't be precisely represented as float in 12.6.1.1130 D>F;

  • dividing by zero (12.6.1.1430 F/);

    lib/include/float2.f has two modes of operation - SILENT-MODE and ERROR-MODE. In the first case - the result of dividing by zero is infinity, in latter case - subsequent floating operation will raise an exception.

  • exponent too big for conversion (12.6.2.1203 DF!, 12.6.2.1204 DF@, 12.6.2.2202 SF!, 12.6.2.2203 SF@);

  • float less than one (12.6.2.1477 FACOSH);

  • float less than or equal to minus-one (12.6.2.1554 FLNP1);

  • float less than or equal to zero (12.6.2.1553 FLN, 12.6.2.1557 FLOG);

  • float less than zero (12.6.2.1487 FASINH, 12.6.2.1618 FSQRT);

  • float magnitude greater than one (12.6.2.1476 FACOS, 12.6.2.1486 FASIN, 12.6.2.1491 FATANH);

  • integer part of float can't be represented by d in 12.6.1.1470 F>D;

  • string larger than pictured-numeric output area (12.6.2.1427 F., 12.6.2.1513 FE., 12.6.2.1613 FS.).

  • 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).

    Mainly this will result in run-time error. TO executes the xt from the defined offset in the body of the word, if this code is invalid (which is the case, when the word was created not as VALUE) Access Violation occurs.

  • deleting the compilation word-list (15.6.2.1580 FORGET);

    FORGET not implemented

  • fewer than u+1 items on control-flow stack (15.6.2.1015 CSPICK, 15.6.2.1020 CSROLL);

  • name can't be found (15.6.2.1580 FORGET);

    FORGET not implemented

  • name not defined via 6.1.1000 CREATE (15.6.2.0470 ;CODE);

  • 6.1.2033 POSTPONE applied to 15.6.2.2532 [IF];

  • reaching the end of the input source before matching 15.6.2.2531 [ELSE] or 15.6.2.2533 [THEN] (15.6.2.2532 [IF]);

  • removing a needed definition (15.6.2.1580 FORGET).

    FORGET not implemented

  • 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).

    AV


Other system documentation

  • 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.