TurboForth Word Glossary

The following lists all words in TurboForth's ROM. All of the following words are available immediately from start-up.

Notes:

All words have an associated colour, the meaning of which is as follows:

Tested, OK	- high degree of confidence that this word functions as intended
To be changed	- works, however is targeted for change before final release
Bugged	- Either crashes TF, or does not work as advertised
Not yet implemented	- To do
Newly added word	- Newly added, or changed from the previous release

Stack Signatures:

The runtime stack signatures for all words are listed. Stack signatures are interpreted as follows. The following is an example of the stack signature for the word SWAP:

a b – b a

This example shows that the top two cell-wide values on the stack (a & b) are swapped. Before execution, b was at the top of the stack. After execution, a is at the top of the stack. The stack before execution of the word is shown to the left of the – symbol; the top of the stack being the rightmost item (b). The stack after execution of the word is shown to the right of the – symbol, again, the top of stack is the item furthest to the right.

Word Type

Words have an associated type, according to the following key:

S = Standard word. Compiles into a word normally, executes at run-time
I = Immediate word. Executes at compile time (at the point at which it is encountered, during the compilation of a word)
C = Compiling word. Compiles either data, code, or both into the word definition. All C type words affect H and HERE, since they compile data or code into words. Most C words will also be I (immediate words)
SS = State smart word. The behavior of the word is dependent on STATE. Care should be taken when compiling state-smart words into definitions. Generally, a state-smart word will execute its interpretation semantics when executed from within a colon definition (since STATE will be normally be 0).

Misc

Word	Stack Effect	Type	Description	v1.0	v1.1	v1.2
BL	-- 32	S	Pushes the value 32, which represents a space character, or a “Blank”. Commonly used in conjunction with WORD to get a word delimited by a blank. E.g. BL WORD.		x	x
BYE	--	S	Immediately resets the computer back the master title screen. Any un-flushed files are not flushed. Any open files are not closed.	x	x	x
COLD	--	S	Performs a cold reset. Any un-flushed files are not flushed prior to reset. Any open files are not closed.	x	x	x
DATA	-- addr count	IC	At compile time, compiles the numeric data following it into the colon definition. At run-time, DATA pushes the address of the data, and item count (in cells) to the stack, and continues execution with the word immediately following the data list. The first data parameter should be the number of data items in the list. Example: DATA 5 100 200 300 400 500 The above causes 6 cells to be compiled into the word (the length (5) and the five data items). At run-time, DATA will push the address of the first data item (100) and the count (5) to the stack and continue execution from the first word following the data list. DATA should only be used inside a colon definition.	x	x	x
DECIMAL	--	S	Sets BASE to 10.	x	x	x
EDIT	block --	S	Invoke editor, loading disk block block into the editor	x	x	x
EXIT	--	S	Exits a forth word immediately. Do not use inside a loop. Use LEAVE instead.	x	x	x
HEX	--	S	Sets BASE to 16 (hexadecimal).	x	x	x
QUIT	--	S	Clears the return stack, sets interpret state, accepts new input from the keyboard.	x	x	x
<<< Back to top

Stack Words

Word	Stack Effect	Type	Description	v1.0	v1.1	v1.2
-ROT	a b c -- c a b	S	Rotates the top 3 items to the right. The topmost item rotates into the 3rd position. 1 2 3 becomes 3 1 2.	x	x	x
?DUP	a -- a \| a a	S	Duplicates the topmost item if it is not 0.	x	x	x
.S	--	S	Non-destructively displays the contents of the stack.	x	x	x
><	ab -- ba	S	Swaps bytes in a word. E.g. 0x1234 becomes 0x3412.	x	x	x
2DROP	a b --	S	Discards the topmost two cells.	x	x	x
2DUP	a b -- a b a b	S	Duplicates the topmost two cells.	x	x	x
DEPTH	-- depth	S	Places the number of cells on the stack on the stack.	x	x	x
DROP	n --	S	Discards the topmost cell.	x	x	x
DUP	a -- a a	S	Duplicates the topmost cell. 1 becomes 1 1.	x	x	x
NIP	a b -- b	S	Discards the second cell.	x	x	x
OVER	a b -- a b a	S	Copies the second cell to the top. 1 2 becomes 1 2 1.	x	x	x
PICK	n – Nth	S	Copies stack cell number n to the top of the stack.	x	x	x
ROLL	+n -- n	S	Rolls the stack left +n items. Items rolled out to the left wrap around to the top of the stack.	x	x	x
ROT	a b c -- b c a	S	Rotates the top 3 items to the left. The 3rd item rotates into the top position. 1 2 3 becomes 2 3 1.	x	x	x
SWAP	a b -- b a	S	Swaps the topmost two cells. 1 2 becomes 2 1	x	x	x
TUCK	a b -- b a b	S	Copies the top cell into the 3rd position, moving the stack forward. 1 2 becomes 2 1 2.	x	x	x
	Note: numbers in red show the position of new data
<<< Back to top

Return Stack Words

Word	Stack Effect	Type	Description	v1.0	v1.1	v1.2
>R	d: a -- r: -- a	S	Moves the top cell from the data stack to the return stack.	x	x	x
R>	r: a -- d: -- a	S	Moves the top cell from the return stack to the data stack.	x	x	x
R@	r: a -- a d: -- a	S	Copies the top cell from the return stack to the data stack (i.e. does not remove it).	x	x	x
	Note: The stack effects above show data stack and return stack
<<< Back to top

Math Words

