FORTH(3X)

NAME
forth - forth-83 standard word set and tile forth kernel extensions

SYNOPSIS
forth

DESCRIPTION
The required word set of Forth-83 Standard excluding the block file word set and the tile forth kernel extensions. Each "word" (function, procedure, variable, etc) is described with its stack action, parameters, and return values and its code type. The format of the glossary list is:
<type> <name> ( <stack-effect> ) [ <mode> ]
The <stack-effect> describes the parameter and return values for the word in the following format:
( <arguments> -- <returns>)
The arguments and return values are given from left to right with the deepest stack value first. Symbolic names are often used for the arguments while the return values are often only described by data type.

The optional <mode> may define how the word is interpreted and when it is visible. The mode "immediate" marks the word as always executed. The mode "execution" reduces the words visibility to only execution, i.e., interpretation, mode. The mode "compilation" reduces the words visibility to only compilation mode. Last, the mode "private" marks the words as only visible in the vocabulary where it is defined. Additional modes are added by other tile forth extensions.

The list of required words in the Forth-83 Standard are described in the following sub-sections; "Stack Manipulation", "Memory Access", "Logic", "Arithmetic", "Comparison", "Numeric Conversion", "Control Structures", "Terminal Input/Output", "Interpreter", "Vocabulary", and "Defining Words". Each sub-section is sorted in ASCII order.

  Stack Manipulation
The Forth-83 Standard parameter and return stack manipulation functions. The tile forth kernel also supports the double number stack manipulation extension.

code -rot ( x y z -- z x y)
    The top three stack entries are rotated, forcing the top to become the deepest of the three.

code 2>r ( x y -- ) compilation
    Double "to-r". "x" and "y" are transferred to the return stack.

code 2drop ( x y -- )
    Double "drop". "x" and "y" are dropped.

code 2dup ( x1 y1 -- x1 y1 x1 y1)
    Double "dup". The first pair is copied.

code 2over (x1 y1 x2 y2 -- x1 y1 x2 y2 x1 y1)
    Double "over". The second pair is copied.

code 2r> ( -- x y) compilation
    Double "from-r". "x" and "y" are removed from the return stack and transferred to the data stack.

code 2rot ( x1 y1 x2 y2 x3 y3 -- x2 y2 x3 y3 x1 y1)
    Double "rot". The three pairs change places.

code 2swap ( x1 y1 x2 y2 -- x2 y2 x1 y1)
    Double "swap". The two pairs change places.

code >r ( x -- ) compilation
    Transfer "x" to the return stack.

code ?dup ( x -- [x x] or [x])
    Duplicate "x" if it is non-zero.

code depth ( -- +n)
    "+n" is the number of values contained in the data stack before "+n" was placed on the stack.

code drop ( x -- )
    "x" is removed from the stack.

code dup ( x -- x x)
    Duplicate "x".

code nip ( x y -- y)
    The second stack element "x" is removed.

code over ( x y -- x y x)
    A copy of "x" is made and moved over "y".

code pick ( +n -- x)
    "x" is a copy of the "+n"-th stack element, not counting "+n" itself. [0..depth-1]
    "0 pick" is equivalent to "dup"
    "1 pick" is equivalent to "over"

code r> ( -- x) compilation
    "x" is removed from the return stack and transferred to the data stack.

code r@ ( -- x) compilation
    "x" is a copy of the top of the return stack.

code roll ( +n -- )
    The "+n"-th stack value, not counting "+n" itself is first removed and then transferred to the top of the stack, moving the remaining values into the vacated position. The parameter should be in the interval: [0..depth-1].
    "0 roll" is a null operation
    "1 roll" is equivalent to "swap"
    "2 roll" is equivalent to "rot"

code rot ( x y z -- y z x)
    The top three stack entries are rotated, bringing the deepest to the top.

code swap ( x y -- y x)
    The top two stack entries are exchanged.

code tuck ( x y -- y x y)
    A copy of "y" is tucked under "x".

  Memory Access
The Forth-83 Standard memory and data access word set. The tile forth kernel extends the Forth-83 Standard with additional access functions for bit testing and bit field access. All access to memory is achieved through this word set.

code ! ( 32b addr -- )
    The postfix assignment operator. Store "32b" at "addr".

code +! ( x1 addr -- )
    "x1" is added to the value at "addr" using the convention for "+". The value at "addr" is assumed to be of size "cell". The sum replaces the original value at "addr".

code -match ( addr1 addr2 n -- bool)
    Matches the strings at address "addr1" and "addr2" of length "n" at the parameter addresses. Returns "false" if the strings are equal else "true". If the length "n" is zero the function will return "true".

code -trailing ( addr +n1 -- addr +n2)
    The character counter "+n1" of a text string beginning at "addr" is adjusted to exclude trailing spaces. If "+n1" is zero, then "+n2" is zero. If the entire string consists of spaces, then "+n2" is zero.

code <c@ ( addr -- 8b)
    "8b" is the value at "addr". The value is sign extended to the stack (cell) width.

