The documentation of the glossary uses a methodology based on that used for the Forth-83 Standard document. As this is not a standard document, but is supposed to be a user manual, we have taken some liberties to make this manual easier to look at.
The glossary definitions are listed in the following order:-
, . : ; ! ? " ' ' ( ) [ ] { } $ + - * / ^ < = > % # & @ \ _ | ~ 0..9 A..Z
Forth word names are capitalised throughout, and are shown in bold in the text.
The stack parameters input to and output from a definition are described using the notation:-
before - after
where:
'before' means the stack parameters before execution
and
'after' means stack parameters after execution
In this notation, the top of the stack is to the right. Unless otherwise noted, all stack notations describe execution time. If it applies at compile time, the line is followed by: (compiling) .
Unless otherwise stated all references to numbers apply to 32-bit signed integers. The implied range of values is shown as {from..to}. The content of an address is shown by double braces, particularly for the contents of variables, e.g., BASE {2..72}. The following are the stack parameter abbreviations and types of numbers used throughout the glossary. These abbreviations may be suffixed with a digit to differentiate multiple parameters of the same type.
Abbrv |
type |
range |
field size (in bits) |
flag |
boolean |
0=false, other=true |
32 |
true |
boolean |
-1 (as a result) |
32 |
false |
boolean |
0 |
32 |
b |
bit |
{0..1} |
1 |
char |
character |
{0..127} |
7 |
8b |
8 bits |
not applicable |
8 |
16b |
16 bits |
not applicable |
16 |
n |
number |
{} |
32 |
+n |
+ve integer |
{} |
32 |
u |
unsigned |
{} |
32 |
w |
unspecified weighted number (n or u) |
{} |
32 |
addr |
address |
{} |
32 |
32b |
32 bits |
not applicable |
32 |
64b |
64 bits |
not applicable |
64 |
d |
double number |
{} |
64 |
+d |
+ve double number |
{} |
64 |
ud |
unsigned double number |
{} |
64 |
wd |
unspecified weighted double number (d or ud) |
{} |
64 |
f |
floating point number |
|
|
sys |
0, 1, or more system dependent entries |
not applicable |
not applicable |
Abbrv. type range & field size flag boolean 0=false, else=true 32 true boolean -1 (as a result) 32 false boolean 0 32 b bit {0..1} 1 char character {0..127} 7 8b 8 bits not applicable 8 16b 16 bits not applicable 16 n number {} 32 +n +ve int {} 32 u unsigned {} 32 w unspecified weighted number (n or u) {} 32 addr address {} 32 32b 32 bits not applicable 32 64b 64 bits not applicable 64 d double number {} 64 +d positive double number {} 64 ud unsigned double number {} 64 wd unspecified weighted double number (d or ud) {} 64 f floating point number sys 0, 1, or more system dependent entries not applicable
Any other symbol refers to an arbitrary signed 32-bit integer in the range {}, unless otherwise noted. Because of the use of two's complement arithmetic, the signed 32-bit number (n) -1 has the same bit representation as the unsigned number (u) 4,294,967,295. Both of these numbers are within the set of unspecified weighted numbers (w). On many occasions where the context is obvious, informal names are used to make the documentation easier to use.
An arbitrary Forth word accepted from the input stream. This notation refers to text from the input stream, not to values on the data stack.
A sequence of arbitrary characters accepted from the input stream until the first occurrence of the specified delimiter character. The delimiter is accepted from the input stream, but it is not one of the characters ccc and is therefore not otherwise processed. This notation refers to text from the input stream, not to values on the data stack. Unless noted otherwise, the number of characters accepted may be from 0 to 255.
The following markers may appear after a word's stack comment. These markers indicate certain features and peculiarities of the word.
C
The word may only be used during compilation.
I
The word is immediate. It will be executed even during
compilation, unless preceded by the word
[COMPILE]
.
This glossary details the cross compiler directives.
End Page. Causes
FROM
andFROM-FILE
to stop using the current page. Has the same effect as;S
in screen files.;P
The comment in a text file differs from the screen file version. The parenthesis comment works over multiple lines. The end of comment is marked by a white-space-delimited closing parenthesis, e.g.
... 2DUP ( save adr # for later ) INIT ... ... CLOBBER ( NOTE: use the operating system function here to shut off access ) ...
A multi-line comment provided for compatibility with other MPE systems. It functions in the same way as
((
with the exception that single parenthesis comments may be nested within double parenthesis comments.
Marks the end of a comment begun with
(
.
Marks the end of a comment begun with
((
.
See
IF(
.
See
IF(
.
Has the same function as
)ENDIF
.
An ANS word that returns true if the following word has been defined. Can be used in conjunction with
[IF]
etc. For example:[DEFINED] FOO 0= \ Is FOO defined? [IF] \ NO : FOO \ Define it ... ; [THEN]
See
[IF]
.
The ANS words
[IF]
[ELSE]
[THEN]
permit conditional compilation and interpretation. They are an analogue ofIF
ELSE
THEN
and are used in the forms:flag [IF] <if flag is true> [THEN] flag [IF] <if flag is true> [ELSE] <if flag is false> [THEN]If the flag is true the words after
[IF]
are interpreted or compiled, but if the flag is false the words after[ELSE]
are interpreted/compiled. The[ELSE]
clause is optional.
See
[IF]
.
Returns true if the following word has not been defined. Can be used in conjunction with
[IF]
etc. For example:[UNDEFINED] FOO \ Is FOO undefined? [IF] \ YES : FOO \ Define it ... ; [THEN]
[UNDEFINED]
is the opposite of the ANS word[DEFINED].
A defining word used to create a second symbol name for a word. Used in the form:
ALIAS name1 name2 ALIAS (EMIT) SEND-BYTEThis feature is useful where a package is written using one word name, and the required function can be provided by a word of a different name elsewhere in the system. In the example above the CFA of
(EMIT)
will be compiled as a reference toSEND-BYTE
.
Used to align CFAs onto even addresses (2-byte boundaries). Some processors require code to be aligned in this fashion.
Used to align CFAs onto 4-byte boundaries. Some processors , i.e. the ARM series, require code to be aligned in this fashion.
Used to align CFAs onto 4-byte boundaries minus 1.
Used to align CFAs onto 4-byte boundaries minus 2.
Used to align CFAs onto odd addresses (so that PFAs are on even ones). The link fields are still forced to an even address.
ALIGN-ODD
Used before
FROM
,DISPLAY
orCONTENTS
,ALL
will put the first and last page numbers on the stack so thatALL
the pages are specified. e.g.ALL DISPLAY MYFILE.FTH
Allots space in the current code page area of a ROM/RAM target.
CREATE AREA \ - addr ; returns pointer to ROM area 0100 ALLOT \ reserve space in ROM 55 AREA ! \ which can be filled in later 66 AREA 4+ !
Allots space in the current data page area of a ROM/RAM target. Its function is to allow uninitialised space to be reserved in RAM.
THERE CONSTANT POINTER \ pointer to RAM area 0100 ALLOT-RAM \ reserve space in RAM
A modifier used before
FROM
orFROM-FILE
or other text file words to describe a single page, for example to compile page 5 from the current text file use:5 ALONE FROM
This word is used in a ROM/RAM system to skip parts of memory that may be occupied by existing ROMS. Such a situation is sometimes found in domestic computers, or when modifying systems that use partial memory decoding.
n1 n2 n3 n4 BOUNDINGThe first parameter n1 declares the size of the EPROM in bytes.
Parameter n2 is a bit mask identifying which address lines select the EPROM. For example an 8k EPROM of size 02000 (hex) is controlled by address lines A15,14,13 and will have a mask value of 0E000 (hex).
Parameter n3 specifies how far before the end of the EPROM the compiler stops to ask the user whether it should step to the next EPROM. This limit is used to prevent the last word in an EPROM being compiled across an EPROM boundary. If the answer is no, the question will be repeated before each word is compiled until the answer is yes or the EPROM boundary is crossed. When the yes answer is given, the compiler steps to the start of the next EPROM, and repeats the question. If the answer is again yes, the complete EPROM is skipped. Note that specifying a value of say 0100 does not guarantee to reserve 0100 free bytes at the end of the EPROM, it only specifies at what point the compiler starts asking what needs to be done.
Parameter n4 specifies how many bytes are skipped at the start of each EPROM.
The example below is for an 8k byte EPROM such that the compiler starts checking 128 bytes (080h) before the end of the EPROM, and the first 256 bytes (0100h) are skipped at the start of each EPROM.
HEX 02000 0E000 080 0100 BOUNDING
Used to select the current code section as the destination for
HERE
,
etc. Also used withSECTION
when defining new memory sections.CDATA \ Make the current code section the destination for HERE etc. 0 , 1 , 2 , \ Lay some values in the current code section IDATA \ Switch to the current initialised data section for HERE etc.
Direct the symbol table log output to the screen. The default output device. If required, this directive has to be used before the command
CROSS-COMPILE
.CON:
Displays the `contents' line (the top line) of each page in the specified range, using the current text file.
This word tells the system to start cross compiling. Until this point the compiler is a conventional Forth system with an application (the cross compiler) loaded but not running. At this stage extensions and assembler macros can be loaded. After
CROSS-COMPILE
has executed the compiler 'pulls down the shutters' to seal itself off, and then treats all code as target code and compiler directives.CROSS-COMPILE
Describes to the cross-compiler the type of emulator that is being used. Eprom types are:
e2716 e2732 e2764l e2764h e2764 e27128 e27256 e27512 e27010 e27020 e27040 e27080Bus width is either
8BIT
16BIT
or32BIT
. Also seeIN-EMULATOR
.
Display a listing of the current file, in the range of pages specified.
Creates a compile-time equate of value n. When the equate is referred to in the target code the value assigned to the equate is used as a literal. An equate only exists during the run-time of the cross compiler. Equates may be redefined like macro-assembler set-symbols. Equates may be used wherever numbers may be used, they are just a means of naming a number.
HEX 0FF80 EQU IO-PORT
The following words are generated with headers containing up to 31 characters, provided that the directive
NO-HEADS
has not been used.EXTERNAL
Direct the symbol table log output to the file <filename>. If required, this directive has to be used before the command
CROSS-COMPILE
.FILE: SYMBOLS.LOG
This word stops the cross compiler. A cleaning-up operation is performed, final reports issued, the output file or EPROM emulator closed, and finally the compiler exits to host/target/umbilical mode.
FINIS
Get text input from a range of pages in the current file. The first and last pages to be used are supplied on the stack. Files can be nested 16 deep; that is files can include input from other files.
FROM
is likeTHRU
orTHRU-USING
with screen files, e.g.4 10 FROM
Get text input from a range of pages in the file <file-name> typed after
FROM-FILE
. The first and last pages to be used are supplied on the stack. Files can be nested; that is files can include input from other files.FROM-FILE
is likeTHRU
orTHRU-USING
, e.g.4 10 FROM-FILE MYFILE.FTH
Returns true if the target is a Harvard architecture type processor.
An immediate equate that returns false if the
NO-HEADS
directive has been used. The function of this equate is to return a value for conditional compilation of the interpreter and compiler layers if heads are needed, for example:HEADS? IF( ALL FROM-FILE INTERACTIVE )ENDIF
Used after
TARGET-ONLY
to allow defining words to be handled again. Some special cases of defining words cannot be handled by the cross compiler, but are required for target execution.TARGET-ONLY
andHOST&TARGET
handle this situation.HOST&TARGET
Temporarily turns off the cross compiler so that the following code can be compiled into the cross compiler itself. Cross compilation is restarted by
TARGET-COMPILATION
.HOST-COMPILATION ....... TARGET-COMPILATION
Not really a directive, rather an auxiliary version of
:
.I:
is used instead of:
to create an immediate word that will exist in, and can be executed by, the cross compiler in the same way that defining words are handled. The same rules as for defining words apply to words created byI:
.I: <name> ...... ; IMMEDIATENote that
IMMEDIATE
only affects the target code,I:
is needed to enable the analogue to be built into the cross compiler.
Used to select the current initialised data section as the destination for
HERE
,
etc. Also used withSECTION
when defining new memory sections.IDATA \ Make the current initialised data section the destination for HERE etc. 0 , 1 , 2 , \ Lay some values in the current initialised data section CDATA \ Switch to the current code section for HERE etc.
The words
IF(
)ELSE(
)ENDIF
permit conditional compilation and interpretation. They are an analogue ofIF
ELSE
ENDIF
and are used in the forms:flag IF( <if flag is true> )ENDIF flag IF( <if flag is true> )ELSE( <if flag is false> )ENDIFIf the flag is true the words after
IF(
are interpreted or compiled, but if the flag is false the words after)ELSE(
are interpreted/compiled. The)ELSE(
clause is optional. Note that the ANS words[IF]
[ELSE]
[THEN]
have the same functionality and should be used in preference.
The code generated for the current section is redirected into an EPROM emulator. The address addr is the start of the image within the emulator. e.g.
$2000 IN-EMULATORwill send the current section to your emulator, starting at offset 2000h. This directive should be used immediately after defining the section to be redirected:
$2000 $8000 CDATA SECTION PROG $2000 IN-EMULATOR $0000 $1FFF IDATA SECTION PROGI
This directive causes the following words to be generated without headers. The cross compiler still knows they are there, but they will not be visible to the interpreter on the target system.
INTERNAL
Creates a label with the address returned by
HERE
, i.e. the current location in the dictionary. Normally only used during interpretation and assembly, but can be used during compilation if surrounded by[
and]
.L: DATA-SLOT 0 , : <word> ...... [ L: INSIDE-WORD ] ...... ;
Used during interpretation to create a label at an arbitrary location to satisfy a forward reference from a code definition or code fragment.
THERE LABEL MY-DATA
The contents of screen n of the current screen file are compiled, e.g.
10 LOAD
The contents of screen n of the given screen file are compiled. If no extension is given, the compiler will add the extension '.SCR', e.g.
10 LOAD-USING A:\ROM-IO
Generate a full symbol table log.
LOG
Used to make your application a turnkey or autostarting system. The word <name> is the name of your application word that you want to be run at start-up. For example,
MAKE-TURNKEY MY-APP
Disables generation of heads, overriding
EXTERNAL
andTARGET-WIDTH
completely. This directive can be used when the application is complete to remove ALL heads from the system without having to go through the source code removing all occurrences ofEXTERNAL
andTARGET-WIDTH
.NO-HEADS
Generate a reduced symbol table log.
NO-LOG
A modifier used before
FROM
orFROM-FILE
or other text file words to use the text from a specified page to the end, for example to compile page 5 to the end from the current text file use:5 ONWARDS FROM
A directive used to set the dictionary pointer to the given address.
HEX 2080 ORG
Direct the cross-compiler log output to the printer. If required, this directive has to be used before the command
CROSS-COMPILE
.PRN:
Please Turn Over. This word causes
FROM
andFROM-FILE
to stop using the current page and to start on the next. (The same effect as -> in screen files.)PTO
Continue cross compilation from the position saved under the given file name. The cross compiler must use files which have been generated using the directive
SUSPEND
during an earlier cross compilation.
Continue cross compilation from the position saved under the given file name. The cross compiler must use files which have been generated using the directive
SUSPEND
during an earlier cross compilation.
Creates a memory section based on the start and end addresses supplied. The type must be either
CDATA
IDATA
orUDATA
to indicate whether the section is for code, initialised data, or uninitialised data respectively. Execution of <name> makes it the current section of its type, and also the current section in use.$0000 $7FFF CDATA SECTION PROG $8000 $CFFF IDATA SECTION PROGI $D000 $FFFF UDATA SECTION PROGU PROG PROGI PROGU CDATA \ Set up default sections and use the code section for HERE etc.The sections are saved to disk as <name>.IMG
Stop the present cross compilation, saving cross compiler information to disc under the given filename, the cross compiler then returning to host/target mode. Note that the file name should not include an extension, the cross compiler supplies its own. Either
RESTART
orRESUME
is used to resume cross compilation later.SUSPEND KERNEL
Re-enable cross compilation after it has been turned off by
HOST-COMPILATION
.
Sets the maximum number of characters in the name field to be n. A maximum of 31 characters is imposed by the compiler.
7 TARGET-WIDTH
The contents of screens n1 to n2 inclusive of the current screen file are compiled, e.g.
DECIMAL 7 23 THRUIt is good practice to define the number base just before
LOAD
orTHRU
as people sometimes forget to restore the base at the end of a screen, or it might be house policy only to define the base where it matters. In this instance it does.
The contents of screens n1 to n2 of the given screen file are compiled. If no extension is given, the compiler will add the extension '.SCR'.
Used to select the current uninitialised data section as the destination for
HERE
,
etc. Also used withSECTION
when defining new memory sections.UDATA \ Make the current uninitialised data section the destination for HERE etc. 0 , 1 , 2 , \ Lay some values in the current uninitialised data section CDATA \ Switch to the current code section for HERE etc.
Set the default text file you wish to
USE
(like "USING
xxx.scr" for screen files). The file defaults to NUL.FTH.USE TEXTFILE.FTH
The words are listed here in ASCII alphabetical order, with the standard pronunciation of the word under the name. The stack comments show the execution point as "-" with the parameters to the left being the input parameters, and those to the right are the results left (if any) by the word's execution. The top of the stack is to the right of the lists. The indicator I indicates that the word is immediate.
Note: Not all the words in this glossary exist in the Umbilical Forth target.
A thirty-two bit integer is stored at the given address.
A word used by compiling and structure words. The stack pointer is saved in user variable
CSP
.
The remainder of +d1 divided by the value of
BASE
is converted to an ASCII character and appended to the output string toward lower memory addresses. +d2 is the quotient and is maintained for further processing. Typically used between <# and #>.
Pictured numeric output conversion is ended dropping 64b. 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
.
Takes n words from the stack and compiles them as literals, n1 first nn last. If no words are to be compiled, n may be zero. This word is used with
NUMBER?
as part of a consistent numeric conversion system.
+d1 is converted appending each resultant character into the pictured numeric output string until the quotient (see:
#
) is zero. +d2 is zero. A single zero is added to the output string if the number was initially zero. Typically used between<#
and#>
.
Use in the form:
' cccccSearches the dictionary using the normal search order, returning the compilation address (cfa) of the word. If the word is not found an error message is given.
use in the form:
"" <text>"Compiles text into the dictionary as a string with a count byte, and when the word containing "" executes later, the address of the string's count byte is returned.
Compiles the string following in the input stream into the dictionary as a counted string (count byte + text). Use in the form:
", string"The space before the string, and the trailing double quotes are not compiled.
Used in the form:
( ccc )The characters ccc, delimited by ) (closing parenthesis), are considered comments. Comments are not otherwise processed. The blank following ( is not part of ccc. ( may be freely used while interpreting or compiling. The number of characters in ccc may be from zero to the number of characters remaining in the input stream up to the closing parenthesis.
W3 is the least-significant 32 bits of the arithmetic product of w1 times w2.
n1 is first multiplied by n2 producing an intermediate 64-bit result. n4 is the quotient of the intermediate 64-bit result divided by the divisor n3. The product of n1 times n2 is maintained as an intermediate 64-bit result for greater precision than the otherwise equivalent sequence: n1 n2 * n3 / . An error condition results if the divisor is zero or if the quotient falls outside the range {}.
n1 is first multiplied by n2 producing an intermediate 64-bit result. n4 is the remainder and n5 is the quotient of the intermediate 64-bit result divided by the divisor n3. A 64-bit intermediate product is used as for */ . n4 has the same sign as n3 or is zero. An error condition results if the divisor is zero or if the quotient falls outside of the range {}.
w3 is the arithmetic sum of w1 plus w2
w1 is added to the value at addr using the convention for +. This sum replaces the original value at addr.
n is added to the loop index. If the new index was incremented across the boundary between limit-1 and limit the loop is terminated and loop control parameters are discarded. When the loop is not terminated, execution continues to just after the corresponding
DO
. Sys is balanced with correspondingDO
.
ALLOT
space for 32b then store 32b atHERE
4
-. This is the basic word used to compile 32-bit data into the dictionary. It places the data at the end of the dictionary and adds four to the dictionary pointer. The byte equivalent is calledC
, and the 16-bit equivalent isW,
w3 is the result of subtracting w2 from w1
Continues interpretation/compilation from the next screen. Only valid when interpreting/compiling from a screen file.
A constant
Saves the top of the stack under the next two items. Equivalent to:
ROT ROT
The character count +n1 of a text string beginning at addr is adjusted to exclude trailing spaces. If +n1 is zero, then +n2 is also zero. If the entire string consists of spaces, then +n2 is zero.
The absolute value of n is displayed in a free field format with a leading minus sign if n is negative.
Used in the form:
." ccc"Later execution will display the characters ccc up to but not including the delimiting " (close-quote). The first blank following ." is not part of ccc.
An equivalent of
."
to be used when interpreting, or for immediate display from within compilation, as."
is intended by the standard to be used within a colon definition to compile a string for later execution. Use in the form:.( string)
Prints n1 as an unsigned number in a format of two hex digits followed by a space. The current value of BASE is unaffected.
Given the name field address of a word, its name is displayed.
The number n1 is printed right aligned in a field of width n2 without a trailing space.
The contents of the stack are printed out, leaving the contents of the stack unchanged.
The value of n1 is displayed unsigned as four hex digits and a space. The current value of
BASE
is unaffected.
n3 is the quotient of n1 divided by the divisor n2. An error condition results if the divisor is zero or if the quotient falls outside the range {}.
n3 is the remainder and n4 the quotient of n1 divided by the 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 range {}.
Steps a specified distance through a string. Often used by text scanning operators, and is then followed by
SKIP
orSCAN
. SeeSKIP
SCAN
WORD
The numbers 0..4 occur so often that it is more economical to define them as constants.
The flag is true if n is less than zero (negative).
The flag is true if n is non-zero.
flag is true if w is zero.
flag is true if n is greater then zero.
w2 is the result of adding one to w1 according to the operation of +.
w2 is the result of subtracting one from w1 according to the operation of -.
The double number d1 is stored at addr. Forth stores double precision numbers with the most significant of the two words on the top of the stack. The word
2!
preserves the memory order so that the number configuration in memory is the same as on the stack. See2@
.
w2 is the result of adding two to w1 according to the operation of +. This operation is performed so often (like
1+
1-
and2-
) that it is worth having fast machine code routines.
w2 is the result of subtracting two from w1 according to the operation of -.
The double number at addr is returned to the stack. Forth stores double precision numbers with the most significant of the two words on the top of the stack. The double number memory operators preserve the memory order so that the number configuration in memory is the same as on the stack. See
2!
A fast machine code multiply by 2.
A fast machine code divide by two. Uses floored division.
The top two items on the stack are removed.
The top two items on the stack are duplicated.
Copies the second pair of words to the top of the stack.
The top two pairs of items on the stack are interchanged.
w2 is the result of adding four to w1 according to the operation of +. This operation is performed so often (like
1+
1-
and2-
) that it is worth having fast machine code routines.
w2 is the result of subtracting four from w1 according to the operation of -.
A defining word executed in the form:
: <name> ... ;Create a word definition for <name> in the compilation vocabulary and set Compilation State. The search order is changed so that the first vocabulary in the search order is replaced by the compilation vocabulary. The compilation vocabulary is unchanged.
The text from the input stream is subsequently compiled. <name> is called a "colon definition". The newly created word definition for <name> cannot be found in the dictionary until the corresponding
;
or;CODE
is successfully processed.An error condition exists if a word is not found and cannot be converted to a number or if, during compilation from mass storage, the input stream is exhausted before encountering
;
or;CODE
. sys is balanced by its corresponding;
.
Stops the compilation of a colon definition, allows the <name> of this colon definition to be found in the dictionary, sets interpret state and compiles
;S
. sys is balanced by its corresponding:
.
Used in creating a defining word.
;CODE
indicates the run-time part of the code is in assembler. For example:: Variable \ - ; [child] - addr CREATE HERE 4+ , \ save current address 0 , \ initialise variable ;CODE d7 -(a7) move, 6 d(a0) d7 move, NEXT, END-CODE
flag is true if n1 is less than n2
The flag is true if n1 is less than or equal to n2.
The flag is true if n1 is not equal to n2.
Initialise pictured numeric output conversion. The words:
#
#S
HOLD
SIGN
can be used to specify the conversion of a double number into ASCII text string stored in right-to-left order. See also#>
Marks the entry point of a backward jump, which will later be resolved by
<RESOLVE
.
Resolves a backward jump whose destination was earlier marked by
<MARK
flag is true if w1 is equal to w2
flag is true if n1 is greater than n2
The flag is true if n1 is greater than or equal to n2.
Converts a compilation address of a word (in this case, the address of the cfa) to the parameter field address.
The address of a variable that contains the present character offset within the current input stream buffer. See:
WORD
BLK
Marks the start of a forward branch which will be later resolved by
>RESOLVE
Converts a word's compilation address to its name field address.
Transfers 32b to the return stack. The return stack is a handy place to use for storing data temporarily while other data stack operations take place.
Resolves the branch address of a forward branch previously marked by
>MARK
Displays the contents of the address.
Consumes a flag and branches to the address given in-line after
?BRANCH
if the flag is true. SeeBRANCH
Causes the error handler to operate if not compiling
Causes the error handler to operate if the stack is unbalanced after last
!CSP
If the current task's event flag is set, the flag is reset and the event handler is executed.
Causes the error handler to operate if not interpreting
Causes the error handler to operate if not loading
Causes the error handler to operate if the stack is out of limits.
If n is negative, d1 is negated, otherwise it is left alone.
Used in the forms:
?DO ... LOOP ?DO ... +LOOPBegins a loop that 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 will not execute if the start and end limits are the same. For example the words inside the loop formed by:w DUP ?DO ... LOOPwill not be executed. See
DO
Duplicate 32b if it is non-zero. This word is very useful when testing error conditions. Often zero is returned for successful completion, a non-zero value being an error code.
If flag is true error message n is displayed. When loading, the error message is taken n lines from line 0 of screen 0 in the current error file.
If the flag is true (non-zero), the current
DO
...LOOP
structure is terminated immediately, execution resumed after theLOOP
or+LOOP
.
If n2 is negative, n1 is negated to give n3, otherwise n3 is n1.
An error condition is reported if n1 is not equal to n2.
32b is the value at addr.
Clear the stacks and enter the Execution State. Return control to the operator via
QUIT
, printing an appropriate message. In this implementationABORT
callsQUIT
. A sealed application will usually replaceQUIT
with a word containing the endless loop that forms the application.
Used in the form:
ABORT" string"If the flag is true the following string is displayed, and
ABORT
then executed.
Leave the absolute value of n.
Initialises and starts the given task number. Task 0 is Forth itself and was activated when Forth started. Note that
ACTIVATE
causes the task to start from the very beginning. If the task was halted, and execution should resume where it left off, useRESTART
instead.
Used in a colon definition in the form:
BEGIN ... AGAINAt run-time,
AGAIN
forces execution to resume at the correspondingBEGIN
. There is no effect on the stack. This is an endless loop unless an exit is forced by other means. At compile time,AGAIN
forces the compilation ofBRANCH
, followed by the address (addr) of the word after the correspondingBEGIN
. The value n is used for compile time error checking.
In cross compiler: Forces the parameter field addresses (PFA) to be on even byte boundaries
In target: Forces
HERE
to an even boundary.
Forces address2 to an even boundary, by adding 1 if necessary.
Reserves n bytes in the dictionary, from the current location. It adds the signed n to the current value of
DP
.
Reserves n bytes of RAM from the current RAM pointer given by
THERE
when used by the compiler and byHERE
when used by the target.
Room is made for another vocabulary to be added to the start of the vocabulary search list. Space is made by duplicating the top entry. This duplicate entry will be overwritten by the new vocabulary when it is executed. If the order is just:
FORTH ROOTthen after executing
ALSO
it will be:FORTH FORTH ROOTand after executing another vocabulary name (say
TOOLS
) it will become:TOOLS FORTH ROOT
Leaves the bitwise logical and of w1 and w2 as w3.
use in the form:
ASCII AUsed to generate the value of the character entered. The example above will return the code for the letter A. If
ASCII
is used in a colon definition the value of the character is compiled as a literal that is returned when the word is executed.
Used to assign the action for a deferred word, interrupt, or timer. Used in the form:
ASSIGN action-word TO-DO wordSee
TO-DO
The address of a user variable containing the current numeric conversion radix. {{2..72}}
Used in the forms:
BEGIN ... flag UNTIL BEGIN ... AGAIN BEGIN ... flag WHILE ... REPEAT
BEGIN
marks the start of a word sequence for repetitive execution. ABEGIN
...UNTIL
loop will be repeated until flag is true, aBEGIN
...AGAIN
loop executes forever unless otherwise left, and aBEGIN
...WHILE
...REPEAT
loop will be repeated until flag is false. The words afterUNTIL
orREPEAT
will be executed when either loop is finished.
Switches the current number conversion base to two, by setting user variable
BASE
to two.
A constant that returns the ASCII code for a space character.
Fills count bytes starting at addr with space characters.
The address of a user variable containing the number of the mass storage block being interpreted as the input stream. If the value of
BLK
is zero the input stream is taken from the text input buffer. See:TIB
addr is the address of the assigned buffer of the first byte of block u. If the block occupying that buffer is not block u and has been
UPDATE
d it is transferred to mass storage before assigning the buffer. If block u is not already in memory, it is transferred from mass storage into an assigned block buffer. A block may not be assigned to more than one buffer. If u is not an available block number, an error condition exists. Only data within the last buffer referenced byBLOCK
orBUFFER
is valid.
Converts a word's parameter field address to its compilation address (cfa).
Converts an address and length into the end-address+1 and start-address, suitable for use with
DO
...LOOP
.BOUNDS
is designed specifically for this purpose.
The Forth goto instruction, normally only used by structure words. Branches to an address given in-line.
Performs a destructive backspace operation if the variable OUT is non-zero. The destructive backspace is performed by the phrase:
8 EMIT SPACE 8 EMIT
The least-significant 8 bits of 32b are stored into the byte at addr.
8b is the contents of the byte at addr.
Compiles a byte into the next available dictionary location, and advances the dictionary pointer by one. The basic word for compiling byte wide data into the dictionary. See
,
W,
Returns the number of characters per line. Conventionally 64 even on 80 character terminals.
The word used to mark the start of the
CASE
....OF
....ENDOF
....ENDCASE
structure. For more details see the tutorial section on control structures.
Add the size in address units of a cell to addr1, giving addr2.
n2 is the size in address units of n1 cells.
Clears the event run flag for the current task. This is bit 4 in the task status byte.
Move u bytes beginning at address addr1 to addr2. The byte at addr2 is moved first, proceeding towards high memory. If u is zero nothing is moved. See
CMOVE>
MOVE
Move u bytes beginning at address addr1 to addr2. The bytes in high memory are moved first. If u is zero nothing is moved. This word is provided so that blocks of memory can be moved if overlapping. See
CMOVE
MOVE
Restarts the Forth system as if from scratch. Stacks are reset, the dictionary is cleared out, and
ABORT
is executed.
Typically used in the form:
: <name> ... COMPILE <namex> ... ;When <name> is executed, the compilation address compiled for <namex> is compiled and not executed. <name> is typically immediate and <namex> is typically not immediate. Most often used to build new compiling or defining words.
A defining word executed in the form:
32b CONSTANT <name>Creates a dictionary entry for <name> so that when <name> is later executed, 32b will be left on the stack.
A variable array holding the vocabularies which are searched to find a word.
addr2 is addr1+1 and +n is the length of the counted string at addr1. The byte at addr1 contains the byte count +n. Range of +n is {0..255}. Forth strings are often stored as a count byte followed by the text.
COUNT
is used to convert the string address to the address of the text, and the number of characters in that text. For reasons of portability, do not useCOUNT
for any other purpose. For example:"" Hello" COUNT TYPEis the same as:
." Hello"
Displays a carriage-return and line-feed or equivalent operation. The user variable
OUT
is reset to 0.
The default action of a deferred word as assigned by
DEFER
. On execution it gives an error message and performsABORT
. SeeDEFER
ABORT
.
A defining word executed in the form:
CREATE <name>Creates a dictionary entry for <name>. After <name> is created, the next available dictionary location is the first byte of <name>'s parameter field. Execution of <name> returns the parameter field address of <name>.
CREATE
is also often used within a colon definition:: cccc CREATE compile-time words DOES> run-time words ;When 'cccc' is executed
CREATE
builds a new dictionary header.DOES>
is immediate and compiles code that causes the words from the run-time portion ofDOES>
onwards to be executed. The phrase:cccc nnnncauses a new word 'nnnn' to be created. When 'nnnn' executes,
DOES>
returns the address of 'nnnn's parameter area, and the code followingDOES>
is then executed. To illustrate this, we will defineVARIABLE
andCONSTANT
usingCREATE
andDOES>
. The action is identical to, but slower than, the usual implementation because the new defining words execute high level code. For example, compiling interactively on the target, the definitions ofCONSTANT
andVARIABLE
are:: VARIABLE CREATE 0 , DOES> ; : CONSTANT CREATE , DOES> @ ;
A variable holding the vocabulary into which new definitions are compiled
Converts a 64 bit double integer to a normalised floating point number.
wd1 is the arithmetic sum of wd1 plus wd2.
The result d3 is d1-d2.
Print a signed double number in the current base followed by a space.
Print a signed double number in the current base in a field n characters wide. The output is right aligned with leading zeros suppressed and no trailing space.
Take the absolute value of d1 i.e. if d1 is negative, make it positive.
Set the input-output numeric conversion base to ten.
A defining word used in the form:
DEFER <name>When <name> executes it executes the action assigned to it. The action assigned by
DEFER
is that ofCRASH
, but other actions are assigned by the phrasing:ASSIGN action TO-DO <name>e.g:
ASSIGN (EMIT) TO-DO EMITwill assign the word
(EMIT)
to be the action ofEMIT
, which is a deferred word.
The vocabulary that words are compiled into (defined by
CURRENT
) is changed to be the same as the first vocabulary in the search order (defined byCONTEXT
).
Convert f1 degrees to its corresponding number of radians.
Returns the current stack depth in cells, that is 1 represents one word on the stack, 2 represents two words, and so on. The returned value does not include n, so 0 represents an empty stack.
Converts the character char using base n1. If conversion is successful the result is returned with the flag, otherwise only the false flag is returned.
Leave the integer part of f as a double number on the stack.
Compiles a double number into the dictionary as a literal. Unlike its fig-Forth counterpart, the Forth-83 version is not state-smart. See
LITERAL
LIT
.
d2 is the two's complement of d1.
Normalise double number d by n left shifts. Leaves a floating point number on the stack.
Used in the forms:
DO ... LOOP DO ... +LOOPBegins 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. For example the words inside the loop:w DUP DO ... LOOPare executed times. See
?DO
Defines the execution-time action of a word created by high-level defining word. Used in the form:
: <namex> CREATE ... DOES> ... ;and then:
<namex> <name>
DOES>
marks the termination of the defining part of the defining word <namex> and then begins the definition of the execution-time action for words that will later be defined by <namex>. When <name> is later executed, the address of <name>'s parameter field is placed on the stack and then the sequence of words betweenDOES>
and;
are executed.
32b is removed from the stack.
The n bytes in memory starting at address addr are displayed (in hexadecimal). Very useful when debugging.
DUMP
also shows the ASCII characters formed by the memory.
Duplicate 32b.
Print the floating point number on the stack in exponential form.
Used in the form:
flag IF ... ELSE ... ENDIF
ELSE
executes after the true part followingIF
and forces execution to continue at just afterENDIF
. See:IF
,ENDIF
andTHEN
.
The ASCII character in the low byte is displayed.
All the mass storage buffers are marked as unused, regardless of their current contents or status.
A word used to mark the end of the
CASE
....OF
....ENDOF
....ENDCASE
structure. If entered from the default action a word is dropped from the stack. See?OF
OF
ENDOF
CASE
The word used to mark the end of the
IF
....ENDIF
orIF
....ELSE
....ENDIF
structures. SeeIF
ELSE
THEN
The word used to mark the end of a selection procedure in the
CASE
....OF
....ENDOF
....ENDCASE
structure. The code betweenOF
andENDOF
or?OF
andENDOF
is executed if the test atOF
or?OF
is passed. AfterENDOF
execution continues immediately after theENDCASE
. SeeCASE
OF
?OF
ENDCASE
At address addr, a count of n bytes is zeroed.
The standard error handler reports error n. If the system is loading, the offending line will be displayed.
Returns true if the event triggered bit has been set in the current task's status byte.
The word definition indicated by addr is executed. The application will most probably crash if addr is not a compilation address. Useful for executing an action (cfa) pulled out of a table.
Compiled within a colon definition such that when executed, that colon definition returns control to the definition that passed control to it by returning control to the return point on top of the return stack. An error condition exists if the top of the return stack does not contain a valid return point, and so
EXIT
will not work within aDO
...LOOP
structure.
Defined by the standard to receive characters and store each into memory. The transfer begins at addr proceeding towards higher addresses one byte per character until either a <CR> is received or until +n characters have been transferred. No more than +n characters will be stored. The <CR> is not stored in memory.
All characters actually received and stored into memory will be displayed, with <CR> displaying as space. The number of characters collected (excluding any "return") is stored in the user variable
SPAN
. Note that because of this the contents ofSPAN
interrogated directly from the keyboard may not reflect what you intended.
Compile the floating point number on the top of the stack.
Print the top floating point number on the stack in free format.
Store the floating point number f at address addr.
Add together the top two floating point numbers on the stack and put the floating point result on the stack.
Subtract the top floating point number on the stack from the second floating point number on the stack, and put the floating point result on the stack.
Take the top two floating point numbers off the stack, multiply them together, and leave the floating point result on the stack.
Divide the second floating point number on the stack by the top floating point number and leave the floating point result on the stack.
Leave true flag if f1<f2. Otherwise, leave a false flag.
Leave a true flag if f<0. Otherwise, leave a false flag.
Leave a true flag if the top two floating point numbers on the stack are equal. Otherwise leave a false flag.
Leave a true flag if the floating point number on the top of the stack is zero.
Leave a true flag if f1>f2. Otherwise, leave a false flag.
Leave a true flag if the floating point number on the top of the stack is greater than zero.
If interpreting, takes text from the input stream and, if possible, converts it to a floating point number on the stack. Numbers in integer format will be converted to floating point. If compiling, the converted number is compiled.
Attempts to convert a token from the input stream to a floating-point number. Numbers in integer format will be converted to floating point. An indicator (0 or 3) is returned in the same way as an indicator is returned by
FNUMBER?
.
Fetch the floating point number from address addr and put it on the stack.
Raise 10 to the power f1 and put the result on the stack.
Take the modulus of the floating point number on the top of the stack.
Leave, on the stack, the angle (in degrees) whose cosine is f1, such that 0<=f2<=180.
When generating the array, take n floating point numbers and n, and compile them into the array. When executing the child word, take n and place floating point number n from the array onto the stack. Note that the numbering in the array goes 0,1,..n-1.
Leave, on the stack, the angle (in degrees) whose sine is f1, such that -90<=f2<=90.
Leave, on the stack, the angle (in degrees) whose tangent is f1, such that -90<f2<90.
Floating point equivalent of
CONSTANT
. Use in the form:<f.p. number on stack> FCONSTANT <name>
Take the cosine of f1 (degrees) and put it on the stack.
Drop the floating point number on the top of the stack.
Duplicate the floating point number on the top of the stack.
Raise e, the exponential number, to the power f1 and put the result on the stack.
Leave the fractional remainder from the division f1/f2. The remainder takes the sign of the dividend.
u bytes of memory beginning at addr are set to 8b. No action is taken if u is zero.
A counted string is at addr1. It is a name to be looked up in the dictionary. If the name cannot be found addr1 and a false flag are returned, so that
NUMBER?
can later check to see if the string is a valid number. If the name is found, its compilation address (cfa) is returned, together with a non-zero flag. If the word is immediate the flag is 1, otherwise it is -1. The search is through the currently specified search order.
Place the floating point integer value of f1 on the stack.
When compiling, compile f as a literal. For example,
: ABCD [ calculate f ] FLITERAL ;Compilation is suspended for the compile-time calculation of f. Execution of
ABCD
leaves f on the stack.
Take the logarithm of f1 to base e and put the result on the stack.
Switches the action of
NUMBER?
to beFNUMBER?
. This action can be reversed byINTEGERS
. BothFLOATS
andINTEGERS
are in theFORTH
vocabulary.
Take the logarithm of f1 to base 10 and put the result on the stack.
Performs the function of
SAVE-BUFFERS
then unassigns all block buffers. This word was originally intended to be useful for mounting or changing mass storage media but is now used to ensure that data is passed from Forth to the operating system. The phrase:USING xxxwhere xxx is an invalid pathname will do this. See
SAVE-BUFFERS
EMPTY-BUFFERS
Put the greater of the top two floating point numbers onto the stack.
Put the lesser of the top two floating point numbers onto the stack.
Negate the floating point number on the top of the stack.
Converts string at address addr to either a single, double or floating point number along with 1, 2, or 3 respectively. If a 0 is left on the stack then
FNUMBER?
was unable to convert the string.
Used in the form:
FORGET <name>If <name> is found in the compilation vocabulary (defined by
CURRENT
), delete <name> from the dictionary, and also delete 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.
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 theFORTH
vocabulary until a different compilation vocabulary is established. See:VOCABULARY
Floating point equivalent of
OVER
.
Floating point equivalent of
ROT
.
Leave the signed integer quotient f4 and remainder f3 when f1 is divided by f2. The remainder has the same sign as the dividend.
Leave the floating point number and a flag on the stack. Leaves a true flag if f is negative, else leaves a false flag.
Leave the floating-point sine of f1 (degrees) and put it on the stack.
Take the square root of the floating-point number on the top of the stack and put the result onto the stack.
Floating point equivalent of
SWAP
.
Take the tangent of f1 (degrees) and put the result on the stack.
Floating point equivalent of
VARIABLE
. Set up anFVARIABLE
by typing:FVARIABLE <name>
Raise f1 to the power n (n integer), and put result on the stack.
Raise f1 to the power f2 and put the result on the stack.
Waits for a message to be received and returns the message and the sending task.
Halts the task whose number is given. Do not halt task 0. Halting a task prevents it responding to messages or events.
Tests the keyboard using
KEY?
to see if a key has been pressed. If no key has been pressed, a zero flag is returned. If a key has been pressed it is read. If the key is not a space, a true flag is returned. If the key is a space, another key is read. If the second key is a space, a false flag is returned, otherwise a true flag is returned.This word is very useful to control output displays, as it pauses on the space bar, and any other key returns a true flag, usually used to terminate the display.
The address of the next available dictionary location.
Changes the base for numeric conversion to hexadecimal. The contents of
BASE
will be changed to decimal 16.
Char is inserted into a pictured numeric output string. Typically used between
<#
and#>
to embed a character into numeric output.
w is a copy of the loop index. Unlike older fig-Forth implementations, in Forth-83
I
is not a synonym ofR@
which should not be used. May only be used in the forms:DO ... I ... LOOP DO ... I ... n +LOOP
Used in the forms:
flag IF ... ELSE ... ENDIF flag IF ... ENDIFIf flag is true, the words following
IF
are executed and the words followingELSE
until just after theENDIF
are skipped. TheELSE
part is optional. If flag is false, words fromIF
throughELSE
, or fromIF
throughENDIF
(when noELSE
is used), are skipped. SeeELSE
ENDIF
THEN
.
Marks the most recently created dictionary entry as a word that will be executed when encountered during compilation rather than compiled.
Initialises the multi-tasker, task 0 which is the Forth itself, and starts the multi-tasker. Just include this word in
COLD
to kick the multi-tasker into action.
The main part of the multi-tasker reset process.
Switches the action of
NUMBER?
to beINTEGER?.
This action reverses that ofFLOATS
. BothFLOATS
andINTEGERS
are in theFORTH
vocabulary.
The outer text interpreter which interprets or compiles each word from the input stream according to the state of the variable
STATE
. If the word is not in the dictionary, a number conversion is attempted. If this fails, an error is reported. Text input is performed byWORD
and numeric conversion is performed byNUMBER?
.
w is the index of the next outer loop. May only be used within a nested
DO
...LOOP
orDO
...+LOOP
structure in the form, for example:DO ... DO ... J ... LOOP ... +LOOP
Receives a character from the console/terminal or input stream. All valid characters can be received. According to the Forth 83 standard, control characters should not be processed by
KEY
or the host system for any editing purpose. Characters received byKEY
will not be displayed.
Returns a true flag if a character is available for input by
KEY
.
Returns the address of the most recently defined word in the
CURRENT
vocabulary (the one words are being compiled into).
When
LEAVE
is encountered the loop terminates immediately, and execution resumes afterLOOP
or+LOOP
. When the loop terminates the loop control parameters are discarded. May only be used in the forms:DO ... LEAVE ... LOOP DO ... LEAVE ... +LOOP
LEAVE
may appear within other control structures that are nested within theDO
...LOOP
structure. More than oneLEAVE
may appear within aDO
...LOOP
structure.
Converts a word's link field address to its compilation address (cfa).
The primitive compiled by
LITERAL
to return an in-line value. When a number such as 33 is encountered while compiling, it is compiled asLIT
33 into the dictionary, and is returned byLIT
when the word executes.
Typically used in the form:
[ 32b ] LITERALCompiles a system dependent operation so that when later executed, 32b will be left on the stack. Unlike its fig-Forth counterpart, this word is not state-smart. See
LIT
Increments the DO-LOOP index by one. If the new index crosses the boundary between limit-1 and limit, the loop is terminated and loop control parameters are discarded. When the loop is not terminated, execution continues to just after the corresponding
DO
.
Two 32 bit signed numbers are multiplied together to produce a 64 bit signed number.
A signed mixed magnitude operator. NOT the same as the fig-Forth word of the same name, which is replaced by
MU/MOD
. The 64-bit d1 is divided by the 32-bit n2 to produce a 32-bit remainder n3 and a 32-bit quotient n4. Note the use of floored division.
n3 is the greater of n1 and n2 according to the operation of <.
n3 is the lesser of n1 and n2 according to the operation of >.
n3 is the remainder after dividing n1 by the divisor n2. The sign of n3 is determined by the rules of floored division.
An intelligent version of
CMOVE
that copies count bytes starting at addr1 to addr2, such that the destination block is always an image of the source block. Useful when the ranges may overlap.
Returns true if the task is holding a message, and is therefore not free to receive another one.
An unsigned mixed magnitude operator. Double number ud1 is divided by u2 to give a remainder u3 and a double quotient ud4. This word is only necessary as the Forth-83
UM/MOD
does not return a double quotient as did its fig-Forth forbear. Be careful not to confuseUM/MOD
(part of the Forth-83 standard) withMU/MOD
(not part of the standard, introduced by F83).
Turns the multi-tasker on, by clearing the bit in the TASK# byte in RAM that inhibits the scheduler.
Converts the compilation address of a word (in this case the cfa) to the address of its name field.
Converts a word's name field address to its compilation address (cfa).
n2 is the two's complement of n1, i.e., the difference of zero less n1.
Removes the second item on the stack. Used for cleaning up.
A dummy word that does nothing.
32b2 is the one's complement of 32b1.
Performs the function of converting text to binary numbers. The counted string at addr is converted to a number. If conversion is possible the number of cells generated is left on the top of the stack as well as a number of that size.
No conversion - 0
Single number - n 1
Double number - d 2
Soft floating point - f 3If a comma is encountered, the variable
DPL
will contain the number of digits after the comma, otherwiseDPL
contains -1. See#LITERAL
Used to mark the start of a section of code conditionally executed in a
CASE
...OF
...ENDOF
...ENDCASE
control structure. If n1 is equal to n2 the code betweenOF
andENDOF
is executed, and control then passes to immediately afterENDCASE
. Otherwise control passes to immediately after the nextENDOF
, n1 being kept so that another test can be made in front of anotherOF
...ENDOF
clause.
Clears (zeros) the word at the given address. Used for resetting flags, and clearing counters. See
ON
Sets the word at addr to -1. Used for setting flags.
Reduces the search order to be just the
ROOT
vocabulary, which is a short vocabulary from which all others can be reached.
32b3 is the bit-by-bit inclusive-or of 32b1 with 32b2.
Displays the order in which vocabularies are searched, starting with the first one searched (the
CONTEXT
vocabulary). The vocabulary into which definitions are built (theCURRENT
vocabulary) is also displayed.
Copies the second item on the stack to the top of the stack. Like
DUP
this word is useful for getting a copy of a stack item for passing as a parameter to another word. SeeDUP
The base address of a scratch area used to hold text and string data for 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.
Waits for one iteration of the scheduler. Equivalent to:
1 WAIT
32b is a copy of the +nth stack value, not counting +n itself, where 0 refers to the top of the stack.
Copies an uncounted string addr1/len to a counted string at addr2
Reduces the vocabulary search order by deleting the first entry in the list. Used with
ALSO
to temporarily add a vocabulary to the search list:ALSO TOOLS ...... PREVIOUS
Input 80 characters of text (or until a carriage-return) from the user's terminal. The text is placed at the address contained in
TIB
and the variable>IN
(position in input line) is set to zero. SeeEXPECT
Clears the return stack, sets interpret state, accepts new input from the current input data device, and begins text interpretation. No message is displayed.
32b is a copy of the top of the return stack. The return stack is unaffected.
32b is removed from the return stack and transferred to the data stack.
Convert f1 radians to degrees, and put result on the stack.
Compiles the compilation address (cfa) of a word inside the definition of the word. Normally a word name is not available until its definition is complete, so that a word can be redefined in terms of its previous definition. If recursion is required, this mechanism must be overcome, and that function is performed by
RECURSE
.
Used in the form:
BEGIN ... flag WHILE ... REPEATAt execution time,
REPEAT
continues execution to just after the correspondingBEGIN
. See:BEGIN
WHILE
A bit masking operation performed on the byte at addr. All the '1' bits in the mask are reset in the byte. Logically, the equivalent of
NOT
AND
.
Restarts a task that was halted by
HALT
orWAIT
. UnlikeACTIVATE
, the task resumes where it left off.
Restore the interrupt Enable State previously saved by
SAVE-INT
.
The +nth 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. If n is negative no action is taken. n=0 refers to the top of the stack. Note also that this is a slow operation as data is actually copied.
Frequent use of
ROLL
is often a sign of bad factorisation of the problem into separate words.
The top three stack entries are rotated, bringing the deepest to the top.
The return stack pointer is set to the given value. The stack can be reset to its original value by the phrase:
R0 @ RP!
Returns the current value of the return stack pointer. See also
R0
RP!
S0
SP!
SP@
A user variable holding the address that should be used to reset the data stack.
S0 @ SP! \ reset data stackThe initialisation of each task that may reset the data stack should include code to initialise this variable, e.g.
SP@ S0 ! \ initialise
The signed 32 bit number n is converted to a signed 64 bit number d.
Converts a single (32 bit) number to a normalised floating point number.
The two strings at addresses addr1 and addr2, length bytes long, are compared, and if they are identical a true flag is returned.
The contents of all block buffers marked as
UPDATE
are written to their corresponding mass storage blocks. All buffers are marked as no longer being modified, but remain assigned.
Saves the current state of the interrupt enable on the stack, and disables interrupts. See
RESTORE-INT
.
A text scanning primitive. Given the address of some ASCII text, the number of bytes to go, and the character to look for, the text is scanned for the given character. The address at which the character was found, and the number of bytes remaining is returned. If the number of bytes remaining is 0, the character was not found. See
SKIP
Returns the task number of the current task. Useful with
MSG?
in particular to determine whether or not a message has been received by the task.
Sends a message to the given task. The message can be used on its own, or as a pointer to an extended message.
A byte-wide bit masking operation. All '1' bits in the mask are set in the byte at addr. Logically equivalent to
OR
. SeeRESET-BIT
TEST-BIT
TOGGLE-BIT
If n is negative, an ASCII "-" (minus sign) is appended to the pictured numeric output string. Typically used between
<#
and#>
.
Turns off the multi-tasker by setting the scheduler disable bit in the
TASK#
byte in internal RAM.
Takes the single number integer part of f and puts it on the stack.
As
SCAN
, butSKIP
looks for the first character that is NOT the specified character. SeeSCAN
Toggles the 'smudge' bit of the most recently defined words name field. If the bit is set the word cannot be found by a normal dictionary search. If an error occurs during compilation the phrase:
SMUDGE FORGET <name>can be used to remove from the dictionary the word in which the error occurred.
Returns the address and length of the current input buffer. This will be the text input buffer or the disc buffer, depending on the value of
BLK
.
Sets the parameter stack pointer to the given value.
Returns the current value of the parameter stack pointer.
Display an ASCII space.
Display +n ASCII spaces. Nothing is displayed if n is zero or negative.
The address of a variable containing the compilation state. A non-zero content indicates compilation is occurring, but the value itself is system dependent. A standard program may not modify this variable. Usually only used by 'state-smart' words (e.g. ASCII) in application programs to determine whether Forth is compiling or executing.
Returns the task status byte of the current task but with the top bit (bit 7) masked off. If this value is non-zero, the task has been awakened for a reason other than for normal running.
The top two stack entries are exchanged.
A label, NOT a word, which returns the start address in DATA RAM of the table holding the action words for all the tasks. In some systems this is implemented as a constant for visibility.
A byte-wide bit-masking operation. b is the result of testing all the bits at addr that are '1' bits in the mask. Logically equivalent to
AND
.
Used in the forms:
flag IF ... ELSE ... THEN flag IF ... THEN
THEN
is the point where execution continues afterELSE
, orIF
when noELSE
is present. sys is balanced with its correspondingIF
orELSE
. See:IF
ELSE
ENDIF
Screens n1 to n2 inclusive are loaded.
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.
Sets the action of the deferred word by writing the cfa into the parameter field (body) of a word created by
DEFER
. Used in the form:DEFER word ASSIGN action-word TO-DO word
Sets the CFA of a Forth word as the action to run when the task's event trigger is set.
ASSIGN <word> <n> TO-EVENT
Stores the CFA of the word forming the task action in the task table entry for the task.
ASSIGN <word> <n> TO-TASK
A byte-wide bit-masking operation. All the '1' bits in the mask are inverted at addr. Logically equivalent to XOR. See
TEST-BIT
SET-BIT
RESET-BIT
TOGGLE
Saves a copy of the top item on the stack under the second item.
+n characters are displayed from the character at addr and continuing through consecutive addresses. Nothing is displayed if n is zero.
u is displayed as an unsigned number in a free-field format.
The flag is true if u1 is logically less than u2.
The flag is true if u1 is logically greater than u2.
Two unsigned 32 bit numbers are multiplied together to produce an unsigned 64 bit number.
The 64 bit unsigned number ud is divided by the unsigned 32 bit number u1 to produce 32 bit unsigned numbers. The remainder is u2 and the quotient is u3.
Used in the form:
BEGIN ... flag UNTILMarks the end of a
BEGIN
...UNTIL
loop that will terminate based on the state of flag. If flag is true, the loop is terminated. If flag is false, execution continues to just after the correspondingBEGIN
. See:BEGIN
If char1 is a lower case letter, it is converted to upper case. See
UPPER
.
The currently valid block buffer is marked as modified. Blocks marked as modified will subsequently be automatically transferred to mass storage should its memory buffer be needed for storage of a different block or upon execution of
FLUSH
orSAVE-BUFFERS
.
The string of len bytes starting at addr is converted to upper case using
UPC
. SeeUPC
.
A defining word used in the form:
n USER ccccwhich defines a user variable whose address is n bytes from the start of the user area. When the user variable cccc is executed the address of its data area is returned. User variables usually contain system information that will be affected by a multi-user or multi-tasking environment. The base address of the user area is held in the UP register.
A vocabulary defined by addr2 is searched. Each word name is tested against the string at addr1. If a match is found, the cfa, and a flag are returned. The flag is 1 for an immediate word, and -1 for a normal word. If no match is found, the string address and 0 are returned. The vocabulary address addr2 is the same address as is set into
CONTEXT
by executing it.
A defining word executed in the form:
VARIABLE <name>A dictionary entry for <name> is created and two bytes are allotted (See
ALLOT
) in its parameter field. This parameter field is to be used for the contents of the variable. The contents are initialised to zero. When <name> is later executed, the address of its parameter field is placed on the stack.
A defining word executed in the 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
CONTEXT
vocabulary with <name>. When <name> becomes the compilation vocabulary new definitions will be appended to <name>'s list. See:DEFINITIONS
CONTEXT
CURRENT
V-FIND
Displays a list of all the vocabularies in the dictionary.
16b is stored into the 16 bit word at addr.
16b is the contents of the 16 bit word at addr.
Compiles 16b into the next available dictionary location, and advances the dictionary pointer by two. The basic word for compiling 16 bit wide data into the dictionary. See ,
C,
Suspends the current task for n iterations of the scheduler. If n is 0, the task is suspended until a message or event is received.
The current task is suspended until it receives a message or an event trigger. The words
MSG?
andEVENT?
can be used to determine whether a message or an event trigger terminated the wait. Note that if an event trigger is received, the event handler will have been called, and the event run flag (bit 4 in the status byte) will be set.
Used in the form:
BEGIN ... flag WHILE ... REPEATSelects conditional execution based on flag. When flag is true, execution continues to just after the
WHILE
through to theREPEAT
which then continues execution back to just after theBEGIN
. When flag is false, execution continues to just after theREPEAT
, exiting the control structure. See:BEGIN
REPEAT
The flag is returned true if n1 is in the range n2..n3 inclusive.
Generates a counted string by non-destructively accepting characters from the input stream until the delimiting character char is encountered or the input stream exhausted. Leading delimiters are ignored.
The entire character string is stored in memory beginning at addr as a sequence of bytes. The string is followed by a blank that is not included in the count. The first byte of the string is the number of characters {0..255}. If the string is longer than 255 characters, the count is unspecified. If the input stream is already exhausted as
WORD
is called, then a zero length character string will result. The address returned is the address at which the string was placed.
Lists the names of the words in the
CONTEXT
vocabulary. Pressing the space bar will halt the listing, which can be restarted by pressing the space bar again. Any other key will cause the listing to abort.
32b3 is the bit-by-bit exclusive-or of 32b1 with 32b2.
None
None
Switches to the Interpretation State. The text from the input stream is subsequently interpreted. For typical use see
LITERAL
. The use of[
and]
must be balanced.
Used in the form:
[COMPILE] <name>Forces compilation of the following word <name>. This allows compilation of an immediate word when it would otherwise have been executed.
Defines a comment to the end of the input line. This word can be used with any input source.
Sets Compilation State. The text from the input stream is subsequently compiled. For typical usage see
LITERAL
. The use of[
and]
must be balanced. See:[