ANS required documentation
Provided word sets
To the best of knowledge FLK is an
ANS Forth System
- providing the Core Extensions word set
- providing the Double-Number word set
- providing the Double-Number Extensions word set
- providing the Exception word set
- providing the Exception Extensions word set
- providing the Facility word set
- providing the Facility Extensions word set
- providing the File Access word set
- providing the File Access Extensions word set
- providing the Floating-Point word set
- providing the Floating-Point Extensions word set
- providing the Memory-Allocation word set
- providing the Memory-Allocation Extensions
- providing the Programming-Tools word set
- providing the Programming-Tools Extensions word set
- providing the Search-Order word set
- providing the Search-Order Extensions word set
- providing the String word set
- providing the String Extensions word set
Implementation defined values
- aligned address requirements (3.1.3.3 Addresses): Since
FLK is tailored to the Intel 386+ CPU's running Linux, neither the cell
aligned addresses nor the character aligned addresses have to be aligned. It
is recommended for speed to align cells to addresses that are multiples of
four.
- behavior of 6.1.1320
EMIT
for non-graphic
characters: EMIT passes its argument directly to the terminal, so its
behavior is dependend upon the behavior of the terminal and the used character
set.
- character editing of 6.1.0695
ACCEPT
and 6.2.1390
EXPECT
: If the used terminal supports them the keys
cursor left, cursor right, back space, delete
character, cursor home, cursor end, return,
set tabulator, cursor up and cursor down are
accepted.
- character set (3.1.2 Character types, 6.1.1320
EMIT
,
6.1.1750 KEY
): The character set used by
EMIT
is terminal depended. The characters returned by
KEY
are limitied to the range of decimal 32...127 inclusive.
- character-aligned address requirements (3.1.3.3
Addresses): No restriction. Any address is character aligned.
- character-set-extensions matching characteristics (3.4.2 Finding
definition names): Word names are copied to the dictionary as found
(case sensitive behaviour) although find names can be case sensitive or
insensitive.
- conditions under which control characters match a space delimiter
(3.4.1.1 Delimiters):
PARSE
and all other words that
parse accept characters below or equal to 32 as delimiters.
- format of the control-flow stack (3.2.3.2 Control-flow
stack): The control flow stack is implemented using the data stack.
- conversion of digits larger than thirty-five (3.2.1.2 Digit
conversion): A number may contain upper of lower case letters. If
they exceed the range of digits, the conversion is ended without error. If
the number is converted by the interpreter, the whole word is considered
unknown.
- display after input terminates in 6.1.0695
ACCEPT
and
6.2.1390 EXPECT
: The cursor is placed to the right of
the last character.
- exception abort sequence (as in 6.1.0680
ABORT"
): Address and length of the string is transfered
to special variables and the exception -2 is raised.
- input line terminator (3.2.4.1 User input device): The
character '\n' as defined by the C compiler. Its numerical value is 10
decimal.
- maximum size of a counted string, in characters (3.1.3.4 Counted
strings, 6.1.2450 WORD): 255
- maximum size of a parsed string (3.4.1 Parsing): 255
- maximum size of a definition name, in characters (3.3.1.2
Definition names): 255
- maximum string length for 6.1.1345 ENVIRONMENT?, in
characters: unlimited
- method of selecting 3.2.4.1 User input device: The user
input device is the standard input of the program.
- method of selecting 3.2.4.2 User output device: The user
output device is the standard output of the program.
- methods of dictionary compilation (3.3 The Forth
dictionary): The name space is distributed over the code space since
the headers are in code space and the names are part of the header. It is
possible to access the code space by
@
etc. An execution token is
the address of the first byte of a header.
- number of bits in one address unit (3.1.3.3 Addresses): 8
- number representation and arithmetic (3.2.1.1 Internal number
representation): little endian, two's complement
- ranges for n, +n, u, d, +d, and ud (3.1.3 Single-cell types, 3.1.4
Cell-pair types): The following ranges are inclusive the given
borders:
n | -2147483648 | 2147483647 |
+n | 0 | 2147483647 |
u | 0 | 4294967295 |
d | -9223372036854775808 | 9223372036854775807 |
+d | 0 | 9223372036854775807 |
ud | 0 | 18446744073709551615 |
- read-only data-space regions (3.3.3 Data space): The
whole data space is writable although is not recommended to bomb around at
will.
- size of buffer at 6.1.2450
WORD
(3.3.3.6 Other
transient regions): 256 characters, defined by the meta compiler
constant #WORD-PAD
- size of one cell in address units (3.1.3 Single-cell
types): 4
- size of one character in address units (3.1.2 Character
types): 1
- size of the keyboard terminal input buffer (3.3.3.5 Input
buffers): 256 character, defined by the meta compiler constant
#TIB
- size of the pictured numeric output string buffer (3.3.3.6 Other
transient regions): 80 characters, defined by the meta compiler
constant
((pnolen))
- size of the scratch area whose address is returned by 6.2.2000
PAD
(3.3.3.6 Other transient regions): 256 characters,
defined by the meta compiler constant #PAD-LEN
- system case-sensitivity characteristics (3.4.2 Finding definition
names): FLK's case sensitivity is controlled by the variable
CAPS
. If it contains TRUE
FLK is case insensitive,
otherwise it is case sensitive.
- system prompt (3.4 The Forth text interpreter, 6.1.2050
QUIT):
CR ." OK " CR
in interpretation state and
CR ." ? "
in compilation state.
- 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:
TRUE
- values returned after arithmetic overflow (3.2.2.2 Other integer
operations): wrap-around, (n modulo 2^32, d modulo 2^64)
- whether the current definition can be found after 6.1.1250
DOES>
(6.1.0450 :): The current definition can not be
found after DOES>
Ambiguos conditions
- a name is neither a valid definition name nor a valid number
during text interpretation (3.4 The Forth text interpreter): Display
the unknown word and raise exception -13.
- a definition name exceeded the maximum length allowed (3.3.1.2
Definition names): The name is truncated to 255 characters
- addressing a region not listed in 3.3.3 Data Space: As
long as the address is a valid address in terms of the operating system
nothing happens. Otherwise a segmentation fault is raised and handled by the
operating system.
- argument type incompatible with specified input parameter, e.g.,
passing a flag to a word expecting an n (3.1 Data types): The
parameter is interpreted as if it was of the right type.
- attempting to obtain the execution token, (e.g., with 6.1.0070
'
, 6.1.1550 FIND
, etc.) of a definition with
undefined interpretation semantics: The execution tokens of all known
words can be obtained.
- 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*/
): The operating
system raises a Floating exception.
- insufficient data-stack space or return-stack space (stack
overflow): Ignored, might cause a segmentation fault.
- insufficient space for loop-control parameters: Ignored,
might cause a segmentation fault.
- insufficient space in the dictionary: Exception -8 is
raised.
- interpretating a word with undefined interpretation
semantics: Exception -14 is raised.
- modifying the contents of the input buffer or a string literal
(3.3.3.4 Text-literal regions, 3.3.3.5 Input buffers): Ignored.
- overflow of a pictured numeric output string: Exception
-17 is raised.
- parsed string overflow: The parsed string is truncated.
- 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*/
): Wrap around. n modulo 2^32
- reading from an empty data stack or return stack (stack
underflow): Ignored, might cause a segmentation fault.
- unexpected end of input buffer, resulting in an attempt to use a
zero-length string as a name: Exception -16 is raised.
- >IN greater than size of input buffer (3.4.1 Parsing):
Parsing is aborted, an empty string is returned.
- 6.1.2120 RECURSE appears after 6.1.1250 DOES>: A call
to the word beeing defined is compiled.
- argument input source different than current input source for
6.2.2148
RESTORE-INPUT
: The described input source is
restored without a notification sent to the program.
- data space containing definitions is de-allocated (3.3.3.2
Contiguous regions): If you are lucky, some words disappear. If not
the system crashed at the next
FIND
or SEARCH-WORDLIST
.
- data space read/write with incorrect alignment (3.3.3.1 Address
alignment): Ignored.
- data-space pointer not properly aligned (6.1.0150
,
, 6.1.0860
C,
): Ignored.
- less than u+2 stack items (6.2.2030
PICK
, 6.2.2150
ROLL
): The system crashes with a segmentation fault.
- 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
): The values found on the return stack are
interpreted as loop control parameters. The loop might stop, perform another
run or the system crashes with a segmentation fault.
- most recent definition does not have a name (6.1.1710
IMMEDIATE): The immediate flag is set in the header anyway. Nothing
else happens.
- name not defined by 6.2.2405
VALUE
used by 6.2.2295
TO
: As long as name is created by CREATE
the
value is stored. You are responsible that there was room for one cell. If
name is not CREATEd or a VALUE, exception -31 is raised.
- name not found (6.1.0070
'
, 6.1.2033
POSTPONE
, 6.1.2510 [']
, 6.2.2530
[COMPILE]
): Exception -13 is raised.
- parameters are not of the same type (6.1.1240
DO
,
6.2.0620 ?DO
, 6.2.2440 WITHIN
): The
parameters are interpreted as if they were of the same type.
- 6.1.2033
POSTPONE
or 6.2.2530 [COMPILE]
applied to 6.2.2295 TO: The equivalent of ['] TO COMPILE,
is performed.
- string longer than a counted string returned by 6.1.2450
WORD
: The string is handled as if is was shorter than a
byte counted string. That's what the address,length notation is for, isn't it?
- u greater than or equal to the number of bits in a cell (6.1.1805
LSHIFT
, 6.1.2162 RSHIFT
): Only the least
significant bits of u are used, equivalent to e.g.31 AND LSHIFT
.
- word not defined via 6.1.1000
CREATE
(6.1.0550
>BODY
, 6.1.1250 DOES>
): Exception -31
is raised.
- 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
): As long as the pictured numeric output buffer
does not overflow it is ignored. Otherwise exception -17 is raised.
Other system documentation
- list of non-standard words using 6.2.2000
PAD
(3.3.3.6 Other transient regions): none
- operator's terminal facilities available: Whether the
terminal supports attributes and any other terminal facilities depend upon the
terminal itself.
- program data space available, in address units:
Adjustable, current number reported upon startup.
- return stack space available, in cells: 10000, defined by
the meta compiler constant
CALL-STACK-SIZE
- stack space available, in cells: 10000, defined by the
meta compiler constant
DATA-STACK-SIZE
- system dictionary space required, in address units:
Execute
CHERE IMAGE-BASE - .
to learn the current value of
allocated code space. Execute HERE IMAGE-BASE - HA-CODESIZE @ - .
for the number of bytes in code space. Execute HA-CODESIZE @ HA-DATASIZE
@ + .
for the total dictionary size in bytes.