mip@massormetrix.ida.liu.se (Mikael Patel) (12/19/89)
#! /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@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@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