Stack diagram notation:
| Data Type | Stack Cells | |
| a | address | 1 |
| n | signed single integer | 1 |
| u | unsigned single integer | 1 |
| d | signed double length integer | 2 |
| ud | unsigned double length integer | 2 |
| t | signed triple length integer | 3 |
| ut | unsigned triple length integer | 3 |
| b | boolean flag: true or false (-1 or 0) | 1 |
| r | double precision floating point value | 2 |
| ^str | counted string address | 1 |
Word names shown in BOLDFACE are not standard in ANS Forth.
FORGET | -- | remove the next word in the input stream and later words from the dictionary |
COLD | -- | remove all non-intrinsic definitions from the dictionary |
WORDS | -- | list the defined words in the current search order |
FORGET may be used to remove words from the
dictionary. TypingFORGET nameCOLD deletes all non-intrinsic definitions and
strings, resets all stacks, and restarts the Forth environment in
interpreter mode.
Words in the dictionary are grouped into word lists. kForth provides
the following built-in word lists:
New definitions are added to the current compilation word list, which
is initially the Forth word list. When the compiler searches the
dictionary for a word name, the search proceeds in a specified order
through a specified series of word lists. This set of ordered word lists is known as
the search order. The Root word list must always be a part of
the search order; however, any other word lists may be added or
removed from the search order. The user may create custom word lists to group
new words added to the dictionary, and control their visibility to the
Forth compiler.
ORDER | -- | display the word lists in the search order. The word list at the |
| beginning of the search order is displayed to the left, | ||
| and the compilation word list is shown in brackets | ||
GET-ORDER | -- awidn ... awid1 n | return the word list address identifiers, and the number of word lists |
| awid1 is the first word list in the search order | ||
SET-ORDER | awidn ... awid1 n -- | set the search order to the specified sequence of word lists, |
| where awid1 is the first word list in the search order | ||
ONLY | -- | remove all word lists from the search order, except the minimal Root word list |
FORTH | -- | replace the first word list in the search order with the Forth word list |
ASSEMBLER | -- | replace the first word list in the search order with the Assembler word list |
GET-CURRENT | -- awid | return the word list address for the current compilation word list |
SET-CURRENT | awid -- | set the compilation word list to be the word list identified by awid |
FORTH-WORDLIST | -- awid | return the word list address identifying the Forth word list |
ALSO | -- | duplicate the word list at the beginning of the search order |
PREVIOUS | -- | remove the first word list in the search order |
DEFINITIONS | -- | set the first word list in the search order as the compilation word list |
WORDLIST | -- awid | create a new empty word list and return its identifier address, awid |
VOCABULARY | -- | create a new named word list which, when executed, will replace the |
| first word list in the search order | ||
SEARCH-WORDLIST | a u awid -- 0 | axt n | search the word list identified by awid for the word name in the string, |
| a u. Return n=0 if the word is not found in the word list, | ||
| n=1 if the word is found and is an immediate word | ||
| n=-1 if the word is found and is not an immediate word | ||
FIND | ^str -- a n | search all the word lists in the search order for |
| the word specified by the counted string; | ||
| n is 0 if not found, | ||
| n is 1 if found and the word is an IMMEDIATE word, | ||
| n is -1 if found and the word is not an immediate word, | ||
| and a is a valid EXECUTE address if the word is found | ||
| [DEFINED] | -- b | parse a word name from the input stream, search for |
| the name in the search order, and return a flag indicating | ||
| whether or not the name was found (-1 if found). | ||
| [UNDEFINED] | -- b | parse a word name from the input stream, search for |
| the name in the search order, and return a flag indicating | ||
| whether or not the name was found (0 if found). |
IMMEDIATE | -- | set the precedence during compilation of the most recently defined word |
NONDEFERRED | -- | set the precedence during interpretation of the most recently defined word |
POSTPONE | -- | append the run-time semantics of the next word to the current definition |
LITERAL | n | a -- | compile a number or address on the stack into the current definition |
2LITERAL | d -- | compile a double number on the stack into the current definition |
SLITERAL | a u -- | compile a string address and count from the stack into the current definition |
FLITERAL | r -- | compile a floating point number on the stack into the current definition |
' | -- a | returns the code field address (cfa) of the next word in the input stream |
['] | -- | immediate version of
' for use inside a word definition |
>BODY | a1 -- a2 | convert the cfa of a word to its parameter field address (pfa) |
COMPILE, | a -- | compile the execution semantics for the cfa of a word into the current definition |
EXECUTE | a -- | execute a word with its cfa given on the stack |
EVALUATE | a u -- | interpret and execute source code contained in a string |
: | -- | create a new word definition and enter the compilation state |
; | -- | |
[ | -- | enter interpretation state |
] | -- | enter compilation state |
STATE | -- b | return true (-1) if compiling; false (0) otherwise |
' (TICK), and ['] may be used to
search the dictionary for a specified word. These words behave
according to the ANS Forth standard, and return an execution address
on the stack. The word EXECUTE may be used
to execute a word given the execution address on the stack. The
word NONDEFERRED is a non-standard word which is used
to set the enhanced precedence state of a word in kForth. For more
information on the concept of precedence in kForth, refer to the
Technical Information section of the user's guide.
The following standard compilation words are provided in Forth source
in
ans-words.4th :
TO | -- | determine the body address of the next word and append the |
| run-time semantics to store a value at that address | ||
: NAME ... ;CREATE name |
VARIABLE name |
n CONSTANT name |
2VARIABLE name |
d 2CONSTANT name |
FVARIABLE name |
f FCONSTANT name |
CREATE can be used inside a word definition to make
your own defining words. The word DOES>,
as part of a CREATE ... DOES> expression,
allows you to specify the run time behavior of words created
by the defining word.
At present, kForth does not allow making a defining word with the use of
":" inside the definition of a word -- use
CREATE ... DOES> instead.
The following common Forth defining words have source code
definitions, provided in
ans-words.4th:
n VALUE name |
DEFER name |
An existing word may be referred to by another name, using the non-standard
word ALIAS.
ALIAS | xt -- | create a new word which has the same execution behavior as xt |
ALIAS name2
The following control structures are provided in kForth:
DO ... LOOP |
DO ... +LOOP |
?DO ... LOOP |
?DO ... +LOOP |
IF ... THEN |
IF ... ELSE ... THEN |
BEGIN ... AGAIN |
BEGIN ... UNTIL |
BEGIN ... WHILE ... REPEAT |
CASE ... OF ... ENDOF ... ENDCASE |
All control stuctures may be nested --- for DO loops
the number of levels of nesting is only limited by return stack space.
The following execution control words are also defined:
RECURSE |
LEAVE |
EXIT |
QUIT |
ABORT |
ABORT" |
RECURSE causes the currently executing word to be
executed.LEAVE removes the current loop parameters
from the return stack, by calling UNLOOP, and causes
an immediate jump out of the current loop. Execution
resumes at the instruction following the loop.EXIT causes an immediate return from the word
currently being executed. Note that EXIT from
within a loop requires that the loop parameters be discarded
from the return stack explicitly with UNLOOP.QUIT empties the return stack, terminates execution
of the current word and returns kForth to the interpreter mode.ABORT empties the data stack and executes QUIT.
ABORT" examines the flag on top of the stack and if the
flag is true, prints the message delimited by ", then executes
ABORT.CATCH and THROW
are defined in source in ans-words.4th.
DUP | n -- n n | duplicate |
?DUP | n -- n n | 0 | dup if not zero |
SWAP | n1 n2 -- n2 n1 | swap |
OVER | n1 n2 -- n1 n2 n1 | over |
ROT | n1 n2 n3 -- n2 n3 n1 | rotate cw |
-ROT | n1 n2 n3 -- n3 n1 n2 | rotate ccw |
DROP | n1 -- | drop |
NIP | n1 n2 -- n2 | nip |
TUCK | n1 n2 -- n2 n1 n2 | tuck |
PICK | ... n -- ... m | copy nth item deep |
ROLL | ... n -- ... m | rotate nth item deep to top of stack |
DEPTH | ... -- ... n | stack depth |
2DUP | n1 n2 -- n1 n2 n1 n2 | |
2SWAP |
n1 n2 n3 n4 -- n3 n4 n1 n2 | |
2OVER |
n1 n2 n3 n4 -- n1 n2 n3 n4 n1 n2 | |
2ROT |
n1 n2 n3 n4 n5 n6 -- n3 n4 n5 n6 n1n2 | |
2DROP |
n1 n2 -- | |
FDUP | r -- r r | duplicate a floating point number on top of the stack |
FSWAP | r1 r2 -- r2 r1 | swap two floating point numbers on the stack |
FOVER | r1 r2 -- r1 r2 r1 | copy the floating point number one deep onto top of stack |
FROT | r1 r2 r3 -- r2 r3 r1 | rotate the order of three fp numbers on the stack |
FDROP | r -- | drop a floating point number from the stack |
F2DROP | r1 r2 -- | drop two fp numbers from the stack |
F2DUP | r1 r2 -- r1 r2 r1 r2 | duplicate a pair of fp numbers on the stack |
Return stack operations are:
>R |
n -- | push onto return stack |
R> |
-- n | pop from return stack |
R@ |
-- n | copy from top of return stack |
2>R |
d -- | push two stack cells onto return stack |
2R> |
-- d | pop two cells from return stack |
2R@ |
-- d | copy two cells from top of return stack |
I | -- n | current loop index |
J | -- n | next outer loop index |
UNLOOP | -- | discard loop parameters from return stack |
Note that 2>R is not equivalent to
the sequence >R >R. The order of the
two single length elements on top of the return
stack is different for the two cases. 2>R
pushes two items from the top of the stack so that they
have the same order on the return stack. The
sequence 2>R 2R>, however, is identical
to the sequence >R >R R> R>.
@ | a -- n | fetch single |
! | n a -- | store single n to address a |
2@ | a -- d | fetch double number from address a |
2! | d a -- | store double number to address a |
A@ | a1 -- a2 | fetch address from address a |
C@ | a -- n | fetch byte |
C! |
n a -- | store byte |
W@ | a -- n | fetch signed word |
W! | n a -- | store signed word |
SF@ | a -- r | fetch single precision float |
SF! | r a -- | store r as single precision float |
DF@ | a -- r | fetch double precision float |
DF! | r a -- | store double precision float |
F@ | a -- r | same as DF@ |
F! | r a -- | same as DF! |
SP@ | -- a | fetch data stack pointer |
RP@ | -- a | fetch return stack pointer |
SP! | a -- | set data stack pointer |
RP! | a -- | set return stack pointer |
? | a -- | fetch and print single; equivalent to @ . |
ALLOT | u -- | allocates u bytes in the dictionary |
?ALLOT | u -- a | allocates u bytes in the dictionary and returns |
| starting address of the allocated region | ||
ALLOCATE | u -- a n | reserve u bytes of system memory and return starting |
| address of the allocated region and error code | ||
FREE | a -- n | release memory previously reserved with ALLOCATE |
| and return error code (0 = success) | ||
RESIZE | a1 u -- a2 ior | change size of previously ALLOCATEd region |
| to u bytes; ior = 0 if success | ||
C" | -- ^str | compile a counted string into the string table; |
| the string is taken from the input stream and | ||
| must be terminated by " | ||
S" | -- a u | compile a string and return address and count |
COUNT | ^str -- a u | convert counted string address to character |
| buffer address a and character count u | ||
MOVE | a1 a2 u -- | move u bytes from source a1 to dest a2; handle overlapping region |
FILL | a u1 n2 -- | fill u1 bytes with byte value n2 starting at a |
ERASE | a u -- | fill u bytes with zero starting at a |
See also String Operations.
The following standard memory words are provided in Forth source in
ans-words.4th and
dump.4th:
PAD | -- a | return address of a scratch-pad in memory for temporary use | ans-words.4th |
DUMP | a u -- | output a hexadecimal display of the u bytes starting at address 'a' | dump.4th |
The non-ANS standard word A@ is needed because
kForth performs type checking for operands involved in
memory access. It is essentially identical to @
except the type field is set to be an address for the
retrieved value. Addresses may be stored in ordinary variables
using !; however they should be retrieved with
A@.
The behavior of ALLOT does not conform exactly
to the ANS standard. ALLOT dynamically allocates
the requested amount of memory and sets the parameter field
address (PFA) of the last created word to the address of the
alloted region. Thus, ALLOT should always be
preceeded by CREATE. In kForth, an attempt to
ALLOT without first creating a named dictionary
entry, using CREATE, will result in a virtual
machine error. Thus kForth limits the use of ALLOT,
but code written for kForth will be portable to ANS Forths.
The non-ANS standard word ?ALLOT is provided
because kForth contains no HERE address.
?ALLOT should be preceeded by CREATE
as described above. All memory is dynamically allocated, and freed
upon exiting kForth.
-TRAILING | a u1 -- a u2 | reduce string length to ignore trailing spaces |
/STRING | a1 u1 n -- a2 u2 | a2 = a1 + n, u2 = u1 - n |
BLANK | a u -- | fill u bytes with the blank-space character starting at a |
CMOVE | a1 a2 u -- | move u bytes from source a1 to dest a2 |
CMOVE> | a1 a2 u -- | move u bytes from a1 to a2 in descending order |
COMPARE | a1 u1 a2 u2 -- n | compare the strings a1 u1 and a2 u2. Return zero if they are equal. |
SEARCH | a1 u1 a2 u2 -- a3 u3 b | search for the string a2 u2 within the string a1 u1; |
return true if found and the substring a3 u3 |
||
SLITERAL | a u -- | compile a string address and count from the stack into the current definition |
The following useful string words are provided in
strings.4th.
SCAN | a1 u1 n -- a2 u2 | search for first occurence of character value n in the string |
| specified by a1 u1. Return the substring a2 u2 starting | ||
| with the search character | ||
SKIP | a1 u1 n -- a2 u2 | search for first occurence of character value not equal to n |
See also Memory Operations.
AND | n1 n2 -- n3 | bitwise AND of n1 and n2 |
OR | n1 n2 -- n3 | bitwise OR of n1 and n2 |
XOR | n2 n2 -- n3 | bitwise exclusive OR of n1 and n2 |
NOT | n1 -- n2 | one's complement of n1 |
INVERT | n1 -- n2 | same as NOT |
LSHIFT | n1 n2 -- n3 | n3 is n1 shifted left by n2 bits |
RSHIFT | n1 n2 -- n3 | n3 is n1 shifted right by n2 bits |
Single and Double Integer Operations
| 1+ | n1 -- n2 | increment (n2 = n1 + 1) |
| 1- | n1 -- n2 | decrement (n2 = n1 - 1) |
| 2+ | n1 -- n2 | n2 = n1 + 2 |
| 2- | n1 -- n2 | n2 = n1 - 2 |
| 2* | n1 -- n2 | arithmetic left shift (n2 = n1*2) |
| 2/ | n1 -- n2 | arithmetic right shift (n2 = n1/2) |
CELLS | n1 -- n2 | n2 is n1 times size in bytes of a cell (4) |
CELL+ | n1 -- n2 | n2 is n1 plus the size in bytes of a cell |
FLOATS | n1 -- n2 | n2 is n1 times size of a floating point number |
FLOAT+ | n1 -- n2 | n2 is n1 plus the size of a floating point number |
DFLOATS | n1 -- n2 | n2 is n1 times size of double precision fp number |
DFLOAT+ | n1 -- n2 | n2 is n1 plus size of double precision fp number |
SFLOATS | n1 -- n2 | n2 is n1 times size of single precision fp number |
SFLOAT+ | n1 -- n2 | n2 is n1 plus size of single precision fp number |
CHAR+ | n1 -- n2 | same as 1+ |
| + | n1 n2 -- n3 | add |
| - | n1 n2 -- n3 | subtract (n3 = n1 - n2) |
| * | n1 n2 -- n3 | multiply |
| / | n1 n2 -- n3 | divide ( n3 = n1/n2) |
| +! | n a -- | add n to value at address a |
MOD | n1 n2 -- n3 | modulus or remainder |
/MOD | n1 n2 -- n3 n4 | n3 = remainder and n4 = quotient for n1/n2 |
*/ | n1 n2 n3 -- n4 | n4 = n1*n2/n3; intermediate value is 64 bit |
*/MOD | n1 n2 n3 -- n4 n5 | n4 and n5 are remainder and quotient for n1*n2/n3 |
M+ | d1 n -- d2 | add single to double integer |
M* | n1 n2 -- d | multiply two singles and return signed double |
M*/ | d1 n1 +n2 -- d2 | multiply d1 by n1 to obtain triple cell result; then divide result by n2>0 to give signed double d2 |
UM* | u1 u2 -- ud | multiply unsigned singles and return unsigned double |
UM/MOD | ud u1 -- u2 u3 | divide unsigned double number by unsigned single |
| and return remainder (u2) and quotient (u3). | ||
| Returns -1 -1 for u2 and u3 on division overflow | ||
FM/MOD | d n1 -- n2 n3 | divide double by single to give floored quotient n3 and modulus n2 |
SM/REM | d n1 -- n2 n3 | divide double by single to give symmetric quotient n3 and remainder n2 |
DS* | d n -- t | multiply double and single to give signed triple length product |
UDM* | ud u -- ut | multiply unsigned double and unsigned single to give unsigned triple length product |
UTM/ | ut u -- ud | divide unsigned triple by unsigned single to give unsigned double quotient |
UTS/MOD | ut1 u1 -- ut2 u2 | Divide unsigned triple ut1 by unsigned single u1 to give unsigned triple quotient ut2 and unsigned single remainder u2 |
STS/REM | t1 n1 -- t2 n2 | Divide signed triple t1 by signed single n1 to give signed triple quotient t2 and signed remainder n2 |
D+ | d1 d2 -- d3 | double number addition |
D- | d1 d2 -- d3 | double number subtraction |
ABS | n1 -- n2 | absolute value |
NEGATE | n1 -- n2 | n2 = -n1 |
DABS | d1 -- d2 | double number absolute value |
DNEGATE | d1 -- d2 | double number negation |
MIN | n1 n2 -- n1 | n2 | minimum of n1 and n2 |
MAX | n1 n2 -- n1 | n2 | maximum of n1 and n2 |
DMIN | d1 d2 -- d1|d2 | minimum of d1 and d2 |
DMAX | d1 d2 -- d1|d2 | maximum of d1 and d2 |
| = | n1 n2 -- b | test n1 equal to n2 |
| <> | n1 n2 -- b | test n1 not equal to n2 |
| < | n1 n2 -- b | test n1 less than n2 |
| > | n1 n2 -- b | test n1 greater than n2 |
| <= | n1 n2 -- b | test n1 less than or equal to n2 |
| >= | n1 n2 -- b | test n1 greater than or equal to n2 |
U< | u1 u2 -- b | test unsigned u1 less than u2 |
U> | u1 u2 -- b | test unsigned u1 greater than u2 |
D= | d1 d2 -- b | test d1 equal to d2 |
D< | d1 d2 -- b | test d1 less than d2 |
DU< | ud1 ud2 -- b | test ud1 less than ud2 |
| 0< | n -- b | test n less than zero |
| 0> | n -- b | test n greater than zero |
| 0= | n -- b | test n equal to zero |
| 0<> | n -- b | test n not equal to zero |
D0= | d -- b | test d equal to zero |
D2* | d1 -- d2 | d2 is the arithmetic left shift of d1 |
D2/ | d1 -- d2 | d2 is the arithmetic right shift of d1 |
WITHIN | n1|u1 n2|u2 n3|u3 -- b | return TRUE if n2|u2 <= n1|u1 < n3|u3, given n2|u2 < n3|u3 |
TRUE (-1) and
FALSE (0).
Floating Point Operations
F+ | r1 r2 -- r3 | fadd |
F- | r1 r2 -- r3 | fsubtract (r3 = r1 - r2) |
F* | r1 r2 -- r3 | fmultiply |
F/ | r1 r2 -- r3 | fdivide ( r3 = r1/r2) |
FABS | r1 -- r2 | absolute value |
FNEGATE | r1 -- r2 | r2 = -r1 |
FROUND | r1 -- r2 | round to nearest whole number |
FTRUNC | r1 -- r2 | truncate, towards zero, to whole number |
FLOOR | r1 -- r2 | truncate, towards minus infinity, to whole number |
FMIN | r1 r2 -- r1 | r2 | minimum of r1 and r2 |
FMAX | r1 r2 -- r1 | r2 | maximum of r1 and r2 |
F0= | r -- b | test r equal to zero |
F0< | r -- b | test r less than zero |
F0> | r -- b | test r greater than zero |
F= | r1 r2 -- b | test r1 equal to r2 |
F<> | r1 r2 -- b | test r1 not equal to r2 |
F< | r1 r2 -- b | test r1 less than r2 |
F> | r1 r2 -- b | test r1 greater than r2 |
F<= | r1 r2 -- b | test r1 less than or equal to r2 |
F>= | r1 r2 -- b | test r1 greater than or equal to r2 |
The following standard word is provided as Forth source in
ans-words.4th:
F~ |
r1 r2 r3 -- b | test r1 approximately equal to r2, within uncertainty r3; |
| if r3 = 0e, r1 and r2 must be exactly equal in their binary representation |
F** | r1 r2 -- r3 | r3 = r1 raised to power of r2 |
FSQRT | r1 -- r2 | square root |
FLOG | r1 -- r2 | r2 = log base 10 of r1 |
FALOG | r1 -- r2 | r2 = 10 raised to power of r1 |
FEXP | r1 -- r2 | r2 = exp(r1) |
FLN | r1 -- r2 | r2 = log base e of r1 |
DEG>RAD | r1 -- r2 | degrees to radians |
RAD>DEG | r1 -- r2 | radians to degrees |
FSIN | r1 -- r2 | r2 = sin(r1) |
FCOS | r1 -- r2 | r2 = cos(r1) |
FSINCOS | r1 -- r2 r3 | r2 = sin(r1); r3 = cos(r1) |
FTAN | r1 -- r2 | r2 = tan(r1) |
FASIN | r1 -- r2 | arc sine |
FACOS | r1 -- r2 | arc cosine |
FATAN | r1 -- r2 | arc tangent |
FATAN2 | r1 r2 -- r3 | r3 is arc tangent of r1/r2 with proper quadrant |
FSINH | r1 -- r2 | r2 = sinh(r1) |
FCOSH | r1 -- r2 | r2 = cosh(r1) |
FTANH | r1 -- r2 | r2 = tanh(r1) |
FASINH | r1 -- r2 | inverse hyperbolic sine |
FACOSH | r1 -- r2 | inverse hyperbolic cosine |
FATANH | r1 -- r2 | inverse hyperbolic tangent |
S>D | n -- d | convert single integer to double length integer |
D>S | d -- n | convert signed double integer to signed integer |
S>F | n -- r | convert single integer to floating point number |
D>F | d -- r | convert double length integer to fp number |
FROUND>S | r -- n | convert floating point to integer by rounding |
FTRUNC>S | r -- n | convert floating point to integer by truncating towards zero |
F>D | r -- d | convert fp number to double integer by truncating towards zero |
>FLOAT | a u -- r TRUE | FALSE | convert string to floating point number |
| return fp number and TRUE if successful, FALSE otherwise | ||
>NUMBER | ud1 a1 u1 -- ud2 a2 u2 | convert digits of string a1 u1 and add this number |
| to ud1*base; result is ud2, and a2 u2 point | ||
| to remaining part of string | ||
NUMBER? | ^str -- d b | convert counted string to signed double number |
| b is TRUE if successful | ||
<# | ud -- ud | begin conversion of unsigned double to a string |
# | ud1 -- ud2 | convert the least significant digit of ud1 to a character; |
| concatenate character to conversion string. | ||
#S | ud1 -- 0 0 | convert all significant digits in ud1 to string |
SIGN | n -- | attach minus sign to conversion string if n < 0 |
HOLD | n -- | attach character with ASCII code n to the conversion string |
#> | ud -- a u | drop the double number and return the string address and count |
Other useful conversion words for number to string conversion
and vice-versa are given in Forth source in
strings.4th.
BASE | -- a | return the address containing current number base |
DECIMAL | -- | set the number base to ten |
BINARY | -- | set the number base to two |
HEX | -- | set the number base to sixteen |
KEY | -- n | wait for key press and return key code |
ACCEPT | a n1 -- n2 | read up to n1 characters into buffer a |
| from keyboard. n2 is actual number input. | ||
BL | -- 32 | return the ascii value for a blank space character |
WORD | n -- ^str | parse a word from the input stream, delimited by |
| character with ascii value n and return | ||
| the address of a counted string containing the word | ||
CHAR | -- n | parse the next word, delimited by a space and return |
| the ascii value of its first character | ||
[CHAR] | -- n | version of CHAR for use in compile state |
. | n -- | display top item on the stack in the current base |
.R | n m -- | display n in the current base in m-wide field |
U. | u -- | display unsigned single in current base |
U.R | u m -- | display u in the current base in m-wide field |
D. | d -- | display signed double length number |
PRECISION | -- u | return the number of significant digits output by FS. |
SET-PRECISION | u -- | set the numer of significant digits output by FS. |
FS. | r -- | display the floating point number using scientific |
| notation, with the number of significant digits | ||
specified by PRECISION |
||
F. | r -- | display the floating point number on top of the stack, |
| using an automatic format. | ||
.S | n1 n2 ... -- n1 n2 ... | non-destructive display of the stack |
." | -- | display text message; the message is read from |
| the input stream and must be terminated by " | ||
.( | -- | display text message from input stream; message |
| is terminated by ')'. The word is executed immediately. | ||
CR | -- | output carriage return |
SPACES | n -- | output n spaces |
EMIT | n -- | output character with ascii value n |
TYPE | a n -- | display n characters from buffer at a |
SOURCE | -- a u | return address and count of the input buffer |
REFILL | -- b | attempt to read another line from the input source and return flag |
>FILE | -- | change output stream from the console to a file. |
| The filename is the next word in the input stream | ||
CONSOLE | -- | reset output stream to the console |
PAGE |
-- | clear the screen and put cursor at top left |
AT-XY | n1 n2 -- | position cursor at column n1 and row n2, origin is (0,0) |
OPEN |
^name n1 -- n2 | open file specified by counted string ^name |
| in mode n1, which can be the following: | ||
| 0 read-only (R/O) | ||
| 1 write-only (W/O) | ||
| 2 read-write (R/W) | ||
| n2 is the file descriptor, a non-negative | ||
| integer if successful. | ||
LSEEK | n1 n2 n3 -- n4 | change current position in opened file |
| n1 is the file descriptor | ||
| n2 is the offset, and | ||
| n3 is the mode with the following meaning: | ||
| 0 offset is relative to start of file | ||
| 1 offset is relative to current position | ||
| 2 offset is relative to end of file | ||
| n4 is the resulting offset from the | ||
| beginning of the file, or -1 if error. | ||
READ | n1 a n2 -- n3 | read n2 bytes into buffer address a, from |
| file with descriptor n1. | ||
| n3 is the number of bytes actually read. | ||
WRITE | n1 a n2 -- n3 | write n2 bytes from buffer address a to |
| file with descriptor n1. | ||
| n3 is the number of bytes actually written. | ||
CLOSE | n1 -- n2 | close file with descriptor n1 and return |
| status n2 (0 if successful, -1 if error). | ||
INCLUDE | -- | read and process the specified Forth source file |
INCLUDED | a u -- ? | set the input stream for the interpreter to the |
| specified file and process it line by line |
The following ANS standard file access words are provided as Forth
definitions in files.4th:
R/O | -- n | "read-only" file access method | |
W/O | -- n | "write-only" file access method | |
R/W | -- n | "read-write" file access method | |
CREATE-FILE |
a u n1 -- n2 n3 | create a file with name specified by string address and count a u, | |
| and access method n1. Return file descriptor n2 and result code n3 | |||
OPEN-FILE |
a u n1 -- n2 n3 | open an existing file and return file descriptor n2 and result code n3 | |
CLOSE-FILE |
n1 -- n2 | close the file with descriptor n1 and return result code n2 | |
READ-FILE |
a u1 n1 -- u2 n2 | read u1 bytes into buffer at address 'a' from file with descriptor n1 | |
| and return actual number of bytes read u2 and result code n2 | |||
WRITE-FILE |
a u n1 -- n2 | write u bytes from buffer 'a' to file with descriptor n1; return result code n2 | |
FILE-POSITION |
n1 -- ud n2 | return the current file position ud and result code n2 | |
REPOSITION-FILE |
ud n1 -- n2 | set file position to ud for file with descriptor n1 and return result code n2 | |
FILE-SIZE |
n1 -- ud n2 | return the size of the file ud and the result code n2 | |
FILE-EXISTS |
^str -- b | return TRUE if the specified file exists | |
DELETE-FILE |
a u -- n | delete the file specified by string a u, and return result code n (not in Cygwin) | |
READ-LINE |
a u1 n1 -- u2 b n2 | read a line of text, with at most u1 bytes, from file with descriptor n1 into the buffer 'a'; return actual bytes read u2, success flag, and result code n2 | |
WRITE-LINE |
a u n1 -- n2 | write a line of text having u bytes from buffer 'a' into file | |
| with descriptor n1, and return result code n2 |
SYSTEM | ^str -- n | execute a shell command; ^str is the command line passed to the shell. |
| Return code n is -1 on error, or the return value from the command. | ||
SYSCALL | n1 ... nm m ncall -- nerr | perform system call ncall, with arguments n1 to nm, where 0<=m<=6 (not functional under Cygwin) |
BYE | -- | close the Forth environment and exit to the system. |
CHDIR | ^path -- n | change the current directory to the one specified in |
| the counted string ^path; n is OS dependent return code | ||
IOCTL | n1 n2 a -- n3 | send device control request n2 to file with descriptor n1. Additional parameters are passed through buffer at address a. n3 is the status (0 if successful, -1 if error). |
TIME&DAY | -- sec min hr day mo yr | return the local time |
MS | u -- | wait for at least u milliseconds |
MS@ | -- u | return number of milliseconds elapsed since start of kForth |
DLOPEN | azstr bflag -- nhandle | load the dynamic library file |
DLERROR | -- azstr | return address of null terminated error string |
DLSYM | nhandle azsym -- addr | return address of symbol in library |
DLCLOSE | nhandle -- nerr | close the dynamic library |
FORTH-SIGNAL | a n -- aold | install Forth word as handler for signal n |
RAISE | n -- ior | assert signal n |
SET-ITIMER | n1 a1 a2 -- n2 | set up timer signals |
GET-ITIMER | n a -- n2 | get timer countdown count |
USLEEP | u -- | wait for at least u microseconds |
| (For Windows version, resolution is 1000) |
Numerous operating system functions are defined as Forth words in
syscalls.4th.
CALL | a -- | call machine language subroutine at address a |