TILE FORTH PACKAGE 6(7)

Mikael Patel mip at massormetrix.ida.liu.se
Tue Dec 19 04:53:11 AEST 1989


#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#		"End of archive 6 (of 7)."
# Contents:  doc/kernel.doc
# Wrapped by mip at massormetrix on Mon Dec 18 18:40:13 1989
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f doc/kernel.doc -a "${1}" != "-c" ; then 
  echo shar: Will not over-write existing file \"doc/kernel.doc\"
else
echo shar: Extracting \"doc/kernel.doc\" \(37708 characters\)
sed "s/^X//" >doc/kernel.doc <<'END_OF_doc/kernel.doc'
XFORTH(1)    	   	    STANDARD FORTH FUNCTIONS 	 		FORTH(1)
X
XNAME
X	forth - forth dictionary
X
XSYNOPSIS
X	forth ( -- )
X
X	false ( -- 0)	
X	true ( -- -1)
X	boolean ( n -- flag)
X	not ( 32b1 -- 32b2)
X	and ( 32b1 32b2 -- 32b3)
X	or ( 32b1 32b2 -- 32b3)
X	xor ( 32b1 32b2 -- 32b3)
X	?within ( value lower upper -- flag)
X
X	dup ( x -- x x)
X	drop ( x -- )
X	swap ( x y -- y x)	
X	over ( x y -- x y z)
X	rot ( x y z -- y z x)
X	pick ( +n -- x)
X	roll ( +n -- )
X	?dup ( x -- [x x] or [x])
X
X	>r ( x -- ) compilation
X	r> ( -- x) compilation
X	r@ ( -- x) compilation
X
X	depth ( -- +n)
X	.s ( -- )
X
X	< ( n1 n2 -- flag)
X	= ( w1 w2 -- flag)
X	> ( n1 n2 -- flag)
X	0< ( n -- flag)
X	0= ( w -- flag)
X	0> ( n -- flag)
X	u< ( u1 u2 -- flag)
X
X	nil ( -- 0)
X	-2 ( -- -2)
X	-1 ( -- -1)
X	0 ( -- 0)	
X	1 ( -- 1)
X	2 ( -- 2)
X
X	negate ( n1 -- n2)
X	+ ( w1 w2 -- w3)
X	- ( w1 w2 -- w3)
X	1+ ( w1 -- w2)
X	1- ( w1 -- w2)
X	2+ ( w1 -- w2)
X	2- ( w1 -- w2)
X	2* ( n1 -- n2)
X	2/ ( n1 -- n2)
X
X	<< ( n1 n2 -- n3)
X	* ( w1 w2 -- w3)
X	um* ( u1 u2 -- u3)
X	um/mod ( u1 u2 -- u3 u4)
X
X	>> ( n1 n2 -- n3)
X	/ ( w1 w2 -- w3)	
X	mod ( n1 n2 -- n3)
X	/mod ( w1 w2 -- w3 w4)
X	*/mod ( w1 w2 w3 -- w4 w5)
X	*/ ( w1 w2 w3 -- w4)
X
X	min ( n1 n2 -- n3)
X	max ( n1 n2 -- n3)
X	abs ( n -- u)
X
X	@ ( addr -- 32b)
X	! ( 23b addr -- )
X	w@ ( addr -- 16b)
X	w! ( 16b addr -- )
X	c@ ( addr -- 8b)
X	c!( 8b addr -- )
X	f@ ( x p w -- y)
X	f! ( y x p w -- z)
X	b@ ( x p -- y)
X	b! ( y x p -- z)
X
X	+! ( x1 addr -- )
X
X	cmove ( addr1 addr2 u -- )
X	cmove> ( addr1 addr2 u -- )
X	fill ( addr u 8b -- )
X	count ( addr1 -- addr2 +n)
X	-trailing ( addr +n1 -- addr +n2)
X
X	base ( -- addr)
X	binary ( -- )
X	octal ( -- )
X	decimal	( -- )
X	hex ( -- )
X	convert	( +d1 addr1 -- +d2 addr2)
X	<# ( x -- )
X	# ( +d1 -- +d2 )
X	#s ( +x -- 0)
X	hold ( char -- )
X	sign ( n -- )
X	#> ( x -- addr +n)
X
X	?number ( string -- [n true] or [string false])
X
X	do ( w1 w2 -- )	immediate compilation
X	?do ( w1 w2 -- ) immediate compilation
X	loop ( -- ) immediate compilation
X	+loop ( n -- ) immediate compilation
X	leave ( -- ) immediate compilation
X
X	i ( -- w) compilation
X	j ( -- w) compilation
X
X	if ( flag -- ) immediate compilation
X	else ( -- ) immediate compilation
X	then ( -- ) immediate compilation
X
X	case ( value -- ) immediate compilation
X	of ( value -- ) immediate compilation
X	endof ( -- ) immediate compilation
X	endcase ( -- ) immediate compilation
X
X	begin ( -- ) immediate compilation
X	until ( flag -- ) immediate compilation
X	while ( flag -- ) immediate compilation
X	repeat ( -- ) immediate compilation
X	again ( -- ) immediate compilation
X
X	recurse ( -- ) immediate compilation
X	tail-recurse ( -- ) immediate compilation
X
X	exit ( -- ) compilation
X	execute	( addr -- )
X	bye ( -- )
X
X	. ( n -- )
X	u. ( u -- )
X	ascii ( -- char) immediate
X	." ( -- ) immediate compilation
X	.( ( -- ) immediate
X	cr ( -- )
X
X	emit ( x -- )
X	type ( addr +n -- )
X	space ( -- )
X	spaces ( +n -- )
X
X	key ( -- x)
X	expect ( addr +n -- )
X	span ( -- addr)
X
X	forth-83 ( -- )
X	quit ( -- )
X	abort ( -- )
X	abort" ( flag -- ) immediate compilation
X
X	here ( -- addr)
X	pad ( -- addr)
X	tib ( -- addr)
X	>body ( addr1 -- addr2)
X	.name ( addr1 -- )
X
X	#if ( flag -- ) immediate
X	#else ( -- ) immediate
X	#then ( -- ) immediate
X	#ifdef ( -- ) immediate
X	#ifundef ( -- ) immediate
X
X	#include ( -- ) 
X	#path ( -- )
X
X	( ( -- ) immediate
X	\ ( -- ) immediate
X
X	, ( x -- )
X	allot ( w -- )
X	does> ( -- ) immediate compilation
X
X	immediate ( -- )
X	execution ( -- )	
X	compilation ( -- )
X	private ( -- )
X
X	[compile] ( -- ) immediate compilation 
X	?compile ( -- ) compilation
X	compile ( -- ) compilation
X	state ( -- addr)
X	compiling ( -- state)
X	literal	( n -- ) immediate compilation
X	[ ( -- ) immediate
X	] ( -- )
X
X	word ( char -- addr)
X
X	context ( -- addr)
X	current ( -- addr)
X	last ( -- addr)
X	definitions ( -- )
X	only ( -- )	
X	restore ( entry -- )
X
X	' ( -- addr)
X	['] ( -- addr) immediate compilation
X	lookup ( addr1 vocabulary -- addr2 n)
X	find ( addr1 -- addr2 n)
X	forget ( -- )
X	words ( -- ) immediate
X
X	entry ( parameter mode code name -- )
X	forward ( -- )
X	: ( -- )
X	; ( -- ) immediate compilation
X	create ( -- )
X	variable ( -- )
X	constant ( x -- )
X	vocabulary ( -- )
X	field ( x -- )
X
XDESCRIPTION
X	The language primitive in the Forth-83 Standard excluding the
X	block file word set.
X
Xforth ( -- )
X	The name of the primary vocabulary. Execution replaces the 
X	first vocabulary in the search order with "forth". "forth" is
X	initially the compilation vocabulary and the first vocabulary
X	in the search order. New definitions become part of the "forth"
X	vocabulary until a different compilation vocabulary is established.
X
Xfalse ( -- 0)	
X	Constant "true".
X
Xtrue ( -- -1)
X	Constant "false".
X
Xboolean ( n -- flag)
X	Maps numerical value to a boolean value, "true" or "false".
X	Non-zero values are mapped to "true" and zero to "false".
X
Xnot ( 32b1 -- 32b2)
X	"32b2" is the one's complements of "32b1".
X
Xand ( 32b1 32b2 -- 32b3)
X	"32b3" is the bit-by-bit logical "and" or "32b1" and "32b2".
X
Xor ( 32b1 32b2 -- 32b3)
X	"32b3" is the bit-by-bit inclusive-or of "32b1" with "32b2".
X
Xxor ( 32b1 32b2 -- 32b3)
X	"32b3" is the bit-by-bit exclusive-or "32b1" with "32b2".
X
X?within ( value lower upper -- flag)
X	Tests if the parameter "value" is within the range "lower" to
X	"upper". Returns "true" if within the range else "false".
X
Xdup ( x -- x x)
X	Duplicate "x".
X
Xdrop ( x -- )
X	"x" is removed from the stack.
X
Xswap ( x y -- y x)	
X	The top two stack entries are exchanged.
X
Xover ( x y -- x y z)
X	"z" is a copy of "x" over "y".
X
Xrot ( x y z -- y z x)
X	The top three stack entries are rotated, bringing the deepest
X	to the top.
X
Xpick ( +n -- x)
X	"x" is a copy of the "+n"-th stack element, not counting
X	"+n" itself. {0..depth-1}
X		0 pick is equivalent to dup
X		1 pick is equivalent to over
X
Xroll ( +n -- )
X	The "+n"-th stack value, not counting "+n" itself is first
X	removed and then transferred to the top of the stack, moving
X	the remaining values into the vacated position. {0..depth-1}.
X		0 roll is a null operation
X		1 roll is equivalent to swap
X		2 roll is equivalent to rot
X
X?dup ( x -- [x x] or [x])
X	Duplicate "x" if it is non-zero. 
X
X>r ( x -- ) compilation
X	Transfer "x" to the return stack.
X
Xr> ( -- x) compilation
X	"x" is removed from the return stack and transferred to
X	the data stack.
X
Xr@ ( -- x) compilation
X	"x" is a copy of the top of the return stack.
X
Xdepth ( -- +n)
X	"+n" is the number of values contained in the data stack 
X	before "+n" was placed on the stack.
X
X.s ( -- )
X	Display the current stack in the format:
X		[ <stack depth> ] <bottom> \ .... \ <top> 
X
X< ( n1 n2 -- flag)
X	"flag" is true if "n1" is less than "n2".
X
X= ( w1 w2 -- flag)
X	"flag" is true if "w1" is equal to "w2"
X
X> ( n1 n2 -- flag)
X	"flag" is true if "n1" is greater than "n2"
X
X0< ( n -- flag)
X	"flag" is true if "n" is less than zero (negative).
X
X0= ( w -- flag)
X	"flag" is true if "w" is zero.
X
X0> ( n -- flag)
X	"flag" is true if "n" is greater than zero.
X
Xu< ( u1 u2 -- flag)
X	"flag" is true if "u1" is less than "u2".
X
Xnil ( -- 0)
X	Constant for nil, none, pointer.
X
X-2 ( -- -2)
X	Constant minus two.
X
X-1 ( -- -1)
X	Constant minus one.
X
X0 ( -- 0)	
X	Constant zero.
X  
X1 ( -- 1)
X	Constant one.
X  	
X2 ( -- 2)
X 	Constant two.
X
X+ ( w1 w2 -- w3)
X	"w3" is the arithmetic sum of "w1" and "w2".
X
X- ( w1 w2 -- w3)
X	"w3" is the result of subtracting "w2" from "w1".
X
X1+ ( w1 -- w2)
X	"w2" is the result of adding one to "w1" according to
X	the operation of "+".
X
X1- ( w1 -- w2)
X	"w2" is the result of subtracting one to "w1" according to
X	the operation of "-".
X
X2+ ( w1 -- w2)
X	"w2" is the result of adding two to "w1" according to
X	the operation of "+".
X
X2- ( w1 -- w2)
X	"w2" is the result of subtracting two to "w1" according to
X	the operation of "-".
X
X2* ( n1 -- n2)
X	"n2" is the result of arithmetically shifting "n1" left one
X	bit. The sign is included in the shift and remains unchanged.
X
X2/ ( n1 -- n2)
X	"n2" is the result of arithmetically shifting "n1" right one
X	bit. The sign is included in the shift and remains unchanged.
X
X<< ( n1 n2 -- n3)
X	"n3" is the result of logically shifting "n1" left "n2" steps.
X
X* ( w1 w2 -- w3)
X	"w3" is the least-significant 32 bits of the arithmetic
X	product of "w1" times and "w2".
X
Xum* ( u1 u2 -- u3)
X	"u3" is the unsigned product of "u1" times "u2". All
X	values and arithmetic are unsigned.
X
Xum/mod ( u1 u2 -- u3 u4)
X	"u3" is the remainder and "u4" is the floor of the quotient
X	after dividing "u1" by the divisor "u2". All values and
X	arithmetic are unsigned. An error condition results if
X	the divisor is zero or if the quotient lies outside the
X	numerical range.
X
X>> ( n1 n2 -- n3)
X	"n3" is the result of logically shifting "n1" right "n2" steps.
X
X/ ( w1 w2 -- w3)	
X	"w3" is the floor of the quotient of "w1" divided by the 
X	divisor "w2". An error condition results if the divisor is 
X	zero.
X
Xmod ( n1 n2 -- n3)
X	"n3" is the remainder after dividing "n1" by divisor "n2". 
X	"n3" has the same sign as "n2" or is zero. An error condition
X	results if the divisor is zero or if the quotient falls outside 
X	of the numerical range.
X
X/mod ( w1 w2 -- w3 w4)
X	"w3" is the remainder and "w4" the floor of the quotient
X	of "w1" divided by the divisor "w2". "w3" has the same sign
X	as "w2" or is zero. An error condition results if the divisor 
X	is zero.
X
X*/mod ( w1 w2 w3 -- w4 w5)
X	"w1" is first multiplied by "w2" producing an intermediate 
X	32-bit result. "w4" is the remainder and "w5" is the floor
X	of the quotient of the intermediate 32-bit result divided by 
X	the divisor "w3".  A 32-bit intermediate product is used as 
X	for */.  "w4" has the same sign as "w3" or is zero. An error
X	condition results if the divisor is zero.
X
X*/ ( w1 w2 w3 -- w4)
X	"w1" is first multiplied by "w2" producing an intermediate 
X	32-bit result. "w4" is the floor of the quotient of the 
X	intermediate 32-bit result divided by the divisor "w3". The 
X	product of "w1" times "w2" is maintained as an intermediate 
X	32-bit result for greater precision then the otherwise 
X	equivalent sequence: w1 w2 * w3 /. An error condition results 
X	if the divisor is zero.
X
Xmin ( n1 n2 -- n3)
X	"n3" is the lesser of "n1" and "n2" according to the operation of <. 
X
Xmax ( n1 n2 -- n3)
X	"n3" is the greater of "n1" and "n2" according to the operation of >. 
X
Xabs ( n -- u)
X	"u" is the absolute value of "n". 
X
Xnegate ( n1 -- n2)
X	"n2" is the two's complement of "n1", i.e., the difference 
X	of zero less "n1".
X
X@ ( addr -- 32b)
X	"32b" is the value at "addr".
X
X! ( 23b addr -- )
X	The postfix assignment operator. Store "32b" at "addr". 
X
Xw@ ( addr -- 16b)
X	"16b" is the value at "addr".
X
Xw! ( 16b addr -- )
X	The postfix assignment operator. Store "16b" at "addr". 
X
Xc@ ( addr -- 8b)
X	"8b" is the value at "addr".
X
Xc!( 8b addr -- )
X	The postfix assignment operator. Store "8b" at "addr". 
X
Xf@ ( x p w -- y)
X	Field access within a 32-bit quantity. "y" are the bits within
X	"x" at position "p" and with a bit field width, "w". Bits positions
X	are counted from right to left starting with zero. A field is 
X	defined from a position and upwards.
X
Xf! ( y x p w -- z)
X	Inserts the value of "y" into "x" at the bit field which is defined
X	by the position "p" and with the width "w". The value "y" is shifted
X	and masked into "x" to form the result "z".
X
Xb@ ( x p -- y)
X	Returns "true" if the bit a position "p" in "x" is one else "zero".
X
Xb! ( y x p -- z)
X	Returns "z", the result of setting the bit at position "p" in "x"
X	according to the value of "y". The bit is set to zero if "y" is
X	zero else one.
X
X+! ( x1 addr -- )
X	"x1" is added to the value at "addr" using the convention
X	for "+". The sum replaces the original value at "addr". 
X
Xcmove ( addr1 addr2 u -- )
X	Move the "u" bytes at address "addr1" to "addr2". The byte 
X	at "addr1" is moved first, proceeding toward high memory. 
X	If "u" is zero nothing is moved.
X
Xcmove> ( addr1 addr2 u -- )
X	Move the "u" bytes at address "addr1" to "addr2". The move 
X	begins by moving the byte at ("addr1"+"u"-1) to ("addr2"+"u"-1)
X	and proceeds to successively lower addresses for "u" bytes. 
X	If "u" is zero nothing is moved. Useful for sliding a string 
X	towards higher addresses.
X
Xfill ( addr u 8b -- )
X	"u" bytes of memory beginning at "addr" are set to "8b". 
X	No action is taken is "u" is zero.
X
Xcount ( addr1 -- addr2 +n)
X	"addr2" is "addr1"+1 and "+n" is the length of the counted
X	string at "addr1". The byte "addr1" contains the byte count
X	"+n". Range of "+n" is {0..255}. 
X
X-trailing ( addr +n1 -- addr +n2)
X	The character counter "+n1" of a text string beginning at
X	"addr" is adjusted to exclude trailing spaces. If "+n1" is
X	zero, then "+n2" is zero. If the entire string consists of
X	spaces, then "+n2" is zero. 
X
Xbase ( -- addr)
X	The address of a variable containing the current numeric 
X	conversion radix. 
X
Xbinary	( -- )
X	Set the input-output numeric conversion base to 2.
X
Xoctal	( -- )
X	Set the input-output numeric conversion base to 8.
X
Xdecimal	( -- )
X	Set the input-output numeric conversion base to 10.
X
Xhex	( -- )
X	Set the input-output numeric conversion base to 16.
X
Xconvert	( +d1 addr1 -- +d2 addr2)
X	"+d2" is the result of converting the characters within the
X	text beginning at "addr1"+1 into digits, using the value of
X	BASE, and accumulating each into "+d1" after multiplying "+d1" 
X	by the value of "base". Conversion continues until an inconvertible
X	character is encountered. "addr2" is the location of the first
X	inconvertible character.
X
X<# ( x -- )
X	Initialize pictured numeric output conversion. The words:
X		#  #>  #s  <#  hold  sign
X	can be used to specify the conversion of a double number
X	into an ASCII text string stored in right-to-left order.
X
X# ( +d1 -- +d2 )
X	The remainder of "+d1" divided by the value of BASE is 
X	converted to a ASCII character and appended to the output
X	string toward lower memory addresses. "+d2" if the quotient
X	and is maintained for further processing. Typically used
X	between "<#" and "#>". See: <#, #s, hold, sign and #>.
X
X#s ( +x -- 0)
X	"+x" is converted appending each resultant character into 
X	the pictured numeric output string until the quotient (see: #) 
X	is zero. A single zero is appended to the output string if the 
X	number was initially zero. Typically used between <# and #>. 
X	See: <#, #, hold, sign and #>.
X
Xhold ( char -- )
X	"char" is inserted into a pictured numeric output string. 
X	Typically used between <# and #>. See: <#, #, #S, SIGN and #>.
X
Xsign ( n -- )
X	If "n" is negative, an ASCII "-" (minus sign) is appended
X	to the pictured numerical output string. Typically used
X	between <# and #>. 
X
X#> ( x -- addr +n)
X	Pictured numeric output conversion is ended dropping "x".
X	"addr" is the address of the resulting output string. 
X	"+n" is the number of characters in the output string. 
X	"addr" and "+n" together are suitable for "type". 
X	See: <#, #, #s, hold and sign.
X
X?number ( string -- [n true] or [string false])
X	Convert a string of character to a number using the current base.
X	If the conversion is not possible the string is returned with a
X	false flag indicating that the conversion failed otherwise the
X	conversion value, the number, and a true flag is returned.
X
Xdo ( w1 w2 -- )	immediate compilation
X	Used in the form:
X		do ... leave ...  loop
X	or
X		do ... leave ... +loop
X	Begins a loop which terminates based on control parameters. 
X	The loop index begins at "w2", and terminates based on the
X	limit "w1". See "loop" and "+loop" for details on how the loop
X	is terminated. The loop is always executed at least once.
X
X?do ( w1 w2 -- ) immediate compilation
X	Used in the form:
X		?do ... leave ...  loop
X	or
X		?do ... leave ... +loop
X	Begins a checked entry loop which terminates based on control
X	 parameters. The loop index begins at "w2", and terminates based
X	 on the	limit "w1". See "loop" and "+loop" for details on how the loop
X	is terminated. If "w1" and "w2" are equal the loop section is skipped.
X
Xloop ( -- ) immediate compilation
X	Increments the "do-loop" index by one. If the new index was
X	incremented across the boundary between limit-1 and limit
X	the loop is terminated and the loop control parameters are 
X	discarded. When the loop is not terminated, execution continues
X	to just after the corresponding "do". 
X
X+loop ( n -- ) immediate compilation
X	"n" is added to the loop index. If the new index was incremented
X	across the boundary between limit-1 and limit then the loop is
X	terminated and the loop control parameters are discarded. When
X	the loop is not terminated, execution continues to just after 
X	the corresponding "do". "+loop" is not available outside a colon
X	definition. 
X
Xleave ( -- ) compilation
X	Transfers execution to just beyond the next "loop" or "+loop".
X	The loop is terminated and the loop control parameters are
X	discarded. May only be used in the form:
X		do ... leave ... loop
X		  or
X		do ... leave ... +loop
X	"leave" may appear within other control structures which are
X	nested within the "do-loop" structure. More than one "leave" may
X	appear within a do-loop. 
X
X
Xi ( -- w) compilation
X	"w" is a copy of the current loop index. May only be used in
X	the form:
X		do ... i ... loop
X		  or
X		do ... i ... +loop
X	"i" is not visible outside a colon definition, i.e., when
X	text interpreting.
X
Xj ( -- w) compilation
X	"w" is a copy of the index of the next outer loop. May only
X	be used within a nested "do-loop" or "do-+loop" in the form:
X		do ... do ... j ... loop ... loop
X	"j" is not visible outside a colon definition, i.e., when
X	text interpreting.
X
Xif ( flag -- ) immediate compilation
X	Used in the form:
X		<flag> if <true-part> else <false-part> then 
X		<flag> if <true-part> then
X	If "flag" is true, the words following "if" are executed
X	and the words following "else" until just after "then" are 
X	skipped. The "else" part is optional. If "flag" is false, 
X	words from "if" through "else", or from "if" through "then"
X	(when no "else" is used) are skipped. 
X
Xelse ( -- ) immediate compilation
X	Used in the form:
X		flag if <true-part> else <false-part> then
X	else executes after the true part following "if". "else" forces
X	execution to continue at just after "then". 
X
Xthen ( -- ) immediate compilation
X	Used in the form:
X		<flag> if <true-part> else <false-part> then
X		  or
X		<flag> if <true-part> then 
X	"then" is the point where execution continues after "else",
X	or "if" when no "else" is present.
X
Xcase ( value -- ) immediate compilation
X	Used in the form:
X		case <case-structure> endcase
X	to mark the beginning of a case structure which should contain
X	a one or several:
X		<case-value> of <case-part> endof
X	The code section after the last case value part will receive "value"
X	as a parameter thus a default behavior is easy implemented. But
X	the default section may only copy this value as "endcase" is an
X	implicit "drop".
X
Xof ( value -- ) immediate compilation
X	Used in the form:
X		<case-value> of <case-part) endof
X	within a case structure to define a value case.
X
Xendof ( -- ) immediate compilation
X	Used in the form:
X		<case-value> of <case-part) endof
X	to mark the end of a cast value structure.
X
Xendcase ( -- ) immediate compilation
X	Used in the form:
X		case <case-structure> endcase
X	to mark the end of a case structure.
X
Xbegin ( -- ) immediate compilation
X	Used in the form:
X		begin ... <flag> while ... repeat
X		  or
X		begin ... <flag> until
X		  or 
X		begin ... again
X	"begin" marks the start of a word sequence for repetitive 
X	execution. A "begin-while-repeat" loop will repeat until "flag" 
X	is false. "begin-until" loop will be repeated until "flag" is 
X	true and "begin-again" will repeat until "abort"-ed. The words 
X	after "until" and "repeat" will be executed when either loop 
X	is finished. 
X
Xuntil ( flag -- ) immediate compilation
X	Used in the form:
X		begin ... <flag> until
X	Marks the end of a "begin-until" loop which will terminate
X	based on "flag". If "flag" is true, the loop is terminated.
X	If "flag" is false, execution continues to just after the 
X	corresponding "begin". 
X
Xwhile ( flag -- ) immediate compilation
X	Used in the form:
X		begin ... <flag> while ... repeat
X	Selects conditional execution based on "flag". When "flag" 
X	is true, execution continues to just after the "while" through
X	to the "repeat" which then continues execution to just after the 
X	"begin". When "flag" is false, execution continues to just after
X	the "repeat", exiting the control structure. 
X
Xrepeat ( -- ) immediate compilation
X	Used in the form:
X		begin ... <flag> while ... repeat
X	At execution-time, "repeat" continues execution to just after
X	the corresponding "begin". 
X
Xagain ( -- ) immediate compilation
X	Used in the following form to compile an eternal loop:
X		begin ... again
X	The loop construct may only be left by an "abort" or an
X	"exit" word in the code part of the loop.
X
Xrecurse ( -- ) immediate compilation
X	Used within a definition to make a recursive call to the
X	current definition.
X
Xtail-recurse ( -- ) immediate compilation
X	Used within a definition to create a recursive call to the
X	current definition without saving return status. This is an
X	efficient way of generating iterative forms as tail recursive
X	calls may be performed any number of times within a definition
X	and corresponds to a branch to the beginning of the definition.
X
Xexit ( -- ) compilation
X	Compiled within a colon definition such that when executed, 
X	the colon definition returns control to the definition that 
X	passed control to it by returning control to the return point 
X	on the top of the return stack. An error condition exists if 
X	the top of the return stack does not contain a valid return
X	point. May not be used within a "do-loop" or "do-+loop" or
X	an "exception"-block.
X
Xexecute	( addr -- )
X	The word definition indicated by "addr" is executed. An
X	error condition exists if "addr" is not a compilation address.
X
Xbye ( -- )
X	Leaves the interaction level and exits to the outer support
X	system (if any).
X
X. ( n -- )
X	The absolute value of "n" is displayed in a free field format
X	with a leading minus sign if "n" is negative. 
X
Xu. ( u -- )
X	"u" is displayed as an unsigned number in a free-field format.
X
X." ( -- ) immediate compilation
X	Used in the form:
X		." output string"
X	Later execution will display the characters "output string" up 
X	to but but including the delimiter " (close-quote). The blank 
X	following the ." is not part of the "output string".
X
X.( ( -- ) immediate
X	Used in the form:
X		.( display comment)
X	The characters "display comment" up to but not including
X	the delimiter ")" (closing-parenthesis) are displayed. The
X	blank following .( is not part of the "display comment".
X	Recursive comments are allowed.
X
Xcr ( -- )
X	Emits ASCII characters carriage-return and line-feed.
X
Xemit ( x -- )
X	The least-significant 7-bit ASCII character is displayed.
X
Xtype ( addr +n -- )
X	"+n" characters are displayed from memory beginning with 
X	the character at "addr" and continuing through consecutive 
X	addresses. Nothing is displayed if "+n" is zero.
X
Xspace ( -- )
X	Display an ASCII space, i.e., emits an ASCII space character code.
X
Xspaces ( +n -- )
X	Displays "+n" ASCII spaces. Nothing is displayed if "+n" is zero.
X
Xkey ( -- x)
X	The next extended ASCII character received. All valid ASCII
X	characters can be received. Control characters are not processed
X	by the system for any editing purpose. Characters received by
X	"key" are not displayed.
X
Xexpect ( addr +n -- )
X	Receive characters and store each into memory. The transfer
X	begins at "addr" proceeding towards higher addresses one byte
X	per character until either a "return" is received or until "+n" 
X	characters have been transferred. No more than "+n" characters
X	will be stored. The "return" is not stored into memory. No 
X	characters are received or transferred if "+n" is zero. All 
X	characters actually received and stored into memory will be 
X	displayed, with "return" displaying as a space. 
X
Xspan ( -- addr)
X	The address of a variable containing the count of characters
X	actually received and stored by the last execution of "expect".
X
Xforth-83 ( -- )
X	Assures that a FORTH-83 Standard System is available.
X
Xquit ( -- )
X	Clears the return stack, sets interpret state, accepts new
X	input from the current input device, and begins text
X	interpretation. No messages is displayed. The text interpreter
X	allows casting of symbols using the vocabulary name in parenthesis
X	as a prefix. Example: "(string) +" may be used to specify that
X	the plus operator from the string vocabulary is to used. This
X	may occur even though this vocabulary is not in the context set.	
X
Xabort ( -- )
X	Clears the data stack and performs the function of "quit". 
X	No message is displayed.
X
Xabort" ( flag -- ) immediate compilation
X	Used in the form:
X		<flag> abort" abort message"
X	When later executed, if "flag" is true the "abort message"
X	delimited by " (close-quote), is displayed and then a system
X	dependent error abort sequence, including the function "abort", 
X	is performed. If "flag" is false, the flag is dropped and 
X	execution continues. The blank following abort" is not part of 
X	the "abort message". 
X
Xhere ( -- addr)
X	The address of the next available dictionary location.
X
Xpad ( -- addr)
X	The lower address of a scratch area used to hold data form
X	intermediate processing. The address or contents of PAD may
X	change and the data lost if the address of the next available 
X	dictionary location is changed. The minimum capacity of PAD is 
X	84 characters. 
X
Xtib ( -- addr)
X	The address of the text input buffer. This buffer is used to 
X	hold characters when the input stream is coming from the current
X	input device. The minimum capacity of TIB is 256 characters.
X
X>body ( addr1 -- addr2)
X	"addr2" is the parameter field address corresponding to
X	the compilation address "addr1".
X
X.name ( addr1 -- )
X	Given the compilation address "add1" of an entry prints the
X	name of the entry.
X
X#if ( flag -- ) immediate
X	Used in the following form to allow conditional compilation
X	and execution both within and outside definitions:
X		<flag> #if <true-part> #else <else-part> #then
X	or
X		<flag> #if <true-part> #then
X	The sections are executed or compiled according to the flag
X	and the current mode.
X
X#else ( -- ) immediate
X	Marks the beginning of a "else"-part of a conditional code
X	section.
X
X#then ( -- ) immediate
X	Marks the end of a conditional code section.
X
X#ifdef ( -- ) immediate
X	Used in the following form for testing if a symbol already 
X	is available:
X		#ifdef <name> <true-part> #else <false-part> #then
X	or
X		#ifdef <name> <true-part> #then
X	If <name> is available in the current search chain the true
X	section of code is executed or compiled according to mode
X	else the false section.
X		
X#ifundef ( -- ) immediate
X	Performs the same function as "#ifdef" but the true section is
X	executed if the symbol is not available in the current search
X	chain.
X
X#include ( -- ) 
X	Used in the following form to load source files:
X		#include <file name>
X	The file name is any string until a space character. If the
X	file has already been included the operation is ignored.
X
X#path ( -- )
X	Used in the following form to define a file search path:
X		#path <path name>
X	The input function, "#include", uses a set of path to 
X	allow shorter file names to be used. The initial set of 
X	paths are defined by the environment variable TILEPATH
X	and HOME.
X
X( ( -- ) immediate
X	Used in the form:
X		( comment string)
X	The characters enclosed by the delimiter ")" are considered
X	comments. Comments are not otherwise processed. The blank
X	following "(" is not part of the comment string. The number
X	of characters in the comment string may be from zero to the
X	number of characters remaining in the input stream up to the
X	closing parenthesis. 
X
X\ ( -- ) immediate
X	Used in the form:
X		\ comment string
X	Comment terminate by end of line (carriage return).
X
X, ( x -- )
X	Allocates space for "x" then store value at "here 4 -". 
X
Xallot ( w -- )
X	Allocated "w" bytes in the dictionary. The address to the 
X	next available dictionary location is updated accordingly.
X
Xdoes> ( -- ) immediate compilation
X	Defines the execution-time action of a word created by a 
X	high-level defining word. Used in the form:
X		: <defining> <create action> does> <run-time action> ;
X	and then
X		<defining> <name>
X	where <create action> is "create" or any user defined word
X	which executes "create".
X	Marks the termination of the defining part of the defining
X	word <defining> and then begins the definition of the run-time
X	action for words that will later be defined by <defining>. 
X	When <name> is later executed, the address of <name>'s parameter
X	field is placed on the stack and then the sequence of words
X	between "does>" and ";", <run-time action> are executed. 
X	Multi-levels of high-level definitions are possible, i.e., 
X	"create-does>" may be used multiple times within the 
X	<run-time action>. 
X
Ximmediate ( -- )
X	Marks the most recently created dictionary entry as a word 
X	which will be executed when encountered during compilation 
X	rather than compiled.
X
Xexecution ( -- )	
X	Marks the most recently created dictionary entry as a word 
X	which is only available in execution mode.
X	
Xcompilation ( -- )
X	Marks the most recently created dictionary entry as a word 
X	which is only available in compilation mode.
X	
Xprivate ( -- )
X	Marks the most recently created dictionary entry as a word
X	which is only available in the dictionary it is created in.
X	The word is not available when the dictionary is not current.
X
X[compile] ( -- ) immediate compilation 
X	Used in the form:
X		[compile] <name>
X	Forces compilation of the following word <name>. This allows
X	compilation of an immediate word when it would otherwise
X	have been executed. If <name> is not found an error message
X	is given.
X
X?compile ( -- ) compilation
X	Used as "compile" but considers the compilation state. If
X	compiling then performs the same action as "compile" else
X	does nothing.
X
Xcompile ( -- ) compilation
X	Typically used in the form:
X		: <name> ... compile <compiled> ... ;
X	When <name> is executed, the compilation address compiled for
X	<compiled> is compiled and not executed. <name> is typically
X	immediate and <compiled> is typically not immediate. 
X
Xstate ( -- addr)
X	The address of a variable containing the compilation state. 
X	True indicated compilation is occurring, false that text
X	interpretation is occurring. A Standard Program may not modify 
X	this variable and should instead use "[" and "]" to alter mode. 
X
Xcompiling ( -- state)
X	Returns the contents of the state variable as this variable 
X	should not be altered by other than system functions.
X
Xliteral	( n -- ) immediate compilation
X	Typically used in the form:
X		[ <value> ] literal
X	At execution time "n" will be left on the parameter stack.
X
X[ ( -- ) immediate
X	Sets interpret state. The text from the input stream is
X	subsequently interpreted. Typically usage see "literal". 
X
X] ( -- )
X	Sets compilation state. The text from the input stream
X	is subsequently compiled. 
X
Xword ( char -- addr)
X	Generates a counted string by non-destructively accepting
X	characters from the input stream until the delimiter character
X	code or a control character is encounter or the input stream 
X	is exhausted. Leading delimiters and control characters are
X	ignored. The entire character string is stored in memory
X	beginning at "addr" as a sequence of bytes. The string is
X	ended by a null character.
X
Xcontext ( -- addr)
X	Variable containing the set of vocabularies in the search chain.
X
Xcurrent ( -- addr)
X	Variable containing a pointer to the current vocabulary for
X	definitions.
X
Xlast ( -- addr)
X	Returns the compilation address of the latest defined entry
X	in the current vocabulary.
X
Xdefinitions ( -- )
X	The compilation vocabulary, "current", is changed to be the
X	same as the first vocabulary in the search order, "context".
X
Xonly ( -- )	
X	The compilation vocabulary, "current", is changed to be the
X	same as the first vocabulary in the search order, "context".
X	And all vocabularies except the first is removed from the 
X	search list.
X
Xrestore ( entry -- )
X	Restores "current" to the parameter entry. Any words defined
X	after "entry" are unlinked form the vocabulary. This is useful
X	for realizing lexical levels in forth. 
X
X' ( -- addr)
X	Used in the form:
X		' <name>
X	"addr" is the compilation address of <name>. Gives an error
X	message	if <name> is not found in the current active search order.
X	
X['] ( -- addr) immediate compilation
X	Used in the form:
X		['] <name>
X	Compiles the compilation address of <name> as a literal.
X	When the colon definition is later executed "addr" is left
X	on the stack. If <name> is not found an error message is
X	given.
X
Xlookup ( addr1 vocabulary -- addr2 n)
X	"addr1" is the address of a null-ended string which is to be
X	located in the "vocabulary" given as a parameter. If the word 
X	is not found, "addr2" is the string and "n" is false. If the
X	word is found, "addr2" is the compilation address and "n" is 
X	set to one of two non-zero values. If the word found has the
X	immediate attribute set, "n" is one. If the word is non-immediate, 
X	"n" is minus one. 
X
Xfind ( addr1 -- addr2 n)
X	"addr1" is the address of a null-ended string. The string 
X	contains a word name to located in the currently active
X	search order. If the word is not found, "addr2" is the
X	string and "n" is false. If the word is found, "addr2" is
X	the compilation address and "n" is set to one of two non-
X	zero values. If the word found has the immediate attribute 
X	set, "n" is one. If the word is non-immediate, n is minus
X	one (true). 
X
Xforget ( -- )
X	Used in the form:
X		forget <name>
X	If <name> is found in the compilation vocabulary, delete
X	<name> from the dictionary and all words added to the 
X	dictionary after <name> regardless of their vocabulary. 
X	Failure to find <name> is an error condition. An error
X	condition also exists if the compilation vocabulary is 
X	deleted.
X
Xwords ( -- ) immediate
X	Display the visible words in the current search chain.
X
Xentry ( parameter mode code name -- )
X	Creates a new entry in the current definitions vocabulary
X	with the given arguments. The entry becomes the "last" entry 
X	in the vocabulary.1
X
Xforward ( -- )
X	Used in the following form to define a symbol which will
X	be defined later:
X		forward <name>
X	If the symbol is executed it will indirectly execute "abort".
X	When the symbol is later defined the forwarded symbol is
X	directed to the newly created symbol.
X
X: ( -- )
X	A defining word executed in the form:
X		: <name> <forth-definition> ;
X	Create a word definition for <name> in the compilation vocabulary
X	and set compilation state. The text from the input stream is
X	subsequently compiled. <name> is called a "colon definition".
X
X; ( -- ) immediate compilation
X	Stops compilation of a colon definitions, sets interpret state.
X	Additional actions may be taken for local variables and argument
X	frames and an exception block.
X
Xcreate ( -- )
X	A defining word executed in the form:
X		create <name>
X	Create a dictionary entry for <name>. After <name> is created, 
X	the next available dictionary location is the first byte of 
X	<name>'s parameter field. When <name> is subsequently executed, 
X	the address of the first byte of <name>'s parameter field is 
X	left on the stack. "create" does not allocate space in <name>'s
X	parameter field.
X
Xvariable ( -- )
X	A defining word executed in the form:
X		variable <name>
X	A dictionary entry for <name> is created and four bytes are
X	allotted in its parameter field. This parameter field is to
X	be used for contents of the variable. The application is 
X	responsible for initializing the contents of the variable
X	which is created. When <name> is later executed, the address
X	of its parameter field is placed on the stack. 
X
Xconstant ( x -- )
X	A defining word executed in the form:
X		<value> constant <name>
X	Create a dictionary entry form <name> so that when <name> is 
X	later executed, "value" will be left on the stack. 
X
Xvocabulary ( -- )
X	A defining word executed in the from:
X		vocabulary <name>
X	A dictionary entry for <name> is created which specifies a
X	new ordered list of word definitions. Subsequent execution
X	of <name> replaces the first vocabulary in the search order 
X	with <name>. When <name> becomes the compilation vocabulary
X	new definitions will be appended to <name>'s list.
X	Demonstration of access of arguments passed to application.
X	Prints and executes an argument.
X
Xfield ( x -- )
X	Used in the form:
X		<offset> field <name>
X	When later <name> is used it will add the <offset> to the
X	top of the parameter stack.
X
Xarc ( -- n)
X	Returns the number of arguments passed for the environment.
X	The first argument is always the name of the application:
X	"forth" or the name of the start symbol.
X
Xargv ( n -- str)
X	Given an index returns the corresponding argument string.
X
XSEE ALSO
X	compiler(1), strings(1), queues(1), multi-tasking(1), memory(1)
X
XCOPYING
X	Copyright (C) 1989 Mikael R.K. Patel
X	Permission is granted to make and distribute verbatim copies
X	of this manual provided the copyright notice and this permission
X	notice are preserved on all copies.
X	Permission is granted to copy and distribute modified versions
X	of this manual under the conditions for verbatim copying, 
X	provided also that the section entitled "GNU General Public
X	License" is included exactly as in the original, and provided
X	that the entire resulting derived work is distributed under
X	the terms of a permission notice identical to this one.
X	Permission is granted to copy and distribute translations of
X	this manual into another language, under the above conditions
X	for modified versions, except that the section entitled "GNU
X	General Public License" may be included in a translation approved
X	by the author instead of in the original English.
X
XAUTHOR
X	Mikael R.K. Patel
X	Computer Aided Design Laboratory (CADLAB)
X	Department of Computer and Information Science
X	Linkoping University
X	S-581 83 LINKOPING
X	SWEDEN
X	Email: mip at ida.liu.se
END_OF_doc/kernel.doc
if test 37708 -ne `wc -c <doc/kernel.doc`; then
    echo shar: \"doc/kernel.doc\" unpacked with wrong size!
fi
# end of overwriting check
fi
echo shar: End of archive 6 \(of 7\).
cp /dev/null ark6isdone
MISSING=""
for I in 1 2 3 4 5 6 7 ; do
    if test ! -f ark${I}isdone ; then
	MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 7 archives.
    rm -f ark[1-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0



More information about the Alt.sources mailing list