Forth Dictionary


Following a comprehensive dictionary on forth words available with MineOS.
(which was introduced with release RP2pr5b1 as version 1.0 and got upgraded to version 1.1 with current RP2pr5b2).

Note: This dictionary is still work-in-progress and can contain bugs or misleading information which can result in unwanted behavior!


Stack notation


To describe the syntax for each word, a stack notation as follows will be used throughout this document:
( <Input> -- <Output> )
Left side <Input> lists all input parameters a word expects, if any, including the order.
The -- is used as a separator and, if not stated else, denotes the word itself (which will, when executed, read, and therefore remove its input parameters from right to left).
Right side <Output> describes all output parameters pushed onto the stack, also optional.

Here are a few examples to get a hold onto it:
Syntax
Description
( -- )
Indicates no change to stack at all
( n -- )
would indicate an existing value is removed from stack
( -- n )
would indicate a new value gets pushed onto stack, without modification of any value currently on stack
( n1 -- n )
Combination of ( n -- ) and ( -- n ) where an existing value n1 gets replaced by n
( n1 n2 -- n )
Two existing values n1 and n2 are replaced by a single value n

Where appropriate, a prefix is used to denote the type expected. If same type is used more than once, a sequence number is added to define parameter ordering:
Prefix
Description
Example(s)
n
A signed integer value with normal precision (16 bit)[1]
+ ( n1 n2 -- n )
to describe an addition
d
An signed integer value with double precision (32 bit)[2]
- ( d1 d2 -- d )
to describe a subtraction
r
A floating-point value with ? single/double precision ?[3]
* ( r1 r2 -- r )
to describe a multiplication
b
A byte value (8 bit)
AND ( b1 b2 -- b )
to describe a logical AND operation
addr
A memory address in general
! ( n addr -- )
to describe a write operation into memory[4]
f
A boolean flag of either TRUE (<>0) or FALSE (=0)[5]
= ( n1 n2 -- f )
to describe the equality comparison operator

Besides the prefixes above, a % as input indicates an empty stack, if used on output side, it indicates that stack will be erased after current word finishes execution.
Furthermore, a ... indicates a sequence of values, so, for example, ( nN...n1 -- ) describes N values to be present on stack.

Further note: Any term value denotes a 16 bit signed integer until stated else, and any term char (or character) equals a single byte.


Terminal interaction


Word
Syntax
Description
Example(s)
Version
PAGE
( -- )
Clears screen and repositions cursor into upper left corner
PAGE
1.0+
SCROLL
( -- )
Scrolls terminal content up by one line
SCROLL
1.0+
AT-XY
( n1 n2 -- )
Moves cursor to x=n1 and y=n2
0 0 AT-XY
will move cursor into upper left corner
1.1+
EMIT
( b -- )
Emits given ASCII char b at current cursor position and advances cursor position by one
(will move to next line if eond of line reached, scrolling if needed)
65 EMIT
will print an A
1.0+
CR
( -- )
Does a carriage return, will scroll screen by one line if already at bottom line
CR
1.0+
SPACE
( -- )
Emits a space character
SPACE
1.0+
BS
( -- )
Emits a backspace, moving the cursor backward and erasing the character beneath it
BS
1.0+
KEY?
( -- f )
Checks for a key press, will return either TRUE or FALSE
(bugged with release pr5b1[6] , fixed with pr5b2)
BEGIN <code> KEY? UNTIL
1.0+
KEY
( -- b )
Wait for a key press and returns ASCII code of key pressed
KEY 32 = IF <code> THEN
1.0+
.
( n -- )
Pulls last value from stack and print it
1 2 3 .
will print 3
1.0+
U.
( n -- )
Unsigned version of .
-32 U.
will print 65504
(which equals FFE0)
1.1+
."
." <string>"
Print string given
(compile mode only, string will be stored within current definition)
." Hello World"
will print Hello World
1.0+
TYPE
( addr -- )
Output string starting at addr onto terminal[7]

1.0+
ACCEPT
( addr n -- addr )
Accepts user input and copies at most n-1 chars to a buffer at addr[8]

1.0+

Note that those words will always operate on terminal stored in TERMADDR.


Stack related