Word	Stack Effect	Type	Description	v1.0	v1.1	v1.2
1+	a -- a+1	S	Increases the topmost cell value by 1.	x	x	x
MAX	a b -- a\|b	S	a and b are removed, to be replaced with the higher of the two.	x	x	x
MIN	a b -- a\|b	S	a and b are removed, to be replaced with the lower of the two.	x	x	x
2+	a -- a+2	S	Adds 2 to the topmost cell.	x	x	x
ABS	-a -- a	S	Converts topmost cell to positive if negative.	x	x	x
/	a b -- a/b	S	Divides a by b, replacing them with the result.	x	x	x
2/	a -- a/2	S	Divides the topmost cell by 2.	x	x	x
*	a b -- a*b	S	Multiplies a by b, replacing them with the result.	x	x	x
2*	a -- a*2	S	Multiplies the topmost cell by 2.	x	x	x
*/	n1 n2 n3 – n4	S	n1 is first multiplied by n2 producing an intermediate 32-bit result. n4 is the floor of the quotient of the intermediate 32-bit result divided by the divisor n3. The product of n1 and n2 is maintained as an intermediate 32-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 of the range {-32,768..32,767}.		x	x
*/MOD	n1 n2 n3 -- n4 n5	S	n1 is first multiplied by n2 producing an intermediate 32-bit result. n4 is the remainder and n5 is the floor of the quotient of the intermediate 32-bit result divided by the divisor n3. A 32-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 {-32,768..32,767}.		x	x
/MOD	n1 n2 -- n3 n4	S	n3 is the remainder and n4 the floor of 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 {-32,768..32,767}.		x	x
NEGATE	a -- a\|-a	S	Negates the topmost cell (positive becomes negative, negative becomes positive).	x	x	x
RND	limit --- n	S	Pushes a pseudo random number n which is a number between 0 and limit-1. If the full range (0-65535) is required, use a limit of 0.		x	x
MOD	a b -- a MOD b	S	Replaces a and b with a mod b.	x	x	x
1-	a -- a-1	S	Subtracts 1 from the topmost cell.	x	x	x
2-	a -- a-2	S	Subtracts 2 from the topmost cell.	x	x	x
-	a b - a-b	S	Subtracts b from a, replacing them with the result.	x	x	x
+	a b -- a+b	S	Sums a and b, replacing them with the result.	x	x	x
UM/MOD	ud u1 -- u2 u3	S	u2 is the remainder and u3 is the floor of the quotient after dividing ud by the divisor u1. All values and arithmetic are unsigned. An error condition results if the divisor is zero or if the quotient lies outside the range		x	x
UM*	u1 u2 -- ud	S	ud is the unsigned double product of u1 times u2. All values and arithmetic are unsigned.		x	x
<<< Back to top

Comparison Words

Word	Stack Effect	Type	Description	v1.0	v1.1	v1.2
<	a b -- true\|false	S	Replaces a and b with TRUE if a < b, else replaces with FALSE.	x	x	x
<=	a b -- true\|false	S	Replaces a and b with TRUE if a <= b, else replaces with FALSE.	x	x	x
<>	a b -- true\|false	S	Replaces a and b with TRUE if a and b are of different value, else replaces with FALSE.	x	x	x
=	a b -- true\|false	S	Replaces a and b with TRUE if a and b are equal, else replaces with FALSE.	x	x	x
>	a b -- true\|false	S	Replaces a and b with TRUE if a > b, else replaces with FALSE.	x	x	x
>=	a b -- true\|false	S	Replaces a and b with TRUE if a >= b, else replaces with FALSE.	x	x	x
0<	a -- true\|false	S	Replaces a with TRUE if a<0, else replaces with FALSE.	x	x	x
0<=	a -- true\|false	S	Replaces a with TRUE is a<=0, else replaces with FALSE.	x	x	x
0<>	a -- true\|false	S	Replaces a with TRUE is a<>0, else replaces with FALSE.	x	x	x
0=	a -- true\|false	S	Replaces a with TRUE if a=0, else replaces with FALSE.	x	x	x
0>	a -- true\|false	S	Replaces a with TRUE if a>0, else replaces with FALSE.	x	x	x
0>=	a -- true\|false	S	Replaces a with TRUE if a>=0, else replaces with FALSE.	x	x	x
U<	a b -- true\|false	S	Performs an unsigned < comparison. Replaces a and b with TRUE if unsigned value a is less than unsigned value b, else replaces with FALSE.	x	x	x
WITHIN	n low high -- true\|false	S	Replaces n, low, and high with TRUE if n is >= low and < high, else replaces with FALSE.	x	x	x
<<< Back to top

Flow Control Words

Word	Stack Effect	Type	Description	v1.0	v1.1	v1.2
(+LOOP)	n --	S	Internal assembly-code representation of +LOOP. Compiled by +LOOP.	x	x	x
(DO)	max index --	S	Internal assembly-code representation of DO. Compiled by DO.	x	x	x
(FOR)	count --	S	Internal assembly-code representation of FOR. Compiled by FOR.	x	x
(LOOP)	--	S	Internal assembly-code represenation of LOOP. Compiled by LOOP.	x	x	x
(NEXT)	--	S	Internal assembly-code represenation of NEXT. Compiled by NEXT.	x	x
+LOOP	n --	IC	Adds n to the current loop index. If the index equals or exceeds the loop limit, the loop exits, otherwise the loop executes again. Example: : TEST 100 0 DO I . 2 +LOOP ; TEST 0 2 4 6 8 10 12 14 16 etc	x	x	x
0BRANCH	flag --	S	Branches using the relative offset in the following cell if flag is FALSE, otherwise takes no action. 0BRANCH is compiled into colon definitions by words such as IF, ELSE, WHILE, UNTIL, OF etc.	x	x	x
AGAIN	--	IC	Loops back unconditionally to associated BEGIN.	x	x	x
BEGIN	--	I	Marks the beginning of a BEGIN...WHILE...REPEAT loop or a BEGIN...UNTIL loop.	x	x	x
BRANCH	--	S	Branches unconditionally using the relative offset in the following cell.	x	x	x
CASE		I	Marks the beginning of case-by-case processing. Example: : TEST KEY CASE 32 OF ." SPACE " ENDOF 42 OF ." STAR " ENDOF 13 OF ." ENTER " ENDOF ." UNKNOWN CASE" ENDCASE ; : TEST-CASE BEGIN TEST BREAK? AGAIN ;	x	x	x
DO	max start --	IC	Begins a DO/LOOP or a DO/+LOOP sequence. The loop begins counting at start. The loop repeats when the word LOOP or +LOOP is encountered. The loop repeats from the word following DO. Each iteration through the loop increases the index value (accessible with the word I). When the index value is equal to max the loop terminates. The word LEAVE may be used to conditionally exit the loop early. Example: : TEST 100 0 DO I . LOOP ;	x	x	x
ELSE	--	IC	Words following ELSE will be executed if the parent IF clause evaluates to FALSE.	x	x	x
ENDCASE		IC	Ends case-by-case processing. See CASE.	x	x	x
ENDOF	--	IC	Marks the end of a particular test case. See CASE.	x	x	x
FOR	count --	IC	Begins a FOR/NEXT loop. The loop begins counting at count and decreases by 1 with each iteration. The loop terminates when the loop index (accessible via I) is equal to 0. Example: : TEST 100 FOR I . NEXT ; The word LEAVE may be used to conditionally exit the loop early.	x	x	x
I	-- index	S	Returns the current index in a DO/LOOP or FOR/NEXT loop.	x	x	x
IF	flag --	IC	Executes the words following IF if flag evaluates to TRUE. Starts an IF...[ELSE]...THEN clause.	x	x	x
J	-- index	S	Returns the outer index when used in a nested DO or FOR loop. Example: : TEST 10 0 DO ." Outer loop " I . CR 5 0 DO ." inner loop " J . LOOP CR LOOP ; In this example the inner loop accesses the index of the outer loop via the word J.	x	x	x
LEAVE	--	S	In a DO/LOOP or FOR/NEXT loop, causes the loop to exit. LEAVE should be used inside an IF...THEN block. Example: : TEST 10000 0 DO I . I 50 = IF ." EXITING EARLY" LEAVE THEN LOOP ; In this example, the loop is supposed to execute 10,000 times. However, the loop exits when the index is equal to 50.	x	x	x
LOOP	--	IC	Causes a DO/LOOP to repeat from the word immediately following DO. When the loop index, accessible via I is equal to max (see DO) the loop terminates and execution continues with the word immediatley following DO)	x	x	x
NEXT	--	IC	Causes a FOR/NEXT loop to repeat from the word following FOR. When the loop index, accessible via I is equal to 0 the loop terminates and execution continues with the word immediatley following NEXT.	x	x	x
OF	--	IC	Marks the beginning of a case test. See CASE.	x	x	x
REPEAT	--	IC	Loops back unconditionally to associated BEGIN.	x	x	x
THEN	--	IC	Marks the end of an IF...[ELSE]...THEN construct.	x	x	x
UNTIL	flag --	IC	Jumps back to associated BEGIN if flag evaluates to FALSE. I.e the loop exits if flag is TRUE.	x	x	x
WHILE	flag --	IC	Enters a WHILE/REPEAT block if flag evaluates to TRUE.	x	x	x
<<< Back to top

