kForth Dictionary


  1. Defining Words
  2. Stack and Memory Operations
  3. Logic and Bit Manipulation Operations
  4. Control Structures
  5. Arithmetic and Relational Operations
  6. Floating Point Functions
  7. Number Conversion
  8. Input and Output
  9. File Access
  10. System


Defining Words

In addition to ordinary "colon definitions" of the form,

: NAME ... ;

the following defining words are also allowed:

CREATE name
VARIABLE name
n CONSTANT name
FVARIABLE name
f FCONSTANT name

CREATE is not currently supported inside word definitions; hence, the ability to create your own defining words is not available in kForth at the present time.

The word FORGET may be used to remove words from the dictionary. Typing

FORGET name


will remove name and all words defined after name from the dictionary.

Stack and Memory Operations

Allowed data stack operations are listed in the following table:

DUPn -- n nduplicate
?DUPn -- n n | 0 dup if not zero
SWAPn1 n2 -- n2 n1swap
OVERn1 n2 -- n1 n2 n1over
ROTn1 n2 n3 -- n2 n3 n1 rotate cw
-ROTn1 n2 n3 -- n3 n1 n2 rotate ccw
DROPn1 --drop
NIPn1 n2 -- n2nip
TUCKn1 n2 -- n2 n1 n2tuck
PICK... n -- ... m copy nth item deep
ROLL... n -- ... m rotate nth item deep to top of stack
DEPTH ... -- ... nstack depth
2DUPn1 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 --
FDUPf -- f f same as 2DUP
FSWAP f1 f2 -- f2 f1 same as 2SWAP
FOVER f1 f2 -- f1 f2 f1 same as 2OVER
FROT f1 f2 f3 -- f2 f3 f1 same as 2ROT
FDROP f1 -- same as 2DROP

Return stack operations are:

>R n -- push onto return stack
R> -- n pop from return stack
R@ -- n copy from top of return stack
I-- ncurrent loop index
J-- nnext outer loop index
UNLOOP -- discard loop parameters from return stack

The following memory access words are implemented:

@a -- nfetch single
!n a -- store single n 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 -- f fetch single precision float
SF!f a -- store f as single precision float
DF@a -- f fetch double precision float
DF!f a -- store double precision float
F@a -- f same as DF@
F!f a -- same as DF!
SP@-- a fetch data stack pointer
RP@-- a fetch return stack pointer
ALLOTn -- allocates n bytes in the dictionary
" -- ^str compile a counted string into the string table;
the string is taken from the input stream and
must be terminated by "
COUNT^str -- a n convert counted string address to character
buffer address a and character count n
CMOVEa1 a2 n -- move n bytes from source a1 to dest a2
CMOVE>a1 a2 n -- move n bytes from a1 to a2 in descending order
FILLa n1 n2 -- fill n1 bytes with byte value n2 starting at a

The non-ANSI 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 can be stored in ordinary variables using !; however they should be retrieved with A@.


Logic and Bit Manipulation Operations


ANDn1 n2 -- n3 bitwise AND of n1 and n2
ORn1 n2 -- n3 bitwise OR of n1 and n2
XORn2 n2 -- n3 bitwise exclusive OR of n1 and n2
NOTn1 -- n2 one's complement of n1
INVERTn1 -- n2 same as NOT
LSHIFTn1 n2 -- n3 n3 is n1 shifted left by n2 bits
RSHIFTn1 n2 -- n3 n3 is n1 shifted right by n2 bits


Control Structures

The following control structures are provided in kForth:

DO ... LOOP
DO ... +LOOP
IF ... THEN
IF ... ELSE ... THEN
BEGIN ... AGAIN
BEGIN ... UNTIL
BEGIN ... WHILE ... REPEAT

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:

LEAVE
EXIT
QUIT
ABORT

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.

Arithmetic and Relational Operations

Single Integer Operations