Word
Syntax
Description
Example(s)
Version
DEPTH
( -- n )
Returns the current number of values on stack
1 2 3 DEPTH .
will print 3
1.0+
.S
( -- )
Prints all values currently on stack
(does NOT remove any value)
1 2 3 .S
will output 1 2 3
1.0+
DUP
( n -- n n )
Duplicates last value on stack
2 DUP .S
will print 2 2
1.0+
?DUP
( n -- n n )
Same as DUP, but duplicates only if last value isn't zero
0 ?DUP .S
will print 0
1.0+
2DUP
( n1 n2 -- n1 n2 n1 n2 )
Duplicates the last 2 values on stack
1 2 3 2DUP .S
will print 1 2 3 2 3
1.0+
DROP
( n -- )
Drops last value from stack
1 2 DROP .S
will print 1
1.0+
2DROP
( n1 n2 -- )
Same as DROP, but drops last 2 values
1 2 3 2DROP .S
will print 1
1.0+
SWAP
( n1 n2 -- n2 n1 )
Swaps the last 2 values
1 2 3 SWAP .S
will print 1 3 2
1.0+
2SWAP
( n1 n2 n3 n4 -- n3 n4 n1 n2 )
Nearly the same as SWAP, but instead, it will swap the last 2 values
1 2 3 4 2SWAP .S
will print 3 4 1 2
1.1+
PICK
( nN...n0 nI -- nN...n0 n )
Picks given value nI from stack and pushes it again.
(will only remove the pick index nI, but NOT the picked value itself)
(position is counted backwards, so an nI of 0 would denotes n0, nI=1 denotes n1, ...)
1 2 3 4 1 PICK .S
will print 1 2 3 4 3
1.0+
OVER
( nN...n2 n1 -- nN...n2 n1 n2 )
Same as 1 PICK
1 2 3 4 OVER .S
will print 1 2 3 4 3
1.0+
2OVER
( nN...n3 n2 n1 -- nN...n3 n2 n1 n3 )
Same as 2 PICK
(different to ANS forth where one would expect 2 values being copied over)
1 2 3 4 2OVER .S
will print 1 2 3 4 2
1.0+
ROT
( n1 n2 n3 -- n2 n3 n1 )
Rotates the three top values of stack leftwise.
1 2 3 ROT .S
will print 2 3 1
1.0+
-ROT
( n1 n2 n3 -- n3 n1 n2 )
Inverse of ROT by rotating rightwise
1 2 3 -ROT .S
will print 3 1 2
1.0+
NIP
( n1 n2 -- n2 )
Removes the value before last value
1 2 3 NIP .S
will print 1 3
1.0+
TUCK
( n1 n2 -- n2 n1 n2 )
Duplicate last value and insert it before the last 2 values
(think of it as a DUP followed by a -ROT)
1 2 TUCK .S
will print 2 1 2
1.0+
>R

Pops a value from stack and pushes it onto R-stack[9]

1.0+
R>

Pops a value from R-stack and pushes it onto stack

1.0+
SP@
( -- addr )
Returns current stack pointer
ABORT
SP@ .
will print 512 (initial value after bootup)
1.0+
SP!
( addr -- )
Set stack pointer
512 SP!
will reset stack to its initial value[10]
1.0+
0SP
( -- % )
Reset stack pointer

1.1+
RP@
( -- addr )
Same as SP@, but interacts with R-stack

1.0+
RP!
( addr -- )
Same as SP!, but interacts with R-stack

1.0+


Control flow


Word
Syntax
Description
Example(s)
Version
EXIT
( -- )
To immediately exit a word, continuing execution at previous word (if any)
KEY? IF EXIT THEN
1.0+
ABORT
( -- % )
Will abort execution and clears stack upon return
KEY? IF ABORT THEN
1.0+
DO
( n1 n2 -- )
Loop from n2 up to n1 (excluding)
(when using with n2=n1, you loop will execute 65535 times. See ?DO below for handling such cases)
: hello 10 0 DO ." Hello World" CR LOOP ;
hello
will print Hello World+CR 10 times
1.0+
?DO
( n1 n2 -- )
Nearly the same as DO, but checks the condition before entering the loop

1.0+
LOOP
( -- )
Denotes the end of a loop started by DO or ?DO
10 0 DO <code> LOOP
1.0+
+LOOP
( n -- )
Same as LOOP, but allows for using a user-definable increment/decrement value
: hello 10 0 DO ." Hello World" CR 2 +LOOP ;
hello
will print Hello World+CR 5 times
1.0+
LEAVE
( -- )
To exit a loop, will continue execution after the loop end marker.
(can only be used for counted DO loops; for uncounted you may want to use multiple WHILE)
10 0 DO <some loop code> IOX@ 3 AND 3 = IF LEAVE THEN <more loop code> LOOP
<code executed afterwards>
will execute at most 10 times or until both white+orange cables are active
1.0+
BEGIN
( -- )
Denotes the starting point for an UNTIL, WHILE or AGAIN loop
BEGIN KEY? UNTIL
will wait until there's a keypress available
1.0+
UNTIL
( f -- )
Loops until flag f = TRUE
BEGIN IOX@ 32 AND 0= UNTIL
waits until input on bit 5 is off
1.0+
WHILE
( f -- )
Loops while flag f = TRUE
BEGIN <code1> WHILE <code2> REPEAT
executes code1, tests top of stack for truth. If it is true, executes code2 and continues loop; else, continues after REPEAT
1.0+
AGAIN
( -- )
Loops forever, one have to use EXIT or other means to break this loop
BEGIN <code> AGAIN
1.0+
REPEAT
( -- )
Used in BEGIN ... WHILE ... REPEAT loop, see above
(Actually, just a shortcut for AGAIN THEN; one can write more funky code with this knowledge,
such as BEGIN ( code for every iteration ) ( test for WHILE ) WHILE ( test for UNTIL ) UNTIL ( UNTIL closes the loop ) ELSE ( This will be printed only if exited via WHILE ) THEN ).
\ Another funky example without REPEAT
BEGIN ( control: loop )
KEY? 0= WHILE ( control: first-exit loop )
IOX@ 1 AND 0= WHILE ( control: first-exit second-exit loop )
AGAIN
ELSE ." White wire is on" THEN
ELSE ." Key pressed" THEN
1.0+
UNLOOP
( -- )
Cleans up one DO/LOOP
(one must cancel every DO/LOOP using UNLOOP when using EXIT)
10 0 DO <some code> IOX@ 3 AND 3 = IF UNLOOP EXIT THEN <more code> LOOP
will execute at most 10 times or until both white+orange cables are active
1.0+
IF
( f -- )
Executes code following if f = TRUE, skips it resp. executes optional ELSE branch if f = FALSE
KEY? IF ." Key pressed" CR THEN
1.0+
THEN
( -- )
Denotes end of an IF condition