code <f@ ( x p w -- y)
    Field access within a 32-bit quantity. "y" are the bits within "x" at position "p" and with a bit field width, "w". Bits positions are counted from right to left starting with zero. A field is defined from a position and upwards. The result "y" is sign extended.

code <w@ ( addr -- 16b)
    "16b" is the value at "addr". The value is sign extended to the stack (cell) width.

code @ ( addr -- 32b)
    "32b" is the value at "addr". Primary variable value access function.

code b! ( x y p -- z)
    Returns "z", the result of setting the bit at position "p" in "y" according to the value of "x". The bit is set to zero if "x" is zero else one.

code b@ ( x p -- y)
    Returns "true" if the bit a position "p" in "x" is one else "false".

code bounds ( addr1 n -- addr2 addr1)
    Converts vector address and size to boundary address suitable for a "do"-loop. "addr2" is the end address of the vector, i.e., the sum of "addr1" and "n".

code c! ( 8b addr -- )
    The postfix assignment operator. Store "8b" at "addr".

code c@ ( addr -- 8b)
    "8b" is the value at "addr". The value is not sign extended.

code cmove ( addr1 addr2 u -- )
    Move the "u" bytes at address "addr1" to "addr2". The byte at "addr1" is moved first, proceeding toward high memory. If "u" is zero nothing is moved.

code cmove> ( addr1 addr2 u -- )
    Move the "u" bytes at address "addr1" to "addr2". The move begins by moving the byte at ("addr1"+"u"-1) to ("addr2"+"u"-1) and proceeds to successively lower addresses for "u" bytes. If "u" is zero nothing is moved. Useful for sliding a string towards higher addresses.

code count ( addr1 -- addr2 +n)
    "addr2" is "addr1"+1 and "+n" is the length of the counted string at "addr1". The byte "addr1" contains the byte count "+n". Range of "+n" is [0..255].

code f! ( x y p w -- z)
    Inserts the value of "x" into "y" at the bit field which is defined by the position "p" and with the width "w". The value "x" is shifted and masked into "y" to form the result "z".

code f@ ( x p w -- y)
    Field access within a 32-bit quantity. "y" are the bits within "x" at position "p" and with a bit field width, "w". Bits positions are counted from right to left starting with zero. A field is defined from a position and upwards.

code fill ( addr u 8b -- )
    "u" bytes of memory beginning at "addr" are set to "8b". No action is taken is "u" is zero.

code w! ( 16b addr -- )
    The postfix assignment operator. Store "16b" at "addr".

code w@ ( addr -- 16b)
    "16b" is the value at "addr". The value is not sign extended.

  Logic
The Forth-83 Standard logic functions. The tile forth kernel extends the basic function set with boolean constants and a boolean conversion function. All logic functions manipulate their parameters bit-by-bit.

code and ( 32b1 32b2 -- 32b3)
    "32b3" is the bit-by-bit logical and of "32b1" and "32b2".

code boolean ( n -- bool)
    Maps numerical value to a boolean value, "true" or "false". Non-zero values are mapped to "true" and zero to "false".

constant false ( -- 0)
    The constant "false" represented by the value zero.

code or ( 32b1 32b2 -- 32b3)
    "32b3" is the bit-by-bit inclusive-or of "32b1" with "32b2".

code not ( 32b1 -- 32b2)
    "32b2" is the one's complements of "32b1".

constant true ( -- -1)
    The constant "true" represented by the value minus one.

code xor ( 32b1 32b2 -- 32b3)
    "32b3" is the bit-by-bit exclusive-or of "32b1" with "32b2".

  Arithmetic
The Forth-83 Standard arithmetic word set. The tile forth kernel extends the Forth-83 Standard with arithmetic functions for shifting and additional numeric constants. Double number width arithmetic function such as "d+" and "dnegate" are not implemented as tile forth is a 32-bit implementation. Arithmetic errors are caught by the tile forth kernel and passed to the application as signals. An exception block may be used to catch the signal.

code * ( w1 w2 -- w3)
    "w3" is the least-significant 32 bits of the arithmetic product of "w1" times and "w2".

code */ ( w1 w2 w3 -- w4)
    "w1" is first multiplied by "w2" producing an intermediate 32-bit result. "w4" is the floor of the quotient of the intermediate 32-bit result divided by the divisor "w3". The product of "w1" times "w2" is maintained as an intermediate 32-bit result for greater precision then the otherwise equivalent sequence: "w1 w2 * w3 /". An error condition results if the divisor is zero and an exception is raised.

code */mod ( w1 w2 w3 -- w4 w5)
    "w1" is first multiplied by "w2" producing an intermediate 32-bit result. "w4" is the remainder and "w5" is the floor of the quotient of the intermediate 32-bit result divided by the divisor "w3". A 32-bit intermediate product is used as for "*/". "w4" has the same sign as "w3" or is zero. An error condition results if the divisor is zero and an exception is raised.

code + ( w1 w2 -- w3)
    "w3" is the arithmetic sum of "w1" and "w2".

code - ( w1 w2 -- w3)
    "w3" is the result of subtracting "w2" from "w1".