Logical Words

Word	Stack Effect	Type	Description	v1.0	v1.1	v1.2
<<	a count -- b	S	Shifts a count bits to the left. Bits shifted out of the most significant bit are discarded. Performs an arithmetic shift – i.e. the sign of the word (the most significant bit) is retained.	x	x	x
>>	a count -- b	S	Shifts a count bits to the right. Bits shifted out of the least significant bit are discarded. Performs a logical shift – i.e. 0 is shifted in at the most significant bit.	x	x	x
AND	a b -- a&b	S	Replaces a and b with their logical AND.	x	x	x
NOT	a -- ~a	S	Performs a bit-wise inversion (1's complement) on a.	x	x	x
OR	a b -- a\|\|b	S	Replaces a and b with their logical OR.	x	x	x
XOR	a b -- XOR(a,b)	S	Replaces a and b with their logical XOR (exclusive OR).	x	x	x
<<< Back to top

Memory Access Words

Word	Stack Effect	Type	Description	v1.0	v1.1	v1.2
-!	value address --	S	Deprecated from V1.2. Reads the cell at address. Subtracts value from the cell value, and stores the result at address.	x	x
!	value address --	S	Writes value to the cell at address.	x	x	x
@	address -- value	S	Pushes the value read from address to the stack.	x	x	x
@++	address – value address+2	S	The cell at address is read and the value pushed to the stack. Address is then incremented by 2, ready for @++ to be called again.	x	x	x
+!	value address --	S	Read the cell at address, adds value to it and stores the result at address.	x	x	x
0!	address --	S	Store 0 to the cell at address.	x	x	x
C!	char address --	S	Store lower 8 bits of char to address. (Byte write)	x	x	x
C@	address -- char	S	Read byte at address. Returns an 8-bit right justified cell, char.	x	x	x
CELLS	a -- a*2	S	Returns the number of bytes needed for a cells (a*2).	x	x	x
CHARS	a – a	S	Returns a. Included for compatibility and code readability.	x	x	x
CMOVE	src_addr dest_addr count --	S	Copies count bytes from src_addr to dest_addr.	x	x	x
CMOVE>	src_addr dest_addr count --	S	Copies count bytes from src_addr to dest_addr. Begins copying at the top of the range. Suitable for use when the source and destination memory areas overlap.	x	x	x
COPYW	src_addr dest_addr count --	S	Copies count cells (16-bits) from src_addr to dest_addr.	x	x	x
FILL	address count value --	S	Fills count bytes of memory with value, starting at address.	x	x	x
HFREE	-- hi_mem_free_bytes	S	Returns available memory (in bytes) in high memory.	x	x	x
LFREE	-- low_mem_free_bytes	S	Returns available memory (in bytes) in low memory.	x	x	x
>MAP	bank address –	S	Maps bank number bank into memory at address address. SAMS 1MB memory expansion required. Address should be a valid address on a 4K boundary (e.g. >2000, >3000, >A000, >B000, >C000, >D000, >E000 or >F000). Bank should be a number between 0 and >FF		x	x
MEM	--	S	Reports the number of free bytes in low memory, number of free bytes in high memory, and total number of free bytes respectively to the screen.			x
V!	value address --	S	Stores value to VDP address address.	x	x	x
V@	address -- value	S	Fetches value from VDP address address.	x	x	x
VMBR	vdp_address cpu_address count --	S	VDP Multiple Byte Read. Copies count bytes starting at vdp_address to CPU memory starting at cpu_address.	x	x	x
VMBW	vdp_address cpu_address count --	S	VDP Multiple Byte Write. Copies count bytes starting at CPU address cpu_address to vdp memory starting at vdp_address.	x	x	x
<<< Back to top

Parsing Words

Word	Stack Effect	Type	Description	v1.0	v1.1	v1.2
(	--	I	Begins a comment. End with a ) character. The comment is not compiled into colon definitions.	x	x	x
.(	--	I	Only valid in a block. Begins a displayed comment. End with a ) character. The comment will be displayed to the screen as the block loads. Useful in a block to provide commentary as a block loads (loading progress etc.). The comment is not compiled into colon definitions.	x	x	x
\	--	I	Trailing comment. All text after \ will be ignored. The comment is not compiled into colon definitions.	x
>BODY	cfa – body_address	S	Given a CFA on the stack, >BODY returns the address of the body of the word. The “body” contains the “payload” of the word. Only applies to words created with CREATE (i.e. VARIABLE, CONSTANT, VALUE). It is not meaningful to apply >BODY to words that are not children of CREATE. >BODY may also be applied to words that utilise DOES> to carry out their work.		x	x
>CFA	da – cfa	S	Converts dictionary address da to code field address cfa.	x	x	x
EXPECT	address length --	S	Receive length or C/L characters and store each received character into memory. The transfer begins at address, proceeding towards higher addresses one byte per character until either a "return" is received or until length or C/L characters have been transferred. No more than length or C/L characters will be stored. The "return" is not stored into memory. No characters are received or transferred if length is zero. On exit, SPAN is set to the number of characters actually received.	x	x	x
FIND	address length – xt type	S	Searches the dictionary for the string stored at address with length of length bytes. Returns the execution token (xt) or 0 if the word is not found in the dictionary. Type describes the type of the word. -1 indicates a standard (i.e. non-immediate) word. 1 indicates the word is immediate. A value of 0 indicates the word was not found.	x	x	x
>LINK	cfa – lfa	S	Converts code field address cfa to the associated link field address lfa. The link field address is the first field of any dictionary entry. (Note: this word was called >DFA in previous versions).		x	x
NUMBER	address length -- value flag	S	Attempts to convert the string at address with length length into a number. If fully successful the number (value) is placed onto the stack and flag will be 0. If it fails (for example contains an illegal character) then a partial number will be placed onto the stack for value (the value computed up until the failure) and flag will be >0. Thus, if flag>0 the string failed to parse fully as a number. A minus sign is permitted for negative numbers. BASE is used to parse numbers in the current BASE. Eg. If BASE=16 then digits 0-9 and A-F are considered legal and will be parsed properly. A facility also exists called 'quick hex' that allows a number to be entered in base 16, by placing a $ symbol at the beginning of the string. This avoids the need to change BASE to enter a hex number. E.g. instead of HEX FEED DECIMAL you can simply type $FEED. The number will be parsed as a hexadecimal number without the need to change BASE. The same facility also exists for binary numbers: Simply precede the number with a % symbol. E.g. %1001 = 9 decimal. The numbers returned are (by default) singles (16 bits). NUMBER can also return a double (32-bit (2 stack cells)) value by including a period in the number string. E.g. 100. 1.00 10.0 .100 will all return 100 decimal (assuming BASE=10) as a double, occupying two stack cells. The stack signature when returning a double value is: address length -- value_lsb value_msb flag. The various facilities can be mixed. For example, -$F. means -15 as a double. - $ and . can be specified in any order. However, $ or % if required, should be specified before any number digits. - and . can be placed anywhere in the string.	x	x	x
WORD	delimiter – address length	S	Moves through the input buffer defined by TIB returns the address and length of a word identified by the ascii value delimiter. Updates >IN as WORD moves through the buffer. If no word is found, or hits the end of the buffer (as defined by C/L) then 0 0 is returned. Note: If BLK>0 then address is a VDP address, otherwise it is a CPU address.	x	x	x
<<< Back to top

Console IO Words

Word	Stack Effect	Type	Description	v1.0	v1.1	v1.2
BREAK?	--	S	Scans keyboard for break (FCTN & 4). If detected, executes QUIT to return to the interpreter. Any open disk files (not including blocks files) will remain open.	x	x	x
CR	--	S	Issues a carriage return to the screen cursor (begins a new line). Scrolls screen up if on the last line of the screen (the 24th row)	x	x	x
EMIT	n–	S	Emits ASCII character n to the screen to the current cursor position. Advances cursor position.	x	x	x
GOTOXY	x y --	S	Sets cursor to x y.	x	x	x
JOYST	unit# -- value	S	Scans the selected joystick. For joystick #1 use a unit# of 0. For joystick 2 use a unit# of 1. The returned value value is a bit code which can be decoded as follows: 1=Fire, 2=Left, 4=Right, 8=Down, 16=Up Since each direction has its own bit, combinations are possible: for example, UP+LEFT+FIRE returns a value of 19. Note: The version of JOYST shipped in version 1.0 returns different values for up, down, left, right & fire. Note: The version of JOYST shipped in version 1.1 has a bug which can return un-predictable results or cause TurboForth to crash in some circumstances. An alternative version of JOYST can be installed in a block and used when required, as presented below. HEX CODE: JOYST C054 0221 0006 06C1 020C 0024 30C1 020C 0006 3541 06C1 0541 0241 001F C501 020C 8328 C80C 83D6 0300 0002 0300 0000 ;CODE DECIMAL	x	x	x
KEY	-- ascii	S	Suspends execution and waits for a key press. Returns ascii code of the key pressed.	x	x	x
KEY?	-- ascii\|-1	S	Scans keyboard and returns ascii code if a key is detected, else returns -1. Does not suspend execution.	x	x	x
PAGE	--	S	Clears the screen.	x	x	x
SPACE	--	S	EMITs a single space character (ascii 32) to the screen.	x	x	x
SPACES	count --	S	EMITs count spaces to the screen.	x	x	x
TERMINAL?	-- true\|false	S	Scans keyboard and tests for break (FCTN & 4). Returns TRUE if detected, else returns FALSE.	x	x
TYPE	address length --	S	Types the string of length length beginning at address address to the screen.	x	x	x
WORDS	--	S	Displays all words currently defined in the dictionary to the screen. Any key pauses the list. Pressing break (FCTN 4) stops the listing.	x	x	x
XY?	-- x y	S	Returns the current X & Y position of the cursor.	x	x	x
<<< Back to top

Compilation Words

Word	Stack Effect	Type	Description	v1.0	v1.1	v1.2
,	n --	S	Compiles the 16 bit cell n on the stack to HERE. Advances HERE by 2 (1 cell).	x	x	x
;	--	S	Ends compilation of the current colon definition and un-hides the definition from the dictionary, sets STATE to 0. Checks DO/LOOP FOR/NEXT and BEGIN/REPEAT etc. reference counters and errors if an un-balanced construct is detected.	x	x	x
:	--	S	Calls HEADER to build a dictionary entry and begins compilation of a colon definition (sets STATE to 1).	x	x	x
:CODE	--	S	Begins compilation of a machine code/ assembly language word. The name of the word must follow CODE: followed by a sequence of numbers. The numbers will be interpreted in the according the current value of BASE. CODE: writes the dictionary entry in a format suitable for machine code words (the CFA points to the machine code, instead of DOCOL) and then compiles the words into consecutive addresses in memory with no translation or conversions applied. The machine code should be terminated with ;CODE. Upon termination, ;CODE appends a B R12 instruction to the compiled code, which (at run time) calls NEXT. Example: HEX CODE: PLUS C014 0644 A500 ;CODE DECIMAL Creates a machine code word called PLUS which contains the following: MOV R4,R0 ; get topmost stack item in R0 DECT R4 ; pop the stack A R0,*R4 ; add R0 to the value on the stack To test it, try 9 100 PLUS .	x	x	x
;CODE		I	Terminates the definition of a machine code word. Appends a B *R12 instruction to the word being defined. See CODE:	x	x	x
'	-- xt	S	Returns the XT/CFA of the word immediately following. Use on command line only.	x	x	x
[	--	I	Used in a colon definition, temporarily suspends compilation (sets STATE to 0) and begins interpreting input as if on the command line.	x	x	x
[']	-- xt	I	During compilation of a colon definition, compiles the word following ['] as a LITERAL. When the colon definition is executed, the word's execution token (XT/CFA) shall be pushed to the stack, and not executed. Example: : TEST ['] DUP ; The above example will leave the execution token of DUP on the stack when TEST is executed.	x	x	x
[COMPILE]	--	IC	Compiles the XT/CFA of the word immediately following it to the current colon definition at address HERE. Use to compile immediate words into the current definition.	x	x	x
]	--	I	Used in a colon definition, ends interpretation mode and resumes normal compilation.	x	x	x
+TO	value --	SS	Adds value to the value in the VALUE immediately following it. Example: 2 +TO SCORE	x	x	x
ALIGN	--	SC	Aligns HERE to the next (highest) even compilation address.	x	x	x
ALLOT	n --	SC	Allots n bytes by advancing HERE by n bytes.	x	x	x
C,	n --	SC	Compiles the lower 8 bits of the cell n on the stack to here. Advances HERE by 1 byte.	x	x	x
COMPILE	--	SC	Compiles the XT/CFA of the word immediately following it to the current colon definition at address HERE. For immediate words use [COMPILE]	x	x	x
CONSTANT	n --	I	Creates a CONSTANT with the value n. The name is taken from the terminal input buffer. Do not use in a colon definition. Example: 10 CONSTANT TEN	x	x	x
CREATE	--	IC	Reads forward in the terminal input buffer and creates a word in the dictionary whose run-time behaviour is to return the body address of the newly created word.	x	x	x
DOES>	--	IC	Links a run-time action to a word created with CREATE.	x	x	x
EXECUTE	xt --	S	Executes the word whose XT/CFA is on the stack.	x	x	x
HEADER	address length --	S	Creates a dictionary entry with the name of the string nominated at address and length.	x	x	x
HIDDEN	da --	I	Toggles the hidden bit on/off in the last created dictionary entry pointed to by dictionary address da. When a word is hidden, dictionary searches with FIND will not find the word. Colon (:) hides new words during compilation so that new words may be defined in terms of identically named older words. Hiding the definition ensures FIND finds the old definition, not the new one. Semi-colon (;) un-hides the new definition (by executing HIDDEN again) at the end of compilation.	x	x	x
IMMEDIATE	--	I	Toggles the immediate bit on/off in the last created word. An immediate word will be executed (rather than compiled) during the compilation of a colon definition.	x	x	x
LIT	-- n	S	At execution time, places the value in the cell immediately following the LIT instruction onto the data stack.	x	x	x
LITERAL	n –	IC	Compiles LIT n to the current definition. n is a 16-bit cell. Normally used in conjuction with [ and ] to encode the result of a calculation into a colon definition as a literal (to save having to evaluate the calculation at run-time). For example, if A B and C are constants, then: : GET-RESULT A B + C * ; can be more efficiently expressed as: : GET-RESULT [ A B + C * ] LITERAL ; In the first example, (A+B)C is repeatedly calculated each time GET-RESULT is called. In the second example, (A+B)C is evaluated in immediate mode (facilitated by [ and ]) and encoded into the colon definition as a literal.	x	x	x
RECURSE	--	IC	Causes a recursive jump to the beginning of the word being defined. Since new words (in the process of being created) are hidden, they can not be referenced with their own name. Thus RECURSE creates a recursive call to the word currently under compilation.	x	x	x
TO	n --	SS	Used with a VALUE. Replaces the value of the named VALUE with n. Example: 100 TO SCORE	x	x	x
VALUE	n --	IC	Defines a VALUE using the name immediately following in the TIB with the value n. Use TO and +TO to modify the value. Example: 10 VALUE TEN VALUEs should not be defined within a colon definition.	x	x	x
VARIABLE	--	IC	Creates a variable using the name immediately following in the TIB. Variables are read and set with @ and !. Example: VARIABLE DELAY VARIABLEs should not be defined within a colon definition.	x	x	x
<<< Back to top