1.0+
ELSE
( -- )
Denotes an ELSE branch
KEY 32 = IF <if-block> ELSE <else-block> THEN
1.0+

Please note that not all control flow words do work in intermediate mode.


Comparison operators


Word
Syntax
Description
Example(s)
Version
0=
( n -- f )
f = TRUE if n = 0

1.0+
0<>
( n -- f )
f = TRUE if n <> 0

1.0+
0<
( n -- f )
f = TRUE if n < 0

1.0+
<>
( n1 n2 -- f )
f = TRUE if n1 <> n2

1.0+
<
( n1 n2 -- f )
f = TRUE if n1 < n2

1.0+
U<
( n1 n2 -- f )
Unsigned version of <

1.1+
>
( n1 n2 -- f )
f = TRUE if n1 > n2

1.0+
U>
( n1 n2 -- f )
Unsigned version of >

1.1+
<=
( n1 n2 -- f )
f = TRUE if n1 <= n2

1.0+
>=
( n1 n2 -- f )
f = TRUE if n1 >= n2

1.0+
=
( n1 n2 -- f )
f = TRUE if n1 = n2

1.0+


Arithmetic operators


Word
Syntax
Description
Example(s)
Version
+
( n1 n2 -- n )
Addition: n = n1 + n2

1.0+
-
( n1 n2 -- n )
Subtraction: n = n1 - n2

1.0+
*
( n1 n2 -- n )
Multiplication: n = n1 * n2

1.0+
U*
( n1 n2 -- n )
Unsigned version of *

1.1+
M*
( n1 n2 -- nL nH )
Same as *, but returns a double precision value with low word as nL and high word as nH
1234 2345 M* .S
results in 10146 44
(10146+65536*44=2893730)
1.0+
UM*
( n1 n2 -- nL nH )
Unsigned version of M*

1.1+
SM/REM
( n1L n1H n2 -- nR n )
Double precision symmetric division: n = n1 / n2 with remainer as nR
10146 44 1234 SM/REM .S
results in 0 2345, and
10147 44 1234 SM/REM .S
results in 1 2345, and
10145 44 1234 SM/REM .S
results in 1233 2344
1.0+
FM/MOD
( n1L n1H n2 -- nR n )
Same as SM/REM, but floored

1.0+
UM/MOD
( n1L n1H n2 -- nR n )
Unsigned version of SM/REM

1.1+
/MOD
( n -- nR nQ )
Modulo operator, nR denotes remainder and nQ the quotient
42 10 /MOD .S
will print 2 4
1.0+
/
( n1 n2 -- n )
Short version of /MOD which returns only the remainder
10 3 / .S
will print 1
1.1+
MOD
( n1 n2 -- n )
Counterpart of /, returns quotient instead
10 3 MOD .S
returns 3
1.1+
1+
( n1 -- n )
Increments value n1 by 1 and pushed it back onto stack
41 1+ .
will print 42
1.0+
1-
( n1 -- n )
Decrements value n1 by 1 and pushed it back onto stack
43 1- .
will print 42
1.0+
NEGATE
( n1 -- n )
Sign inversion of n1
-42 NEGATE .
will print 42, and
42 NEGATE .
will print -42
1.0+
MAX
( n1 n2 -- n )
Returns max( n1, n2 )
42 33 MAX .
will print 42
1.0+
MIN
( n1 n2 -- n )
Returns min( n1, n2 )
42 33 MIN .
will print 33
1.0+
S>D
( n -- n1 n2 )
Extend single-precision value n to double-precision, with n2 0 or -1, latter reflects that n was a negative number
(missing in pr5b2, maybe a bug)
42 S>D .S
will print 42 0, and
-42 S>D .S
will print -42 -1
1.0 only


Binary operators