constant -1 ( -- -1)
    Constant minus one.

constant -2 ( -- -2)
    Constant minus two.

constant -4 ( -- -4)
    Constant minus four.

code / ( w1 w2 -- w3)
    "w3" is the floor of the quotient of "w1" divided by the divisor "w2". An error condition results if the divisor is zero.

code /mod ( w1 w2 -- w3 w4)
    "w3" is the remainder and "w4" the floor of the quotient of "w1" divided by the divisor "w2". "w3" has the same sign as "w2" or is zero. An error condition results if the divisor is zero and an exception is raised.

constant 0 ( -- 0)
    Constant zero.

constant 1 ( -- 1)
    Constant one.

code 1+ ( w1 -- w2)
    "w2" is the result of adding one to "w1" according to the operation of "+".

code 1- ( w1 -- w2)
    "w2" is the result of subtracting one to "w1" according to the operation of "-".

constant 2 ( -- 2)
    Constant two.

code 2* ( n1 -- n2)
    "n2" is the result of arithmetically shifting "n1" left one bit. The sign is included in the shift and remains unchanged.

code 2+ ( w1 -- w2)
    "w2" is the result of adding two to "w1" according to the operation of "+".

code 2- ( w1 -- w2)
    "w2" is the result of subtracting two to "w1" according to the operation of "-".

code 2/ ( n1 -- n2)
    "n2" is the result of arithmetically shifting "n1" right one bit. The sign is included in the shift and remains unchanged.

constant 4 ( -- 4)
    Constant four.

code << ( n1 n2 -- n3)
    "n3" is the result of logically shifting "n1" left "n2" steps.

code >> ( n1 n2 -- n3)
    "n3" is the result of logically shifting "n1" right "n2" steps.

code abs ( n -- u)
    "u" is the absolute value of "n".

code max ( n1 n2 -- n3)
    "n3" is the greater of "n1" and "n2" according to the operation of ">".

code min ( n1 n2 -- n3)
    "n3" is the lesser of "n1" and "n2" according to the operation of "<".

code mod ( n1 n2 -- n3)
    "n3" is the remainder after dividing "n1" by divisor "n2". "n3" has the same sign as "n2" or is zero. An error condition results if the divisor is zero or if the quotient falls outside of the numerical range.

code negate ( n1 -- n2)
    "n2" is the two's complement of "n1", i.e., the difference of zero less "n1".

constant nil ( -- 0)
    Constant for a nil pointer.

code um* ( u1 u2 -- u3)
    "u3" is the unsigned product of "u1" times "u2". All values and arithmetic are unsigned.

code um/mod ( u1 u2 -- u3 u4)
    "u3" is the remainder and "u4" is the floor of the quotient after dividing "u1" by the divisor "u2". All values and arithmetic are unsigned. An error condition results if the divisor is zero or if the quotient lies outside the numerical range.

  Comparison
The Forth-83 Standard comparison word set. The tile forth kernel extends the standard with an integer range test function. The kernel does not implement double number comparison functions. Boolean values "true" and "false" are represented with "-1" and "0".

code 0< ( n -- bool)
    Returns "true" if "n" is less than zero (negative).

code 0= ( w -- bool)
    Returns "true" if "w" is zero.

code 0> ( n -- bool)
    Returns "true" if "n" is greater than zero.

code < ( n1 n2 -- bool)
    Returns "true" if "n1" is less than "n2".

code = ( w1 w2 -- bool)
    Returns "true" if "w1" is equal to "w2"

code > ( n1 n2 -- bool)
    Returns "true" if "n1" is greater than "n2"

code ?within ( value lower upper -- bool)
    Tests if the parameter "value" is within the range "lower" to "upper". Returns "true" if within the range else "false".

code u< ( u1 u2 -- bool)
    Returns "true" if "u1" is less than "u2".

  Numeric Conversion
The Forth-83 Standard numeric conversion functions. The tile forth kernel extends the standard with string to number converter, and general number literal recognition.

code # ( +d1 -- +d2 )
    The remainder of "+d1" divided by the value of "base" is converted to a ASCII character and appended to the output string toward lower memory addresses. "+d2" if the quotient and is maintained for further processing. Typically used between "<#" and "#>".

code #> ( x -- addr +n)
    Pictured numeric output conversion is ended dropping "x". "addr" is the address of the resulting output string. "+n" is the number of characters in the output string. "addr" and "+n" together are suitable for "type".

code #s ( +x -- 0)
    "+x" is converted appending each resultant character into the pictured numeric output string until the quotient is zero. A single zero is appended to the output string if the number was initially zero. Typically used between "<#" and "#>".

code <# ( x -- )
    Initialize pictured numeric output conversion. The words: "<# # #s hold sign #>" can be used to specify the conversion of a number into an ASCII text string stored in right-to-left order.

code ?number ( str -- [n true] or [str false]) recognizer
    Convert a string of character to a number using the current "base". If the conversion is not possible the string is returned with a "false" flag indicating that the conversion failed otherwise the conversion value, the number, and a "true" flag is returned.