Interpreter Words

Word	Stack Effect	Type	Description	v1.0	v1.1	v1.2
ABORT	--	S	Immediately stops execution, resets data stack, resets return stack and returns to command line. No message is issued.	x	x	x
ABORT”	flag --	IC	If flag is true, stops execution, resets stacks, and displays the string. If flag is false then no action is taken. Example: ABORT” Error!”	x	x	x
FORGET	“word” --	S	Removes word “word”, and all words following it, from the dictionary. Cannot be used in a colon definition. Can be used in a block. The word to erase follows the word FORGET. Example: FORGET GET-RESULT	x	x	x
INTERPRET	--	S	Runs the interpreter/compiler.	x	x	x
STK?	--	S	Checks for stack underflow, and aborts if an underflow is detected, else no action is taken.	x	x	x
<<< Back to top

Built in Variables

Word	Stack Effect	Type	Description	v1.0	v1.1	v1.2
#TIB	-- address	S	Pushes the address of the #TIB variable. #TIB contains the number of characters received by EXPECT. Equivalent to SPAN.		x	x
>IN	-- address	S	Pushes the address of the current read position variable in the TIB.	x	x	x
BASE	-- address	S	Pushes the address of the current number base variable.	x	x	x
C/L	-- address	S	Pushes the address of the 'characters per line' variable. C/L is 80 when reading from the command line or 64 when reading a block.	x	x	x
CSEN	-- address	S	Pushes the address of the case sensitivity variable. When CSEN > 0 all dictionary searches shall be case sensitive. Default value is 0 (not case sensitive).			x
H	-- address	S	Pushes the address of the HERE pointer.	x	x	x
KMODE	-- address	S	Pushes the address of the keyboard scan mode variable.	x	x	x
LATEST	-- address	S	Pushes the address of the latest dictionary entry variable.	x	x	x
RP!	-- address	S	Sets the return stack pointer.	x	x	x
RP@	-- address	S	Pushes the address of the return stack pointer variable.	x	x	x
SP!	-- address	S	Sets the address of the top of the data stack.	x	x	x
SP@	-- address	S	Pushes the address of the top of the data stack variable.	x	x	x
SPAN	-- address	S	Pushes the address of the SPAN variable. SPAN contains the number of characters received by EXPECT. Equivalent to #TIB.	x
SSCROLL	-- address	S	Pushes the address of the screen scrolling variable. Determines if screen scrolling shall be used. Defaults to TRUE.	x	x	x
STATE	-- address	S	Pushes the address of the STATE variable. When STATE=0, the system is interpreting, else the system is compiling.	x	x	x
TIB	-- address	S	Pushes the address of the terminal input buffer (TIB) pointer variable.	x	x	x
WARN	-- address	S	Pushes the address of the WARN variable. Word re-definition warnings are suppressed when WARN=0			x
WRAP	-- address	S	Pushes the address of the WRAP variable. Used with SCROLL. If TRUE, SCROLL will do a wrapping scroll.	x	x	x
ZEROS	-- address	S	Pushes the address of the ZEROS variable. If ZEROS=TRUE, . U. and $. etc will display leading zeros.	x	x	x
	Note: All variables return addresses. Addresses are read with @ (fetch) and set with ! (store).