Word
Syntax
Description
Example(s)
Version
AND
( n1 n2 -- n )
Returns n1 AND n2
1 3 AND
will return 1
(00000001 & 00000011 = 00000001)
1.0+
OR
( n1 n2 -- n )
Returns n1 OR n2
1 2 OR
will return 3
(00000001 | 00000010 = 00000011)
1.0+
XOR
( n1 n2 -- n )
Returns n1 XOR n2
1 3 XOR
will return 2
(00000001 ^ 00000011 = 00000010)
1.0+
INVERT
( n1 -- n )
Returns inverse of n1
HEX AA INVERT .
will print 55
(10101010 -> 01010101)
1.0+
2*
( n1 -- n )
Multiplies value n1 with 2
(a so-called left-shift operation)
1 2*
will result in 2
1.0+
2/
( n1 -- n )
Divides value n1 by 2
(a right-shift operation)
4 2/
will result in 2
1.0+
<<
( n1 n2 -- n )
Multiplies value n1 with 2 n2 times
(a leftwise shift over n2 bits)
1 3 <<
will result in 8
1.0+
U>>
( n1 n2 -- n )
Divides value n1 by 2 n2 times
(a rightwise shift over n2 bits)
8 3 U>>
will result in 1
1.0+


Variables, constants and alike


Word
Syntax
Description
Example(s)
Version
VARIABLE

Allocates a named variable with a default value of 0
VARIABLE foo
1.0+
CONSTANT

Allocates a named constant using value specified [11] [12]
42 CONSTANT foo
1.0+
CREATE

Create a new word with options following[13]
CREATE foo 10 CELLS ALLOT
creates an array named foo with 10 (un-initialized) values in total
1.0+
@
( addr -- n )
Reads a value from given address addr[14]
foo @ .
will print value of variable foo
1.0+
!
( n addr -- )
Writes value n into address addr
42 foo !
will set variable foo to hold 42
1.0+
C@
( addr -- b )
Same as @, but reads a byte value from given address addr
foo C@
1.0+
C!
( b addr -- )
Same as !, but writes a byte value b into address addr
42 foo C!
1.0+
+!
( n addr -- )
Increments value addr points to by n

1.0+
-!
( n addr -- )
Decrements value addr points to by n

1.0+
CELL
( -- n )
Returns size of a value[15]
CELL .
will print 2
1.0+
CELLS
( n1 -- n )
Returns size of n1 values
10 CELLS .
will print 20
(10 values each 2 bytes wide)
1.0+
ALLOT
( n -- addr )
Allocates n bytes of memory and returns start of block as addr[16]
10 CELLS ALLOT
allocates 10 values (20 bytes), un-initialized
1.0+
,
( n -- )
Allocates a value at end of program code and assigns it n
(just a short version of n CELL ALLOT !)

1.0+
,C
( b -- )
Same as , above, but allocates and stores a byte value instead
(short for b 1 ALLOT C!)

1.0+
,S
( addr -- )
Same as , above, but allocates and copies a string which source is stored at addr (incl. zero-term.)

1.0+


Predefined variables & constants


Word
Type
Syntax
Description
Example(s)
Version
TRUE
C
( -- f )
Will give you the value for a TRUE flag
TRUE .
will print -1
1.0+
FALSE
C
( -- f )
Will give you the value for a FALSE flag
FALSE .
will print 0
1.0+
BL
C
( -- n )
Will give you the ASCII value for a blankspace
BL .S
will print 32
1.0+
I
C
( -- n )
Will return current counter for (inner) loop
<do> I . <loop>
1.0+
J
C
( -- n )
Will return current counter for (outer) loop
<outer DO> <inner DO>
J 10 * I + .
<inner LOOP> <outer LOOP>
1.0+
RADIX
V
( -- addr )
Current radix used to parse and display values
RADIX @ . \ will print 10 (default after boot)
16 RADIX ! \ will switch to hexadecimal radix[17]
1.0+
SP0
C
( -- n )
Returns stack start address
SP0 .
will print 512
1.0+
RP0
C
( -- n )
Returns R-stack start address
RP0 .
will print 768
1.0+
STATE
V
( -- addr )
Current compiler state
(0=intermediate mode, 1=compile mode)

1.0+
VOCAB
V
( -- addr )
Address of last known word

1.0+
TOP
V
( -- addr )
Top of available memory
(size of memory installed - 1)
HEX TOP @ .
will print 1FFF[18]
1.1+
TERMADDR
V
( -- addr )
Current terminal address
(after boot up this reflects the dip settings on your rpc8/e)

1.0+
DISKADDR
V
( -- addr )
Current disk drive address
(after boot up this reflects the dip settings on your rpc8/e)

1.0+
IOXADDR
V
( -- addr )
Current IO expander address

1.0+
SORTADDR
V
( -- addr )
Current sortron address

1.2 XP
SCRATCH
C
( -- n )
Position of scratch buffer
(several uses, for example, UITOA uses it build string representation, DISKID will fetch the id into it, ...)

1.0+
TIB
C
( -- n )
Pointer to terminal input buffer

1.0+
TIBPTR
V
( -- addr )
Pointer to remaining string to interpret in terminal input buffer

1.0+
(HERE)
V
( -- addr )
Address of memory position where new program code gets stored

1.0+
(blkbuf)
V
( -- addr )
Stores the block buffer address