variable base ( -- addr)
    The address of a variable containing the current numeric conversion radix.

code binary ( -- )
    Set the input-output numeric conversion "base" to 2.

code convert ( +d1 addr1 -- +d2 addr2)
    "+d2" is the result of converting the characters within the text beginning at "addr1"+1 into digits, using the value of "base", and accumulating each into "+d1" after multiplying "+d1" by the value of "base". Conversion continues until an inconvertible character is encountered. "addr2" is the location of the first inconvertible character.

code decimal ( -- )
    Set the input-output numeric conversion "base" to 10.

code hex ( -- )
    Set the input-output numeric conversion "base" to 16.

code hold ( char -- )
    "char" is inserted into a pictured numeric output string. Typically used between "<#" and "#>".

code octal ( -- )
    Set the input-output numeric conversion "base" to 8.

code sign ( n -- )
    If "n" is negative, an ASCII "-" (minus sign) is appended to the pictured numerical output string. Typically used between "<#" and "#>".

  Control Structures
The Forth-83 Standard control flow word set. The tile forth kernel extends the basic set of control structures with environment arguments access, conditional compilation, case structure, additional loop constructs, and recursion words.

code #else ( -- ) immediate
    Used in the following form:
    <flag> #if <true-part> #else <else-part> #then
    Marks the beginning of a "else"-part of a conditional code section.

code #if ( flag -- ) immediate
    Used in the following form:
    <flag> #if <true-part> [ #else <false-part> ] #then
    Marks the beginning of a conditional code section. The else section is optional.

code #ifdef ( -- ) immediate
    Used in the following form for testing if a symbol already is available:
    #ifdef <name> <true-part> [ #else <false-part> ] #then
    If <name> is available in the current search chain "context" the true section of code is executed or compiled according to mode else the optional false section.

code #ifundef ( -- ) immediate
    Used in the following form:
    #ifundef <name> <true-part> [ #else <false-part> ] #then
    Performs the same function as "#ifdef" but the true section is executed if the symbol is not available in the current search chain.

code #then ( -- ) immediate
    Used in the following form:
    <flag> #if <true-part> [ #else <false-part> ] #then
    Marks the end of a conditional code section.

code +loop ( n -- ) immediate compilation
    "n" is added to the loop index. If the new index was incremented across the boundary between limit-1 and limit then the loop is terminated and the loop control parameters are discarded. When the loop is not terminated, execution continues to just after the corresponding "do". "+loop" is not available outside a colon definition.

code ?do ( w1 w2 -- ) immediate compilation
    Used in the following forms:
    ?do ... { i | leave } ... loop
    or
    ?do ... { i | leave } ... +loop
    Begins a checked entry loop which terminates based on control parameters. The loop index begins at "w2", and terminates based on the limit "w1". See "loop" and "+loop" for details on how the loop is terminated. If "w1" and "w2" are equal the loop section is skipped.

code abort ( -- )
    Clears the data stack and performs the function of "quit". No message is displayed.

code abort" ( flag -- ) immediate compilation
    Used in the following form:
    <flag> abort" <abort-message> "
    When later executed, if "flag" is true the <abort-message> delimited by close quote, is displayed and then a system dependent error abort sequence, including the function "abort", is performed. If "flag" is false, the flag is dropped and execution continues. The blank following abort" is not part of the <abort-message>.

code again ( -- ) immediate compilation
    Used in the following form to compile an eternal loop:
    begin ... again
    The loop construct may only be left by an "abort" or an "exit" word in the code section of the loop.

code argc ( -- num)
    Returns the number of arguments passed from the environment. The first argument is always the name of the application: "forth" or the name of the start symbol.

code argv ( n -- str)
    Given an index returns the corresponding argument string. The "string" vocabulary words may be used for process an argument string.

code begin ( -- ) immediate compilation
    Used in the following forms:
    begin ... <flag> while ... repeat
    or
    begin ... <flag> until
    or
    begin ... again
    "begin" marks the start of a word sequence for repetitive execution. A "begin-while-repeat" loop will repeat until <flag> is false. "begin-until" loop will be repeated until <flag> is true and "begin-again" will repeat until "abort"-ed. The words after "until" and "repeat" will be executed when either loop is finished.

code bye ( -- )
    Leaves the interaction level and exits to the outer support system (if any).

code case ( value -- ) immediate compilation
    Used in the following form:
    case <case-structure> { <default-part> } endcase
    to mark the beginning of a case structure which should contain a one or several case statements:
    <case-value> of <case-part> endof
    The code section after the last case value part will receive "value" as a parameter thus a default behavior is easy implemented. The default section may only copy this value as "endcase" is an implicit "drop".

code do ( w1 w2 -- )	immediate compilation
    Used in the following forms:
    do ... { i | leave } ... loop
    or
    do ... { i | leave } ... +loop
    Begins a loop which terminates based on control parameters. The loop index begins at "w2", and terminates based on the limit "w1". See "loop" and "+loop" for details on how the loop is terminated. The loop is always executed at least once.