<<< Back to top

Built in Constants

Word	Stack Effect	Type	Description	v1.0	v1.1	v1.2
IOERR	-- io_error	S	Returns the last disk IO error. If 0, no error occurred.	x	x	x
FALSE	-- 0	S	Returns 0.	x	x	x
FFAIHM	-- n	S	Returns the first free address in high memory.	x	x	x
FFAILM	-- n	S	Returns the first free address in low memory.	x	x	x
HERE	-- address	S	Returns the address of the next value/xt/cfa to be compiled.	x	x	x
PAD	-- address	S	Returns an address for use as a temporary pad. The address may be in high or low memory depending on the value of HERE when PAD is executed.	x	x	x
R0	-- address	S	Returns beginning address of return stack. Used to reset return stack.	x	x	x
S0	-- address	S	Returns beginning address of data stack. Used to reset data stack.	x	x	x
TRUE	-- -1	S	Returns -1 (>FFFF hex).	x	x	x
XMAX	-- width	S	Returns the number of columns on the display. Either 32, 40 or 80.	x	x	x
<<< Back to top

String Words

Word	Stack Effect	Type	Description	v1.0	v1.1	v1.2
-TRAILING	addr len -- addr len	S	Trims a string of any trailing spaces. Modifies len accordingly.	x	x	x
.	n --	S	Displays n as a signed 16 bit integer in the current number BASE.	x	x	x
.”	--	IC	Displays the string immediately following it. For use in colon definitions only. Example: ." Hello, World!"	x	x	x
.R	n width --	S	Displays the signed number n, right justified by width characters.	x	x	x
U.R	n width --	S	Displays the unsigned number n, right justified by width characters.	x	x	x
$.	n --	S	Displays the number n as an unsigned 16 bit hexadecimal integer.	x	x	x
ASCII	-- ascii	I	If used on the command line, behaves as per CHAR. If used within a colon definition, compiles the first character of the string immediately following into the colon definition as a literal. The rest of the string is skipped.	x	x	x
CHAR	-- ascii	I	Returns the ascii value of the first character in the word immediately following. Do not use in a colon definition (unless surrounded with [ and ])	x	x	x
COUNT	addr1 -- addr2 len	S	Converts a counted string at addr1 to an address/length pair suitable for use with TYPE etc. Addr2 is addr1+1, and len is the value of the byte found at address1.	x	x	x
N>S	n -- addr len	S	Converts a number n from the stack into a string equivalent. The address addr and length len of the string are pushed to the stack. The location of the newly created string should be considered transitory (for example, calling N>S again with a different value will overwrite the string).	x	x	x
S"	-- addr len	IC	Stores a string. At run-time, the address addr and length len of the string are pushed to the stack.	x	x	x
U.	n --	S	Displays the value n as an unsigned 16 bit integer in the current number BASE.	x	x	x
<<< Back to top

