kForth Dictionary

Dictionary

Dictionary Maintenance
Compilation and Execution Words
Defining Words
Control Structures
Stack and Memory Operations
Logic and Bit Manipulation Operations
Arithmetic and Relational Operations
Floating Point Functions
Number Conversion
Input and Output
File Access
Operating System Interface
Miscellaneous

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
b boolean flag: true or false (-1 or 0) 1
f double precision floating point value 2
^str counted string address 1

Dictionary Maintenance

`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 dictionary
`FIND`	^str -- a flag	search the dictionary for the word specified by the counted string;
		flag is true if found and a is execution address

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.

The word COLD deletes all non-intrinsic definitions and strings, resets all stacks, and restarts the Forth environment in interpreter mode.

Compilation and Execution Words

`IMMEDIATE`	--	set the precedence of the most recently defined word
`NONDEFERRED`	--	set the precedence of the most recently defined word
`POSTPONE`	--	defer execution of an immediate word inside colon definition
`LITERAL`	n \| a --	compile a number or address 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)
`EXECUTE`	a --	execute a word with its cfa given on the stack
`EVALUATE`	a u --	interpret and execute source code contained in a string
`[`	--	enter interpretation state
`]`	--	enter compilation state
`STATE`	-- b	return `true (-1)` if compiling; `false (0)` otherwise

The words ' (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.

Defining Words

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

: NAME ... ;

the following defining words are also provided:

CREATE name

VARIABLE name

n CONSTANT 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.

Control Structures

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.

Stack and Memory Operations

Allowed data stack operations are listed in the following table:

`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`	f -- 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
`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>.

The following memory access words are implemented:

`@`	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 -- 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
`?`	a --	fetch and print single; equivalent to `@ .`
`ALLOT`	n --	allocates n bytes in the dictionary
`?ALLOT`	n -- a	allocates n bytes in the dictionary and returns
		starting address of the allocated region
`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 n	compile a string and return address and count
`COUNT`	^str -- a n	convert counted string address to character
		buffer address a and character count n
`CMOVE`	a1 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
`FILL`	a n1 n2 --	fill n1 bytes with byte value n2 starting at a
`ERASE`	a n --	fill n bytes with zero starting at a
`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
`COMPARE`	a1 u1 a2 u2 -- n	compare the strings a1 u1 and a2 u2. Return zero if they are equal.

Since kForth uses the data stack for floating point operations, the words DF@ and F@ are equivalent to 2@, and DF! and F! are equivalent to 2!.

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

The behavior of ALLOT does not conform exactly to the ANSI 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 ANSI Forths.

The non-ANSI 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.

Logic and Bit Manipulation 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

Arithmetic and Relational Operations

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
`DFLOATS`	n1 -- n2	n2 is n1 times size of a floating point number
`DFLOAT+`	n1 -- n2	n2 is n1 plus the size of a floating point number
`SFLOATS`	n1 -- n2	same as `CELLS`
`SFLOAT+`	n1 -- n2	same as `CELL+`
`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
`/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
`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 remainder n2
`SM/REM`	d n1 -- n2 n3	divide double by single to give symmetric quotient n3
		and 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
=	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
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

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

Floating Point Operations

`F+`	f1 f2 -- f3	fadd
`F-`	f1 f2 -- f3	fsubtract (f3 = f1 - f2)
`F*`	f1 f2 -- f3	fmultiply
`F/`	f1 f2 -- f3	fdivide ( f3 = f1/f2)
`FABS`	f1 -- f2	absolute value
`FNEGATE`	f1 -- f2	f2 = -f1
`FROUND`	f1 -- f2	round to nearest whole number
`FLOOR`	f1 -- f2	round down to whole number
`FMIN`	f1 f2 -- f1 \| f2	minimum of f1 and f2
`FMAX`	f1 f2 -- f1 \| f2	maximum of f1 and f2
`F0=`	f -- b	test f equal to zero
`F0<`	f -- b	test f less than zero
`F=`	f1 f2 -- b	test 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
`FSQRT`	f1 -- f2	square root
`FLOG`	f1 -- f2	f2 = log base 10 of f1
`FEXP`	f1 -- f2	f2 = exp(f1)
`FLN`	f1 -- f2	f2 = log base e of f1
`DEG>RAD`	f1 -- f2	degrees to radians
`RAD>DEG`	f1 -- f2	radians to degrees
`FSIN`	f1 -- f2	f2 = sin(f1)
`FCOS`	f1 -- f2	f2 = cos(f1)
`FTAN`	f1 -- f2	f2 = tan(f1)
`FASIN`	f1 -- f2	arc sine
`FACOS`	f1 -- f2	arc cosine
`FATAN`	f1 -- f2	arc tangent
`FATAN2`	f1 f2 -- f3	f3 is arc tangent of f1/f2

Number Conversion

`S>D`	n -- d	convert single integer to double length integer
`S>F`	n -- f	convert single integer to floating point number
`D>F`	d -- f	convert double length integer to fp number
`F>S`	f -- n	convert floating point to integer by rounding;
		use `F>D` if truncation is desired
`F>D`	f -- d	convert fp number to double integer by truncation
`NUMBER?`	^str -- d b	convert counted string to signed double number
		b is TRUE if successfull
`<#`	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

Currently NUMBER? may only be used to translate a counted string into number that is within the bounds of a single length number. The returned double number may be converted to 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
`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
`F.`	f --	display the floating point value on top of the stack
`.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
`>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 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.
`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).

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/NT).

Operating System Interface

`SYSTEM`	^str -- n	execute another process; ^str is the command line passed
		to the operating system. n is the return code
		and is OS dependent.
`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 (Linux only). 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
`USLEEP`	u --	wait for at least u microseconds
		(For Windows version, resolution is 1000)

Miscellaneous

CALL a -- call machine language subroutine at address a

	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
b	boolean flag: true or false (-1 or 0)	1
f	double precision floating point value	2
^str	counted string address	1