code else ( -- ) immediate compilation
    Used in the following form:
    <flag> if <true-part> else <false-part> then
    in a conditional structure to mark the beginning of the false section. This section is executed when the <flag> is "false". The true section is then skipped.

code endcase ( -- ) immediate compilation
    Used in the following form:
    case <case-structure> { <default-part> } endcase
    to mark the end of a case structure.

code endof ( -- ) immediate compilation
    Used in the following form:
    <case-value> of <case-part> endof
    to mark the end of a cast value structure.

code execute ( addr -- )
    The word definition indicated by "addr" is executed. An error condition exists if "addr" is not a compilation address.

code exit ( -- ) compilation
    Compiled within a colon definition such that when executed, the colon definition returns control to the definition that passed control to it by returning control to the return point on the top of the return stack. An error condition exists if the top of the return stack does not contain a valid return point. May not be used within a "do-loop" or "do-+loop" or an "exception"-block.

code i ( -- w) compilation
    "w" is a copy of the current loop index. May only be used in the form:
    do ... { i | leave } ... loop
    or
    do ... { i | leave } ... +loop
    "i" is not visible outside a colon definition, i.e., when text interpreting and should only be used within a loop-block.

code if ( flag -- ) immediate compilation
    Used in the following form:
    <flag> if <true-part> [ else <else-part> ] then
    If "flag" is true, the words following "if" are executed and the words following "else" until just after "then" are skipped. The "else" part is optional. If "flag" is false, words from "if" through "else", or from "if" through "then" (when no "else" is used) are skipped.

code j ( -- w) compilation
    "w" is a copy of the index of the next outer loop. May only be used within a nested "do-loop" or "do-+loop" in the form:
    do ... do ... { i | j | leave } ... loop ... loop
    "j" is not visible outside a colon definition, i.e., when text interpreting.

code leave ( -- ) compilation
    Transfers execution to just beyond the next "loop" or "+loop". The loop is terminated and the loop control parameters are discarded. May only be used in the following forms:
    do ... { i | leave } ... loop
    or
    do ... { i | leave } ... +loop
    "leave" may appear within other control structures which are nested within the "do-loop" structure. More than one "leave" may appear within a do-loop.

code loop ( -- ) immediate compilation
    Increments the "do-loop" index by one. If the new index was incremented across the boundary between limit-1 and limit the loop is terminated and the loop control parameters are discarded. When the loop is not terminated, execution continues to just after the corresponding "do".

code of ( value -- ) immediate compilation
    Used in the following form:
    <case-value> of <case-part> endof
    within a case structure to define a value case.

code quit ( -- )
    Clears the return stack, sets interpret state, accepts new input from the current input device, and begins text interpretation. No messages is displayed.

code recurse ( -- ) immediate compilation
    Used within a definition to make a recursive call to the current definition.

code repeat ( -- ) immediate compilation
    Used in the following form:
    begin ... <flag> while ... repeat
    At execution-time, "repeat" continues execution to just after the corresponding "begin".

code tail-recurse ( -- ) immediate compilation
    Used within a definition to create a recursive call to the current definition without saving return status. This is an efficient way of generating iterative forms as tail recursive calls may be performed any number of times within a definition and corresponds to a branch to the beginning of the definition.

code then ( -- ) immediate compilation
    Used in the following form:
    <flag> if <true-part> [ else <else-part> ] then
    Marks the end of a conditional statement "if-else-then".

code until ( flag -- ) immediate compilation
    Used in the following form:
    begin ... <flag> until
    Marks the end of a "begin-until" loop which will terminate based on "flag". If "flag" is true, the loop is terminated. If "flag" is false, execution continues to just after the corresponding "begin".

code while ( flag -- ) immediate compilation
    Used in the following form:
    begin ... <flag> while ... repeat
    Selects conditional execution based on "flag". When "flag" is true, execution continues to just after the "while" through to the "repeat" which then continues execution to just after the "begin". When "flag" is false, execution continues to just after the "repeat", exiting the control structure.

  Terminal Input/Output
The Forth-83 Standard terminal interaction functions. The tile forth kernel extends the basic set of input and output functions with field format output and access of the current input source file name and the current line number count.

code . ( n -- )
    The absolute value of "n" is displayed in a free field format with a leading minus sign if "n" is negative. A space is emit after the number.

code ." ( -- ) immediate compilation
    Used in the following form within a code definition:
    <output-string> "
    Later execution will display the characters <output-string> up to but but including the delimiter (close-quote). The blank following the "." " is not part of the <output-string> but the word separator.