Graphics Words

Word

Stack Effect

Type

Description

v1.0

v1.1

v1.2

COLOR

set fgcolor bgcolor --

Sets the character set set to the foreground colour fgcolor and the background colour bgcolor.

fgcolor/bgcolor value	Colour
0	Transparent
1	Black
2	Medium Green
3	Light Green
4	Dark Blue
5	Light Blue
6	Dark Red
7	Cyan
8	Medium Red
9	Light Red
10	Dark Yellow
11	Light Yellow
12	Dark Green
13	Magenta
14	Grey
15	White

DCHAR

address len ascii --

Defines the character with the code ascii using len cells of data found at address. Normally used in conjunction with DATA.
Example: DATA 4 $FFFF $FFFF $FFFF $FFFF 65 DCHAR re-defines the character A as a solid block.

GCHAR

y x – ascii

Returns the ascii code at cursor location y & x.

GMODE

mode --

Sets the graphics mode to mode. Valid mode values are

Mode value	Description
0	40 column text mode
1	32 column text mode
2	80 column text mode

A V9938/9958 or F18A video system is required for mode 2.

HCHAR

y x ascii count --

Draws count ascii characters on screen starting at y & x, continuing horizontally and to the right.

MAGNIFY

n --

Sets the magnification value for sprites to n. Valid values are 0 to 3, as follows:

Value for n	Description
0	8x8 pixel sprites, non-magnified
1	8x8 pixle sprites, double size
2	16x16 pixel sprites, non-magnified
3	16x16 pixel sprites, double size