+n1 n2 -- n3add
-n1 n2 -- n3subtract (n3 = n1 - n2)
*n1 n2 -- n3multiply
/n1 n2 -- n3divide ( n3 = n1/n2)
+!n a -- add n to value at address a
1+n1 -- n2increment (n2 = n1 + 1)
1-n1 -- n2decrement (n2 = n1 - 1)
2+n1 -- n2n2 = n1 + 2
2-n1 -- n2n2 = n1 - 2
2*n1 -- n2arithmetic left shift (n2 = n1*2)
2/n1 -- n2arithmetic right shift (n2 = n1/2)
MODn1 n2 -- n3 modulus
/MODn1 n2 -- n3 n4 n3 = remainder and n4 = quotient for n1/n2
*/n1 n2 n3 -- n4 n4 = n1*n2/n3; intermediate value is 64 bit
*/MODn1 n2 n3 -- n4 n5 n4 and n5 are remainder and quotient for n1*n2/n3
ABSn1 -- n2 absolute value
NEGATEn1 -- n2 n2 = -n1
MINn1 n2 -- n1 | n2 minimum of n1 and n2
MAXn1 n2 -- n1 | n2 maximum of n1 and n2
=n1 n2 -- btest 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
0<n -- b test n less than zero
0>n -- btest n greater than zero
0=n -- btest n equal to zero

kForth provides pre-defined constants TRUE (-1) and FALSE (0).

Floating Point Operations

F+f1 f2 -- f3fadd
F-f1 f2 -- f3fsubtract (f3 = f1 - f2)
F*f1 f2 -- f3fmultiply
F/f1 f2 -- f3fdivide ( f3 = f1/f2)
FABSf1 -- f2absolute value
FNEGATEf1 -- f2f2 = -f1
FROUNDf1 -- f2round to nearest whole number
FLOORf1 -- f2round down to whole number
FMINf1 f2 -- f1 | f2 minimum of f1 and f2
FMAXf1 f2 -- f1 | f2 maximum of f1 and f2
F=f1 f2 -- btest f1 equal to f2
F<>f1 f2 -- b test f1 not equal to f2
F<f1 f2 -- b test f1 less than f2
F>f1 f2 -- b test f1 greater than f2
F<=f1 f2 -- b test f1 less than or equal to f2
F>=f1 f2 -- b test f1 greater than or equal to f2

Floating Point Functions


F**f1 f2 -- f3 f3 = f1 raised to power of f2
FSQRTf1 -- f2 square root
FLOGf1 -- f2 f2 = log base 10 of f1
FEXPf1 -- f2 f2 = exp(f1)
FLNf1 -- f2 f2 = log base e of f1
DEG>RADf1 -- f2 degrees to radians
RAD>DEGf1 -- f2 radians to degrees
FSINf1 -- f2f2 = sin(f1)
FCOSf1 -- f2f2 = cos(f1)
FTANf1 -- f2f2 = tan(f1)
FASINf1 -- f2 arc sine
FACOSf1 -- f2 arc cosine
FATANf1 -- f2 arc tangent
FATAN2f1 f2 -- f3 f3 is arc tangent of f1/f2


Number Conversion


S>Fn -- f convert single integer to floating point number
F>Sf -- n convert floating point to integer by rounding;
use FLOOR first if truncation is desired
NUMBER?^str -- d b convert counted string to signed double number
b is TRUE if successfull


Note that double numbers are not currently supported in kForth. NUMBER? may be used to translate a counted string into a single length number by dropping the top half of the returned double number. Other useful conversion words for converting strings to numbers and vice-versa are given in strings.4th.


Input and Output


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
ACCEPTa n1 -- n2 read up to n1 characters into buffer a
from keyboard. n2 is actual number input.
.n -- display top item on the stack in the current base
U.u -- display unsigned single in current base
F.f -- display the floating point value on top of the stack
.Sn1 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 "
CR -- output carriage return
SPACESn -- output n spaces
EMITn -- output character with ascii value n
TYPEa n -- display n characters from buffer at a


PAGE and other terminal control words for ANSI terminals are provided in the form of source code in ansi.4th

File Access


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.
LSEEKn1 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.
READn1 a n2 -- n3 read n2 bytes into buffer address a, from
file with descriptor n1.
n3 is the number of bytes actually read.
WRITEn1 a n2 -- n3 write n2 bytes from buffer address a to
file with descriptor n1.
n3 is the number of bytes actually written.
CLOSEn1 -- n2 close file with descriptor n1 and return
status n2 (0 if successful, -1 if error).
IOCTLn1 n2 a -- n3 send device control request n2 to file
with descriptor n1 (Linux only). Additional parameters
are passed through buffer at address a.
n3 is the status (0 if successful, -1 if error).


The ANS standard file access words are provided as Forth definitions in terms of these low-level words in files.4th (Linux) and filesw.4th (Win95/98).

System


CALLa -- call machine language subroutine at address a
USLEEPu -- suspend execution for at least u microseconds
(For Windows version, resolution is 1000)