code .( ( -- ) immediate
    Used in the following form:
    .( <output-comment> )
    The characters <output-comment> up to but not including the delimiter (closing-parenthesis) are displayed. The blank following ".(" is not part of the <output-comment>.

code .s ( -- )
    Displays the current parameter stack contents in the format:
    [ <depth> ] <bottom> \ ... \ <top>

code ascii ( -- char) immediate
    Used in the following form:
    ascii <character> ( -- char)
    to create a character literal.

code cr ( -- )
    Emits ASCII characters carriage-return and line-feed.

code emit ( x -- )
    The least-significant 7-bit ASCII character is displayed.

code expect ( addr +n -- )
    Receive characters and store each into memory. The transfer begins at "addr" proceeding towards higher addresses one byte per character until either a "return" is received or until "+n" characters have been transferred. No more than "+n" characters will be stored. The "return" is not stored into memory. No characters are received or transferred if "+n" is zero. All characters actually received and stored into memory will be displayed, with "return" displaying as a space. The actual number of characters received is stored in the variable "span".

code key ( -- x)
    The next extended ASCII character received. All valid ASCII characters can be received. Control characters are not processed by the system for any editing purpose. Characters received by "key" are displayed in tile forth due to interaction with the operating system.

code line ( -- +n)
    Returns the current number of lines received from the current input "source".

code r. ( n w -- )
    The absolute value of "n" is displayed in a field format of width "w" with a leading minus sign if "n" is negative.

code source ( -- str)
    Returns the name string of the fully path expanded current file name. "nil" is returned if the current source is the standard input device.

code space ( -- )
    Displays an ASCII space, i.e., emits an ASCII space character code.

code spaces ( +n -- )
    Displays "+n" ASCII spaces. Nothing is displayed if "+n" is zero.

variable span ( -- addr)
    The address of a variable containing the count of characters actually received and stored by the last execution of "expect".

code type ( addr +n -- )
    "+n" characters are displayed from memory beginning with the character at "addr" and continuing through consecutive addresses. Nothing is displayed if "+n" is zero.

code u. ( u -- )
    "u" is displayed as an unsigned number in a free-field format.

code u.r ( u w -- )
    "u" is displayed as an unsigned number in a field format with width "w".

  Interpreter
The Forth-83 Standard interpreter functions. The tile forth kernel extends the interpreter word set with functions for loading of source files, library directory paths and mode marking of vocabulary entries. The additional modes allow marking with concern to the interpreter state and visibility across vocabularies.

code #include ( -- )
    Used in the following form to load source files:
    #include <file-name>
    The <file-name> is any string until a white space character. The file is located using the current set of paths defined by the environment variables $TILEPATH, $PWD, and $HOME. If the file has already been included the operation is ignored. The kernel maintains a list of all loaded files with their fully expanded names.

code #path ( -- )
    Used in the following form to define a file search path:
    #path <path-name>
    The input function, "#include", uses a set of path to allow shorter file names to be used and support source code libraries. The initial set of paths are defined by the environment variables $PWD, $TILEPATH, and $HOME.

code ( ( -- ) immediate
    Used in the following form:
    ( <comment-string> )
    The characters enclosed by the delimiter ")" are considered comments. Comments are not otherwise processed. The blank following "(" is not part of the comment string. The number of characters in the comment string may be from zero to the number of characters remaining in the input stream up to the closing parenthesis.

code , ( x -- )
    Allocates space for "x" then store value at "here cell -".

code .name ( addr1 -- )
    Given the compilation address "addr1" of an entry prints the name of the entry.

code >body ( addr1 -- addr2)
    "addr2" is the parameter field address corresponding to the compilation address "addr1".

code ?compile ( -- ) compilation
    Used in the following form:
    ?compile <compiled-entry>
    to compile an entry at run-time. Considers the compilation state at run-time. If the state is compiling then performs the same action as "compile" else does nothing and the succeeding word is executed and not compiled.

code [ ( -- ) immediate
    Sets interpret (execution) state. The text from the input stream is subsequently interpreted. Typically usage see "literal".

code [compile] ( -- ) immediate compilation
    Used in the following form:
    [compile] <compiled-entry>
    Forces compilation of the succeeding word. This allows compilation of an "immediate" word when it would otherwise have been executed. If the entry is not found an error message is given.

code \ ( -- ) immediate
    Used in the following form:
    \ <comment-string>
    Comment terminate by end of line (carriage return).

code ] ( -- )
    Sets compilation state. The text from the input stream is subsequently compiled.

code allot ( w -- )
    Allocated "w" bytes from the dictionary. The address to the next available dictionary location is updated accordingly.

code align ( -- )
    Align dictionary pointer to nearest cell boundary.

code cell ( -- bytes)
    Returns the number of bytes per cell. Four bytes for a 32-bit Forth.

code cell+ ( n -- m)
    Returns the result, "m", of incrementing "n" by "cell".

code cells ( n -- m)
    Returns the given value, "n", in cells. The result of "n" times "cell".

code compilation ( -- )
    Used in the following form:
    : <name> ( ... ) ... <colon-definition> ... ; compilation
    Marks the most recently created dictionary entry as a word which is only available in compilation mode.

code compile ( -- ) compilation
    Typically used in the following form:
    : <name> ... compile <compiled-entry> ... ; immediate compilation
    When <name> is executed, the compilation address compiled for <compiled-entry> is compiled and not executed. <name> is typically "immediate" and "compilation", and <compiled-entry> is typically not an immediate word.

code compiling ( -- bool)
    Returns the contents of the state variable as this variable should not be altered by other than system functions.

code does> ( addr -- ) immediate compilation
    Defines the run-time action of a word created by a high-level defining word. Used in the following form:
    : <defining> ( ... )
    ... <create-definition> ...
    does> ( addr -- ...)
    ... <run-time-definition> ... ;
    and then
    <defining> <name> (...)
    where <create-definition> is "create" or any user defined word which executes "create", and allocated memory. Marks the termination of the defining part of the defining word <defining> and then begins the definition of the <run-time-definition> for words that will later be defined by <defining>. When <name> is later executed, the parameter field address, "addr", of <name> is pushed on the parameter stack and then the sequence of words between "does>" and ";", the <run-time-definition>, is executed. Multi-levels of high-level definitions are possible, i.e., "create-does>" may be used multiple times within the <run-time-definition>.

code execution ( -- )
    Used in the following form:
    : <name> ( ... ) ... <colon-definition> ... ; execution
    Marks the most recently created dictionary entry as a word which is only available in execution mode.

code here ( -- addr)
    The address of the next available dictionary location.

code immediate ( -- )
    Used in the following form:
    : <name> ( ... ) ... <colon-definition> ... ; immediate
    Marks the most recently created dictionary entry as a word which will be executed when encountered during compilation rather than compiled.

code interpret ( -- )
    The forth top-loop; scan, locates, compiles and interprets symbols. The top-loop may be left with the word "bye".

code literal ( n -- ) immediate compilation
    Typically used in the following form:
    [ <expression> ] literal
    At execution time "n" will be left on the parameter stack.

create pad ( -- addr)
    The lower address of a scratch area used to hold data form intermediate processing. The address or contents of "pad" may change and the data lost if the address of the next available dictionary location is changed. The minimum capacity of "pad" is minimum of 84 characters (bytes).

code private ( -- )
    Used in the following form:
    : <name> ( ... ) ... <colon-definition> ... ; private
    Marks the most recently created dictionary entry as a word which is only available in the dictionary it is created in. The word is not available when the dictionary is not the definitions vocabulary, "current".

code quit ( -- )
    Clears the parameter stack and performs the function of "interpret". Starts the forth interpreter and compiler.

code recognizer ( -- )
    Used in the following form:
    : <name> ( str -- [str false] or [x true]) ... <colon-definition> ... ; recognizer
    Marks the most recently created dictionary entry as a word which will perform the literal recognition function. Executed by "interpret" when an "entry" has not been found. The recognizer function for "forth" is "?number" and "?float" for "float".

variable state ( -- addr)
    The address of a variable containing the compilation state. True indicated compilation is occurring, false that text interpretation is occurring. A Standard Program may not modify this variable and should instead use "[" and "]" to alter mode.

create tib ( -- addr)
    The address of the text input buffer. This buffer is used to hold characters when the input stream is coming from the current input device. The minimum capacity of "tib" is 256 characters.

code word ( char -- addr)
    Generates a null-terminated string by non-destructively accepting characters from the input stream until the delimiter character code or a control character is encounter or the input stream is exhausted. Leading delimiters and control characters are ignored. The entire character string is stored in memory beginning at "addr" as a sequence of bytes.

  Vocabulary
The Forth-83 standard vocabulary management functions. The tile forth kernel extends the basic function set with primitive entry lookup and literal recognition. Each vocabulary may have a literal recognition function which is automatically applied by "interpret" when the entry lookup fails. This allows easy extension of the input syntax for literal symbols. For examples see the "float" and the "rationals" vocabularies and files.

code ' ( -- addr)
    Used in the form:
    ' <name> ( -- addr)
    "addr" is the compilation address of <name>. Gives an error message if <name> is not found in the current active search order, "context".

code ['] ( -- addr) immediate compilation
    Used in the form:
    ['] <name> ( -- addr)
    Compiles the compilation address of <name> as a literal. When the colon definition is later executed "addr" is left on the stack. If <name> is not found an error message is given.

set context ( -- addr)
    Variable containing the set of vocabularies in the search chain. The set is represented as a vector set in the tile forth kernel and may be manipulated with the functions from the "sets" extension.

variable current ( -- addr)
    Variable containing a pointer to the current vocabulary for definitions.

code definitions ( -- )
    The compilation vocabulary, "current", is changed to be the same as the first vocabulary in the search order, "context".

code find ( addr1 -- addr2 n)
    "addr1" is the address of a null-ended string. The string contains a word name to located in the currently active search order. If the word is not found, "addr2" is the string and "n" is false. If the word is found, "addr2" is the compilation address and "n" is set to one of two non- zero values. If the word found has the immediate attribute set, "n" is one. If the word is non-immediate, n is minus one (true).

code forget ( -- )
    Used in the form:
    forget <name> ( -- )
    If <name> is found in the compilation vocabulary, delete <name> from the dictionary and all words added to the dictionary after <name> regardless of their vocabulary. Failure to find <name> is an error condition. An error condition also exists if the compilation vocabulary is deleted.

vocabulary forth ( -- )
    The name of the primary vocabulary. Execution replaces the first vocabulary in the search order with "forth". "forth" is initially the compilation vocabulary and the first vocabulary in the search order. New definitions become part of the "forth" vocabulary until a different compilation vocabulary is established.

code forth-83 ( -- )
    Assures that a Forth-83 Standard System is available.

code last ( -- addr)
    Returns the compilation address of the latest defined entry in the current vocabulary.

code lookup ( addr1 vocabulary -- addr2 n)
    "addr1" is the address of a null-ended string which is to be located in the "vocabulary" given as a parameter. If the word is not found, "addr2" is the string and "n" is false. If the word is found, "addr2" is the compilation address and "n" is set to one of two non-zero values. If the word found has the immediate attribute set, "n" is one. If the word is non-immediate, "n" is minus one.

code only ( -- )
    The compilation vocabulary, "current", is changed to be the same as the first vocabulary in the search order, "context". And all vocabularies except the first is removed from the search list.

code recognize ( addr1 -- [addr1 false] or [addr2 true])
    "addr1" is the address of a null-ended string. The string is tested by each recognizer function in the currently active search order. If recognized the function will return the literal value in "addr2" and "true". In other cases the string is returned with "false". The recognizer functions for the "forth" and "float" vocabularies are "?number" and "?float".

code restore ( entry -- )
    Restores "current" to the parameter entry. Any words defined after "entry" are unlinked form the vocabulary. This is useful for realizing lexical levels in forth. The lookup function cache is also flushed. An "nil" parameter will flush the whole cache.

code seal ( -- )
    The first (top) vocabulary is removed from the set of search vocabularies, "context". This allows lexical levels using vocabularies.

code words ( -- ) immediate
    Display the visible words in the current search chain, "context".

  Defining Words
The Forth-83 standard defining functions. The tile forth kernel extends the Forth-83 Standard with additional functions for creating vocabulary entries, fields, and forward declaration.

code : ( -- )
    A defining word executed in the following form:
    : <name> ( ... ) ... <colon-definition> ... ;
    Create a word definition for <name> in the compilation vocabulary and set compilation state. The text from the input stream is subsequently compiled. <name> is called a "colon definition".

code ; ( -- ) immediate compilation
    Stops compilation of a colon definitions, sets interpret state. Additional actions may be taken for local variables and argument frames and an exception block.

code code ( addr -- )
    Used in the following form:
    <addr> code <name> ( ... )
    to create a kernel primitive which will execute code at the given address, "addr", when used. The "address" is assumed to be a pointer to a parameter-less procedure.

code constant ( value -- )
    A defining word executed in the following form:
    <value> constant <name> ( -- value)
    Create a dictionary entry form <name> so that when <name> is later executed, <value> will be left on the stack.

code create ( -- )
    A defining word executed in the following form:
    create <name> ( -- addr)
    Create a dictionary entry for <name>. After <name> is created, the next available dictionary location is the first byte of <name>'s parameter field. When <name> is subsequently executed, the address of the first byte of <name>'s parameter field is left on the stack. "create" does not allocate space in <name>'s parameter field. The dictionary location is always aligned before the entry is created.

code entry ( parameter mode code name -- )
    Creates a new entry in the current definitions vocabulary with the given arguments. The entry becomes the "last" entry in the vocabulary.

code field ( offset -- )
    Used in the following form:
    <offset> field <name> ( addr1 -- addr2)
    When later <name> is used it will add the <offset> to the top of the parameter stack.

code forward ( -- )
    Used in the following form to define a symbol which will be defined later:
    forward <name> ( ... )
    If the symbol is executed it will indirectly execute "abort". When the symbol is later defined the forwarded symbol is automatically redirected to the newly created symbol.

code variable ( -- )
    A defining word executed in the following form:
    variable <name> ( -- addr)
    A dictionary entry for <name> is created and four bytes are allocated in its parameter field. This parameter field is to be used for contents of the variable. The application is responsible for initializing the contents of the variable which is created. When <name> is later executed, the address of its parameter field is placed on the stack.

code vocabulary ( -- )
    A defining word executed in the following form :
    vocabulary <name> ( -- )
    A dictionary entry for <name> is created which specifies a new ordered list of word definitions. Subsequent execution of <name> replaces the first vocabulary in the search order with <name>. When <name> becomes the compilation vocabulary new definitions will be appended to <name>'s list.

INTERNALS
For the internal data structures of the tile forth kernel see the source files "internals.f83" and the manual file "internals". The C definition of the data structures may be found in the file "kernel.h".

SEE ALSO
tile(1), memory(3X), compiler(3X), locals(3X), exceptions(3X), float(3X), string(3X), queues(3X), multi-tasking(3X).

NOTE
The function lists are sorted in ASCII order. The type and mode of the entries are indicated together with their parameter stack effect.

COPYING
Copyright (C) 1990 Mikael R.K. Patel

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the original English.

AUTHOR
Mikael R.K. Patel
Computer Aided Design Laboratory (CADLAB)
Department of Computer and Information Science
Linkoping University
S-581 83 LINKOPING
SWEDEN
Email: mip@ida.liu.se