1.1+
(1.2 XP only)
(blkno)
V
( -- addr )
Stores the currently active block number

1.1+
(1.2 XP only)
(blkup)
V
( -- addr )
Stores the block modified flag. This flag is set but not tested anywhere. If (blkno) is not zero the buffer is always treated as modified.

1.1+
(1.2 XP only)
(blkload)
V
( -- addr )
Used internally by LOAD to hold buffer address while iterating lines.

1.2 XP
Type: V = Variable (always returns an address, so use @ to get its value), C = Constant (will return value directly, no need for using @)


Redbus interaction


Word
Syntax
Description
Example(s)
Version
RBP!
( n -- )
Used to select your current redbus device
2 RBP!
would select, if using default id's, the disk drive
1.0+


IO expander


IOX@
( -- n )
Used to read current inputs from an I/O-expander, returned as n
IOX@ .
would print current input state
1.0+
IOX!
( n -- )
Used to set I/O-expander output pins to bits defined by n
1 IOX!
switches only white output to on
(resp. keeps it on if previously set),
all other colors are switched off
1.0+
IOXSET
( n -- )
Used to set individual bits with I/O-expander, without changing bits not given by n
1 IOXSET
switches only white output on,
other outputs will keep current state
1.0+
IOXRST
( n -- )
Used to clear individual bits with I/O-expander, without changing bits not given by n
1 IOXRST
switches only white output off,
other outputs will keep current state
1.0+

Note that those words will always operate on IO expander stored in IOXADDR.


Disk-related words


Word
Syntax
Description
Example(s)
Version
DISKNAME"
DISKNAME" <name>"
Names a disk

1.0+
DISKID

Will print the unique disk-id[19]

1.0+
SAVE"
SAVE" <name>"
( -- addr )
Names your disk and writes memory content (current FORTH system) onto disk
(starting at address 0x500 up to current value of HERE, also rounded upwards to next 128 byte boundary to completely fill a sector). The upper address of memory written is returned. The return value doesn't appear to have a purpose and may be a bug.

1.0+
DISKWS
( addr n -- )
Write 128 bytes of memory at addr into disk sector n. To test the result immediately follow with 898 C@, if this byte is zero the operation succeeded.

1.0+
DISKRS
( addr n -- )
Read disk sector n (128 bytes) to memory at addr. To test the result immediately follow with 898 C@, if this byte is zero the operation succeeded.

1.1+
BLOCK
( n -- addr )
Load block n into memory and make it the currently active block, returning address of first bytes read in addr[20] [21] (will also flush a previously active block to disk before loading another one)
example
1.1+
(1.2 XP only)
LIST
( n -- )
As BLOCK, but lists the block contents afterwards
(note that current implementation of LIST will change current radix to decimal)
1 LIST
will list content of first block
1.1+
(1.2 XP only)
LOAD
( n -- )
As BLOCK, but executes code contained after loading
(can be used to compile code stored in blocks but v1.1 has limitations. See details or patch).

1.1+
(1.2 XP only)
WIPE
( -- )
Wipe all contents in currently active block using blankspaces

1.1+
(1.2 XP only)
FLUSH
( -- )
Flushes currently active block to disk

1.1+
(1.2 XP only)
REVERT
( -- )
Reverts to data from disk, loosing all changes to currently active block

1.1+
(1.2 XP only)
UPDATE
( -- )
Forces current block to be marked as modified. This modified flag is not implemented, the block handling mechanism always assumes it set to modified. See here.

1.1+
(1.2 XP only)
PP
<line> PP <content>
Edit line <line>[22] , replacing any existing content with <content>(content will be padded using spaces to erase any remain on line)
0 PP ( Just a comment )
1.1+
(1.2 XP only)

Note that those words will always operate on disk drive stored in DISKADDR.


Sortron-related words


Word
Syntax
Description
Example(s)
Version
SORTCMD
( b -- )
Instigates the sortron operation of b through red bus and waits for the result. If an error occurs ABORT is called. The call does not return until the operation completes. (If the sortron is not powered it will hang).
4 SORTCMD
\ will run the Match command
1.2 XP
SORTCOLOR@
( -- b )
Reads the current output filter color. If zero, no color filtering is applied.

1.2 XP
SORTCOLOR!
( b -- )
Sets the current output filter color. If zero, no color filtering is applied.
1 SORTCOLOR! \ set to white
1.2 XP
SORTDMG@
( -- n)
Returns the current damage level of the item in the selected slot of the attached inventory. The slot must first be selected with a call to SORTSLOT@. (Testing a sonic screwdriver returns how many times it has been used).

1.2 XP
SORTDMGMAX@
( -- n)
Returns the maximum possible damage level of the item in the selected slot of the attached inventory. The slot must first be selected with a call to SORTSLOT@. If the item does not support damage zero is returned.
SORTDMG@ SORTDMGMAX@ U< IF ... THEN
1.2 XP
SORTINCOL@
( -- b )
Reads the current input filter color. If zero, no color filtering is applied.