PANEL

x y xlength ylength --

Logically defines a rectangular panel starting at y, x extending to ylength and xlength to be scrolled by SCROLL.

SCREEN

color --

Sets screen colour to color. Valid values are 0 to 15 as follows:

fgcolor/bgcolor value	Colour
0	Transparent
1	Black
2	Medium Green
3	Light Green
4	Dark Blue
5	Light Blue
6	Dark Red
7	Cyan
8	Medium Red
9	Light Red
10	Dark Yellow
11	Light Yellow
12	Dark Green
13	Magenta
14	Grey
15	White

SCROLL

direction --

Scrolls screen defined by PANEL in direction direction. Valid values for direction are:

Direction value	Direction
0	Left
2	Right
4	Up
6	Down

SPRVEC

sprite y x --

Defines a movement vector for sprite sprite. When SPRMOV is called, sprite sprite will move y pixels up/down and x pixels left/right. If y is negative sprite will move upwards. If x is negative sprite will move leftwards. Note: In TurboForth versions 1.0 and 1.1 this word is called SMLIST. It has been renamed in version 1.2 to SPRVEC to better describe its intention/function.

SPRCOL

sprite color --

Sets the colour of sprite sprite to color. Colours are 0 to 15. See SCREEN for colours.

SPRITE

sprite y x pattern color --

Sets sprite sprite to the y location y, the x location x assigned to pattern pattern with colour color. There are 32 sprites available, numbered from 0 to 31. There are 256 patterns available. Sprite patterns do not share their patterns with the ASCII character set ala Extended Basic, they are independant. Sprite patterns may be defined using DCHAR. When defined using DCHAR, add 256 to the ascii code passed to DCHAR.

SPRLOC

sprite y x --

Sets the location of sprite sprite to y and x.

SPRLOC?

sprite -- y x

Returns the x and y location of sprite sprite.

SPRMOV

start_sprite count

Moves the sprites starting at start_sprite and continuing for count sprites according to their vectors (see SMLIST).

SPRPAT

sprite ascii –

Sets the ascii code of sprite sprite to ascii.

VCHAR

y x ascii count --

Draws count ascii characters on screen starting at y & x, continuing downward and to the right.

<<< Back to top

Sound Words

Word	Stack Effect	Type	Description	v1.0	v1.1	v1.2
SOUND	pitch vol ch# –	S	Sets sound channel ch# to the pitch pitch with volume volume. Suitable values for pitch can be found in the editor assembler manual on page 318 (note, it is not necessary to adjust the pitch values for each channel as described in the editor assembler book, just use the values given for channel 0 – SOUND modifies the pitch internally for each channel). Valid vol values are 0 to 15 (0=loudest). Valid ch# values are 0 to 3 (3 is the noise channel). For the noise channel, the pitch field is used to describe the noise. Bits 15 and 14 (15=LSB) select the shift rate, and bit 13 selects either periodic or white noise. Other bit positions should not be used. Note SOUND does not ‘sanity check’ the values passed, so care should be taken to pass in only legal values.	x	x	x
<<< Back to top

Speech Words

Word	Stack Effect	Type	Description	v1.0	v1.1	v1.2
SAY	address count --	S	Says count words from the speech synthesizer's resident vocabulary, from the list at address address. The address list consists of addresses from the speech synthesizer's resident speech ROM.	x	x	x
STREAM	address count --	S	Streams count raw bytes to the speech synthesizer from a buffer in CPU memory beginning at address address.	x	x	x
TALKING?	-- flag	S	Checks the speech synthesiser and returns TRUE if the speech synthesizer is busy, else returns FALSE.	x	x	x
<<< Back to top

Disk Block IO Words

Word

Stack Effect

Type

Description

v1.0

v1.1

v1.2

-->

--

Loads the next block from the file currently in USE.

BLK

-- address

Contains the number of the block currently being accessed, or 0 if no block is currently being accessed. Note: BLK is a variable (it returns its address) and should be accessed via @. Writing to BLK is not generally meaningful, it is managed internally.

BLK?

buffer -- block vdp_addr

Returns the disk block stored in the buffer buffer (or 0 if the buffer is empty) and the VDP address vdp_addr of the buffer. [1].

BLOAD

block – nfb

Loads a block of raw memory from block storage that has been previously saved with BSAVE.
BLOAD checks word 0 of the block for >994A. If >994A is not found then the data in the block is determined to be of invalid format and the BLOAD operation fails, passing block to the stack. In other words, if after executing BLOAD the value on the stack is equal to block, the operation failed. BLOAD uses the header in each block and installs the payload contents (1008 bytes) at the address defined by the offset + 6 (see BSAVE for offsets). BLOAD continues loading blocks until it encounters a block that does not have >994A in offset + 0. Upon completion, BLOAD pushes the next free block number (nfb) to the stack (i.e. the last BLOADed block+1).

BLOCK

block -- vdp_address

Loads block block from the file currently in USE into a free buffer (calling FLUSH if no free buffers are available), and returns the address vdp_addr of the beginning of the buffer in VDP memory. Blocks (and their associated buffers) are exactly 1024 bytes in length.

BSAVE

start block – nfb

Saves CPU memory from start to HERE to the block beginning at block and continuing for as many blocks as are required to hold the contents of memory. Upon completion, the stack contains the next free block number (nfb) (i.e. the last block used by BSAVE+1).

BSAVEd blocks have the following format:

Byte Offset	Description
0	>994A – marker for BLOAD
2	LATEST – current value of LATEST
4	HERE – current value of HERE
6	Address of payload data
8	Reserved for future use
10	Reserved for future use
12	Reserved for future use
14	Reserved for future use
16 to 1023	1008 bytes of payload data

BUF?

block -- buffer vdp_addr

Returns the buffer number of block block, and its address in VDP memory as vdp_addr. Returns 0 0 if the block is not in memory. [1].

CLEAN

buffer --

Sets the status of buffer buffer to clean. Subsequent FLUSHes will not flush the buffer to disk. [1].

CLOAD

block –

Conditionally loads block if the word immediately following CLOAD is not found after a dictionary search.
E.g. 69 CLOAD SAMS?
The above will load block 69 if the word SAMS? is not found in the dictionary. Note, this is an immediate word. Not to be used in a colon definition. Typically, this word will only be used inside of a block, outside of a colon definition.

