FORTH
Section: Miscellaneous Library Functions (3X)
Updated: September 17, 1990
Index
Return to Main Contents
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
reates a new en!
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- Stack Manipulation
-
- Memory Access
-
- Logic
-
- Arithmetic
-
- Comparison
-
- Numeric Conversion
-
- Control Structures
-
- Terminal Input/Output
-
- Interpreter
-
- Vocabulary
-
- Defining Words
-
- INTERNALS
-
- SEE ALSO
-
- NOTE
-
- COPYING
-
- AUTHOR
-
This document was created by
man2html,
using the manual pages.
Time: 14:00:07 GMT, November 05, 2024