1.2 XP
SORTINCOL!
( b -- )
Sets the current input filter color. If zero, no color filtering is applied.
1 SORTINCOL! \ set to white
1.2 XP
SORTMATCH
( b -- )
Waits until a given quantity of items has passed through an in-line sortron. Both the currently set item and color filters are respected. The call does not return until the given quantity has been passed. Calls SORTCMD.
6 SORTMATCH \ wait for 6 items.
1.2 XP
SORTPAT@
( -- d )
Reads the current item identifier that an in-line sortron will accept from the input tube, and passed through to the output tube. If this value is zero any item type may pass. d is the double word (32 bit) unique identifier of the item type.
SORTPAT@ U. U. \ the current item filter
1.2 XP
SORTPAT!
( d -- )
Sets the current item identifier that an in-line sortron will accept from the input tube, and passed through to the output tube. If this value is zero any item type may pass. d is the double word (32 bit) unique identifier of the item type. Input and output color filters are also respected and applied.
0 0 SORTPAT! \ clears the item filter
1.2 XP
SORTPULL
( b n -- b )
Injects a quantity (b) of items from the slot (n) in the attached inventory into the output tube. The count actually injected is return (may be less if not enough items in slot). Calls SORTCMD.
6 0 SORTPULL . \ 6 items at 1st slot and print count
1.2 XP
SORTSLOT@
( n -- d b )
Returns the unique identifier and quantity of the item in the slot (n) of the attached inventory. d is the double word (32 bit) unique identifier of the item type. b is the quantity. Calls SORTCMD.
0 SORTSLOT@ . U. U. \ prints 1st slot count and item
1.2 XP
SORTSLOTS
( -- n )
Returns the number of slots in the inventory attached to the sortron device. Calls SORTCMD.
SORTSLOTS . \ prints slots
1.2 XP

Note that those words will always operate on the sortron stored in SORTADDR.


Miscellaneous words


Word
Syntax
Description
Example(s)
Version
EXECUTE
( addr -- )
Set program counter to addr and executes
' TEST EXECUTE
will execute TEST
1.0+
INTERPRET
( addr -- )
Processes the string at addr (as a command line). The string must be null terminated. The system uses INTERPRET to process command line input. It respects the current mode (intermediate or compile) and acts accordingly.
: TRY " PAGE WORDS" INTERPRET ;
\ running TRY will run the string as a command line
1.0+
WORDS
( -- )
Print a list of all words known
(will start with last one defined)

1.0+
HIDE
--
Will hide last word defined, preventing it's execution

1.0+
REVEAL
--
Will reveal last word defined

1.0+
ERASE
ERASE <word>
Delete word given
(by rewinding both VOCAB and HERE pointers,
this will also delete any word defined afterwards)
: foo1 <code> ;
: foo2 <code> ;
ERASE foo1
will erase both foo1 and foo2
1.0 only
(renamed to FORGET)
FORGET
FORGET <word>
Delete word given
(by rewinding both VOCAB and HERE pointers,
this will also delete any word defined afterwards)
: foo1 <code> ;
: foo2 <code> ;
FORGET foo1
will erase both foo1 and foo2
1.1+
HEX
( -- )
Will switch RADIX to 16

1.0+
DECIMAL
( -- )
Will switch RADIX to 10

1.0+
TICK
( -- )
Wait 1 minecraft tick (1/20 second)

1.0+
TICKS
( n -- )
Wait given amount of ticks
20 TICKS
will wait 1 second
1.0+
TIMES
n TIMES <word>
Repeat given word n times
10 TIMES SPACE
will print 10 spaces
1.0+
HERE
( -- n )
Memory position where new program code gets stored

1.0+
FREE
( -- n )
Returns amount of free memory
FREE .
will print 600[23]
1.1+
[

Switches into compile mode

1.0+
]

Switches back into intermediate mode

1.0+
:
: <word>
Will start defining a new word, any text after <word> will be compiled instantly[24]
: xx DUP * ;
1.0+
;

Denotes the end of a word definition