DIRTY

buffer --

Sets buffer buffer's status to dirty. Subsequent FLUSHes will causes the buffer to be written to disk, to the block set with SETBLK. [1].

DIRTY?

buffer -- flag

Returns TRUE if buffer buffer is dirty (i.e. changed and requires flushing to disk), otherwise returns FALSE. [1]

EMPTY-BUFFERS

--

Unconditionally sets all buffers to CLEAN. Subsequent FLUSHes will not write anything to disk.

FLUSH

--

Flushes all dirty buffers back to their respective block positions on disk. Buffers not marked as dirty are not flushed.

LIST

block --

Displays block block to the screen.

LOAD

block --

Loads (compiles/executes) block block.

MKDSK

--

Creates a block file with the name file and capacity for block blocks.
Example: MKDSK DSK1.BLOCKS 80
Use on the command line only.

SETBLK

buffer block --

Associates buffer buffer with block block. [1]

THRU

start end –

Loads blocks starting at block start thru end inclusive.

UPDATE

--

Marks the last accessed block (determinable via BLK) as dirty, such that it will be flushed to disk when FLUSH is called. FLUSH may be called either explicitly in user code, or implicitly by the kernal when all block buffers are exhausted.

USE

string –

Defines the block file to be used. A string should be set up on the stack before calling USE. Example: S” DSK1.BLOCKS” USE

WHERE

-- block

Returns the block number of a word in the dictionary. Useful in conjunction with EDIT and LIST. Eg. WHERE CPYBLK EDIT
Note that a word must be loaded (in the dictionary) before its block location can be located with WHERE. ROM resident words return 0.

[1] “buffer” is a number from 0 to 5 inclusive. There are six block buffers, located in VDP memory.

<<< Back to top

File IO Words

Word

Stack Effect

Type

Description

v1.0

v1.1

v1.2

#CLOSE

file_id

Closes the file with the file id file_id.
Where a file is opened thus: MYFILE #OPEN the following will close the same file: MYFILE #CLOSE

#EOF?

file_id – t|f

Returns TRUE if file file_id is currently positioned at the end of the file.

#GET

buff_addr file_id – t|f

Reads a line of input from the file specified by file_id. The address of an appropriately sized buffer (buff_addr) must be supplied. If the read is successful, the buffer at buff_addr is filled with the data read from the input device, with the first byte being the length count of the data immediately following it. This can be converted into a address/length pair with COUNT.
Returns FALSE if successful or TRUE if not successful. This allows trapping with ABORT" as follows:
MYFILE #GET ABORT" Could not read from file"
If the read fails, IOERR is set to the error code, otherwise it is set to 0.

#OPEN

file_id – t|f

Opens a file with the file name and attributes specified in the buffer starting at file_id. The buffer (actually a PAB) is set-up with FILE. E.g.
FBUF: SERIAL
S" RS232.BA=9600 DV80O" SERIAL FILE
SERIAL #OPEN
The above attempts to open the serial port for output as a Display Variable 80 type file. A file buffer called SERIAL is declared (using FBUF:), and this is fed to FILE (along with the string that describes the file). FILE builds the PAB in the buffer named SERIAL.

#OPEN leaves a FALSE on the stack if the file was opened successfully. If the file could not be opened, it leaves a TRUE on the stack. This allows easy trapping with ABORT" as shown below:
SERIAL #OPEN ABORT" Can't open file"
In the event of a file error, IOERR can be read to get the DSR error code. If IOERR returns -1 (>FFFF) then this means that no free file IO slots were found. A maximum of 3 open files are supported (2 if block files are also to be used). Note that block files are immediately closed after they are accessed for either reading or writing, so 3 generic file I/O streams are available when no blocks files are being used.

#PUT

buf_addr len file_id – t|f

Writes a string from buffer_addr with length len to the file represented by file_id. Returns FALSE if successful, else returns TRUE. This can be trapped with ABORT"
Example:
FBUF: DISK-FILE
S" DSK1.TEST DV80SO" DISK-FILE FILE
DISK-FILE #OPEN ABORT" Cannot open disk file for output"
S" This is a test" DISK-FILE #PUT ABORT" Cannot write to disk"
DISK-FILE #CLOSE

#REC

record file_id –

Sets the record number of file referenced by file_id to record record for reading or writing relative files. The file should be opened prior to using #REC.

FBUF:

–

Declares a file buffer, used by FILE to build the PAB (Peripheral Access Block) required for file access. Internally, FBUF: ALLOTs 42 bytes starting at HERE. Later, FILE, as it parses the file-name and file descriptor, will build the PAB in the buffer previously declared with FBUF: E.g.
FBUF: DISK-FILE
S” DSK1.README DV80SI” DISK-FILE FILE
Here, a buffer called DISK-FILE is declared. FILE is used to build the PAB for a file on DSK1 called README, declared as a DV80 file, in sequential input mode. Of the 42 bytes allotted, 12 are used for the PAB and internal pointers, leaving 30 characters for the file-name, which allows enough space for hard disk systems with subdirectories etc. FBUF: should not be used inside a colon definition.

FILE

string –

Builds a PAB (Peripheral Access Block) in a buffer previously declared with FBUF: according to the string descriptor supplied via the stack. E.g.:
S" PIO.CR DV80O" PRINTER FILE
The above defines a file variable (previously declared with FBUF:) called PRINTER which references the PIO device. Subsequent file IO words that wish to send data to the PIO shall use the file variable name to reference it, e.g.

PRINTER #OPEN DROP	(open PIO and drop success/fail flag)
S" HELLO WORLD" PRINTER #PUT DROP	(write HELLO WORLD to the PIO and drop success/fail flag)

Internally, FILE variables build a PAB in CPU memory which will be used by #OPEN and all File IO words. Word 0 of the reserved memory is used to point to the actual PAB in VDP memory. The VDP location of the PAB is not determined until #OPEN is executed. The string which specifies the file name and options is defined as below. The file-name *must* come first followed by at least one space character. After that, the file options can come in any order.

File Options	File Type
F	Fixed record type
V	Variable record type

D	Display data type
L	Internal data type*

U	Update file mode
O	Output file mode
I	Input file mode
A	Append file mode

S	Sequential file type
R	Relative file type

*Note that Internal type files require L - this is because I is used to specify INPUT mode.

<<< Back to top