1.0+
(
( <comment>)
Adds a comment up to a closing parenthesis ) [25]
( I'm just a comment )
1.1+
\
\ <comment><CR>
Similar to (, but ends at first CR encountered

1.1+
STRLEN
( addr -- n )
Returns the length n of a string given by addr

1.0+
RSTRLEN
( addr -- n )
Nearly the same as STRLEN, but traverses backwards

1.0+
STRCMP
( addr1 addr2 -- n )
Compares two strings at addr1 and addr2, returning either
1 if str1 <> str2 or 0 if str1 = str2

1.0+
ISNUM
( b -- f )
Tests the character against the current RADIX and returns TRUE if it is a signed digit (only a preceding - is recognized, + will return FALSE)

1.0+
ISUNUM
( b -- f )
Tests the character against the current RADIX and returns TRUE if it is an unsigned digit

1.0+
ATOI
( addr -- n )
Convert string at addr into a signed value returned as n
(using current RADIX)

1.0+
UATOI
( addr -- n )
Same as ATOI, but only for unsigned values
(using current RADIX)

1.0+
UITOA
( n -- addr )
Converts unsigned value n into a string and returns string address
(using current RADIX)
example
1.0+
MEMCMP
( addr1 addr2 n1 -- n )
Compares two memory blocks at addr1 and addr2, both of given length n1. Returns either
1 if block1 <> block2 or 0 if block1 = block2

1.0+
FILL
( addr n b -- )
Fills memory block at addr with length n1 using a byte value of b
CREATE foo 64 ALLOT
foo 64 0 FILL
1.0+
MOVE
( addr1 addr2 n -- )
Copies n bytes of memory from addr1 to addr2. The copy is always in a forward direction, copying to a higher address in an overlapping buffer will not copy correctly.

1.0+
SPLIT
( addr b -- addrN addrS )
Split string given by addr using separator b skipping any leading separators automatically.
Will return any string found as addrS (zero-term. by replacing separator found), addrN points to end of string + 1 and can be used to call SPLIT again

1.0+
FIND
( addr1 -- addr )
Returns the executable address of the word in the system's dictionary identified by the name in the string at addr1. The returned address is suitable to be used with EXECUTE to run the word. If the name is not found zero is returned. (This word functions correctly but alternatives exists which work much faster. See patch.)
: TEST " WORDS" FIND EXECUTE ;
\ will run WORDS
1.0+
WORD
addr -- addrN addrS )
Parse string given by addr to find next word, halts on a whitespace (space, tab, CR, LF) but skips leading ones automatically.
addrS will contain start of word (first trailing whitespace encountered is replaced by a zero to term. string properly),
addrN points to end of word (so addrN-addrS can be used to compute string length), can be used, for example, to call WORD again
TIB WORD .S
will return 131 128, thats our TIB from command line
1.0+
TIBWORD
( -- addrS )
Nearly the same as WORD, but uses current TIB pointer as addr and advances it afterwards,
returning only start of string in addrS

1.0+
TIBSPLIT
( b -- addrS )
Split the input stream (at TIBPTR) using separator b.
Calls SPLIT, returns the first string as addrS and updates TIBPTR to point behind that.

1.0+
TIBFIND
TIBFIND <word>
Searches for given word, returns address of word or prints an error message[26]
TIBFIND RADIX .
will print 2660 (as with MineOS 1.0)
1.0 only
(renamed to ')
'
' <word>
Searches for given word, returns address of word or prints an error message[27]
' RADIX .
will print 2859 (as with MineOS 1.1)
1.1+
"
" <string>"
Will inject string following into program code (incl. zero-term.), advancing HERE. When executed the string's address is pushed onto the stack. In short, a string literal is stored in the code. Can be used only in compile mode.
(in contrast to .", this will NOT print the string given when word is executed)
: STR " String" ;
STR TYPE \ will print the string
1.1+


Debugging


Word
Syntax
Description
Example(s)
Version
MMUDBG
( n -- )
Writes value n into minecraft log (debug mode only?)

1.0 only
>NAME
( addr1 -- addr )
Find name (returned as addr) for given subroutine address addr1

1.1+
NAME>
( addr1 -- addr )
Counterpart of >NAME, advances from name at addr1 to first opcode[28]

1.1+


Internal words


You are advised not to use them directly (if you don't know what you're doing, to be precise ^^).
Word
Syntax
Description
Example(s)
Version
DOCON

Implementation for constant access, pushes actual value onto stack by automatically dereferencing memory address

1.0+
DOVAR

Implementation for variable access, pushes variable address onto stack

1.0+
QUIT
( -- % )
QUIT sits at the bottom of the system and represents the endless command line. QUIT never returns. QUIT does not perform a full system reset, ABORT should be used for this purpose.

1.0+
HEADER

Used to inject header data for a forth word, also increments HERE and changes VOCAB to point to this new word

1.1+
PROBE

Probes RAM to find max. amount installed and returns maximum memory address
(so 8k of RAM (8192 bytes) will return a value of 8191). COLD sets TOP with the value returned from PROBE. Once booted use TOP @ instead.
(If more than one extra RAM units are installed PROBE corrupts memory from 16K. See fix)

1.1+
COLD
( -- )
Starts the OS, sets up DISKADDR and TERMADDR, probes memory size and prints boot message

1.0+
DOES>
( -- )
Updates semantics of CREATEd word.
The default semantics of CREATEd word is to put its allocated address onto the stack, and it cannot be overwritten.
However, this can be extended with DOES> word.
DOES> reads all tokens up to ; (semicolon) and adds found words to interpretation semantic of the most recently CREATEd word.
When DOES> code starts, an address of allocated memory is already on top of the stack; use it wisely!
: CONSTANT ( redefining built-in CONSTANT)
CREATE ( create a word; it will take token next to CONSTANT)
, ( takes value from stack and writes it to HERE)
DOES> ( definition begins)
( address is on top of the stack)
@ ( deferefence it)
; ( end)
42 CONSTANT Answer
Answer
will put 42 onto stack
1.1+
IMMEDIATE
( -- )
Makes the most recent : definition get executed every time when it's about to be compiled.
In other words, replaces the most recent definition compilation semantics with its implementation semantics.
It can also be used with CREATE.
: warning ." WARNING" CR ; IMMEDIATE
: test warning 1 2 + . ;
1.1+
LITERAL
( -- )
Injects the executable address of the following token into code as a literal. The token's executable address is pushed onto the stack at run-time. Typically, LITERAL is used in the definition of IMMEDIATE words to dynamically constructed code by injecting the addresses of other words, but can also be used to pass the address of a word as a parameter (as a call back function). LITERAL can only be used in compile mode and is the compile equivalent of the ' word in intermediate mode.

Compile mode:
LITERAL <token>

Intermediate mode:
' <token>
: TEST LITERAL WORDS EXECUTE ;
\ calling TEST will run the word WORDS. It pushes its address then executes it
1.1+
POSTPONE
Run-time: As defined by word
Can be used inside IMMEDIATE words. Takes next word and compiles call to it into current word's interpretation semantics. Immediate words run when they are being used in word definitions. For example, IF when used does not compile, it runs. If you want a word in an immediate word's definition to not run, but to run in the word made from it POSTPONE causes this action on the word following it. POSTPONE checks weather the word following is immediate or not and compiles it accordingly. For example, POSTPONE IF will cause IF to be compiled and run when the word currently being compiled is run. POSTPONE is a compiler extension word; its used in words that make other words.
: smartword
LITERAL (lit) , 1 1 + , POSTPONE . ; IMMEDIATE
( will compile into 2 . )
: test smartword ." Another action" CR ;
test
will print 2 Another action
1.1+
RECURSE
( -- )
Compiles self-call into currently defining word. The name of a word currently being compiled cannot be used as it is hidden until the ; token.
: n! \ A classic example
DUP 0= IF
DROP 0
ELSE
DUP 1- RECURSE *
THEN ;
1.1+
(lit)

The word size value following in the program code is treated as a literal value and is pushed onto the stack. When a number is compiled in a word the compiler injects (lit) before it at HERE. An executable address following is treated as a value, this is used with, for example, , to store a subroutine address ( See LITERAL).

1.0+
(.")

Actual implementation of ." which emits string following (up to its zero-term.)

1.0+
(branch)

Unconditional jump to address value following

1.0+
(?branch)

Conditional jump to address value following, skipping address following if condition value is <>0

1.0+
(do)

Actual implementation of DO

1.0+
(?do)

Actual implementation of ?DO

1.0+
(loop)

Actual implementation of LOOP

1.0+
(+loop)

Actual implementation of +LOOP

1.0+
(leave)

Actual implementation of LEAVE

1.0+
(")

Actual implementation of "

1.1+
(does)

Helper word for DOES>

1.1+
DODOES

Actual implementation for DOES>

1.1+

  1. ^ Stored with low byte first (called little Endian).
  2. ^ Handled as 2 separate 16 bit values, yet no support to store into or load from memory directly.
  3. ^ Floating-point isn't yet supported as with MineOS 1.0+
  4. ^ May also be a mapped Redbus memory address.
  5. ^ Note that flags are also 16 bit values.
  6. ^ Workaround, thx to immibis: : KEY? KEY? -1 = IF -1 THEN ;
  7. ^ As with all strings in MineOS, this string must be zero-terminated
  8. ^ ACCEPT will zero-terminate this string automatically
  9. ^ R-stack = Return value stack.
  10. ^ See SP0 for official way to get initial stack pointer, or use newly introduced 0SP.
  11. ^ Note that constants can't be changed after creation.
  12. ^ Accessing a constant will directly return its value instead of an address as with variables.
  13. ^ Detailed informations t.b.d.
  14. ^ Note that when accessing a variable, you'll only get the address of where its stored in memory.
  15. ^ As stated near the beginning of this dictionary, default size for values is 16bit, so CELL will always return 2.
  16. ^ Note that this will just shift end of programm code by n bytes, hence changing HERE.
  17. ^ 10 RADIX ! won't switch you back to decimal mode, we're in hex mode, so that's a hex 10, use A RADIX ! for a decimal value of 10
  18. ^ Reflecting a memory size of 8kB (base rpc8/e memory size if no additional memory modules are installed).
  19. ^ Used to find disk image files in redpower/ folder named as "disk_id.img"
  20. ^ One block can hold 16 lines with 64 chars each.
  21. ^ On its first call, BLOCK will allocate a 1k wide buffer using ALLOT.
  22. ^ Starting at 0 up to 15, so 16 lines of code available, each 64 chars long.
  23. ^ After booting a clean forth disk as with MineOS 1.1 and no additional memory modules installed.
  24. ^ You can also type multiple lines of code up to an ending ;
  25. ^ Not sure if this works over multiple input lines, as usual in Forth.
  26. ^ This address points to the actual program code of this word, allowing for direct execution.
  27. ^ This address points to the actual program code of this word, allowing for direct execution.
  28. ^ Address returned must be adjusted by calling at least 1- when used within forth context, resp. -2 if called from assembler code (to hit first opcode ENT)