4TrOn

Forth language based operating environment.
Language Reference

1. System language (4Tron core compiler)

This is a list of all words available in the kernel. Some words have a highlevel definition to show a possible implementation of the word. This is a valid way to implement but most kernels will have a equivalent assembly routine or native code generator for each primitive for increased execution speed.

1.1. Stack jugling words

1.1.1. DROP

Stack effect: n --
Remove the value on top of the data-stack

1.1.2. DUP

Stack effect: n -- n n
Duplicate the top value on the data-stack

1.1.3. NIP

Stack effect: n1 n2 -- n2
Remove the value below top on the data-stack

: NIP   SWAP DROP ;

: NIP   >R DROP R> ;

1.1.4. OVER

Stack effect: n1 n2 -- n1 n2 n1
Copy the value below top on the data-stack

1.1.5. THIRD

Stack effect: n3 n2 n1 -- n3 n2 n1 n3
Get the value 2 levels below top and copy it to the data-stack

: THIRD   >R OVER R> SWAP ;

1.1.6. SWAP

Stack effect: n1 n2 -- n2 n1
Exchange top two items on the data-stack

1.1.7. TUCK

Stack effect: n1 n2 -- n2 n1 n2
It can be considered the counterpart of OVER.

: TUCK   SWAP OVER ;

1.1.8. TRUE

Stack effect: -- -1
Push true on the data-stack.

: TRUE   -1 ;

: TRUE   FALSE 1 - ;

: TRUE   0 0 = ;

1.1.9. FALSE

Stack effect: -- 0
Push false or null on the data-stack.

: FALSE   0 ;

1.2. Math words

1.2.1. 2*

Stack effect: n -- n+n
Multiply top stack item by 2 (shift left by 1 bit).

: 2*   DUP + ;

1.2.2. 2/

Stack effect: n -- (n/2)
Divide top stack item by 2 (shift right by 1 bit).

1.2.3. +

Stack effect: a b -- a+b
Add top two stack items together.

1.2.4. NEGATE

Stack effect: n -- -n
Subtrack top of stack from zero.

: NEGATE   INVERT 1 + ;

1.2.5. *

Stack effect: a b -- a*b
Multiply top two stack items.

: *   M* DROP ;

1.2.6. M*

1.2.7. /MOD

1.2.8. U/MOD

1.2.9. */

1.3. Logic words

1.3.1. AND

Stack effect: n1 n2 -- (n1 AND n2)
Perform logical AND on top two parameters on the data-stack.

1.3.2. OR

Stack effect: n1 n2 -- (n1 OR n2)
Perform logical OR on top two parameters on the data-stack.

1.3.3. XOR

Stack effect: n1 n2 -- (n1 XOR n2)
Perform logical ExclusiveOR on top two parameters on the data-stack.

1.3.4. INV

Stack effect: n -- ~n
Invert all bits of n.

: INVERT   TRUE XOR ;

1.3.5. BOOL

Stack effect: n -- f
Convert value to boolean (all bits set or cleared). Flag is -1 if n is none zero, and flag is 0 if n is zero.

: BOOL   0 = INVERT ;

1.4. Memory accessing words

1.4.1. !

Stack effect: n addr --
Store cell wide value n in the memory cell at address pointed to by addr.

1.4.2. B!

Stack effect: n addr --
Store byte value n in the memory at address pointed to by addr.

1.4.3. @

1.4.4. B@

Stack effect: addr -- n
Fetch byte value from given address.

1.5. Compiler words

1.5.1. :

Stack effect: |name| --
Creates a new word in the dictionary. The execution address is set to the current location in code space. The word is directly visible in the dictionary. So recursive calling of the word from itself is possible. Tail recursion optimisation is always implemented. The dictionary is defined outside the code space so multiple entry and exit points are possible.

: ENDLESSLOOP  ...do something... ENDLESSLOOP ;

1.5.2. CONSTANT

: CONSTANT  :' CFA DOVAL N, COMPILE,' W,' ;

1.5.3. VALUE

: VALUE  :' CFA DOVAL N, COMPILE,' W,' ;

1.5.4. CREATE

Runtime stack effect: |name| --
Defined stack effect: -- a
Creates a new word in the dictionary. Executing this word returns a pointer to location in code space which was current when the word was defined.

: CREATE  :' CFA DOVAR N, COMPILE,' ;

1.5.5. DOES'

: DOES'  HERE' MAGIC' +' N,'   CFA LASTDEF N, COMPILE,   CFA ! N, COMPILE,   ;' R>'' ;
Note: MAGIC is a constant containing length of inserted code which looks like:  40576 LASTDEF ! ;
      40576 is result of HERE MAGIC +. DOES' can NOT be implemented platform independed.

1.5.6. CELL

Stack effect: -- n
Return number of bytes needed to store a cell wide value. This is 4 for 32-bit systems.

1.5.7. CELL+

Stack effect: a -- a
Add size of cell to the address.

: CELL+  CELL' +' ;

1.5.8. CELLS

Stack effect: n -- n
Returns number of bytes used to store given number of cells.

: CELLS  CELL' *' ;

1.5.9. FIND

Stack effect: a n -- cfa 0 | a n

1.5.10. TO

Stack effect: n --
Store value in variable. Needed to update automatic variables (VALUE)

: TO  CFA' MAGIC-CALLSIZE' +' !' ;

1.5.11. TO'

Compile stack effect: |name| --
Runtime stack effect: n --
Store value in variable. Needed to update automatic variables (VALUE)

1.5.12. B,

Stack effect: n --
Store byte at current code compiling location (pointed to by HERE)

: B,  HERE' C!'   HERE' 1+' TO' HERE ;

1.5.13. W,

Stack effect: n --
Store integer at current compiling location (pointed to by HERE)

: W,  HERE' !'   HERE' CELL+' TO' HERE ;

1.5.14. N,

Compile stack effect: n --
Runtime stack effect: -- n
Compile literal, at runtime this will return the integer stored.

: N,  CFA DOLIT N, COMPILE,'   W,' ;

Note: Do you see the problem? N, requires N, for its definition. It could be solved like this:

: N,  DOLIT' CFA DOLIT W, COMPILE,'   W,' ;

1.5.15. IF'

Compile stack effect: -- a
Runtime stack effect: f --
Skip code until THEN' when flag is zero.

1.5.16. NIF'

Compile stack effect: -- a
Runtime stack effect: f --
Skip code until THEN' when flag is not zero.

1.5.17. THEN'

Compile stack effect: a --
Runtime stack effect: --
Terminates conditional code execution statement. It resolves the forward reference left behind by IF' or NIF'.

1.6. System variables

1.6.1. HERE

Stack effect: -- a
Current code compiling location, updatable with TO'.

1.6.2. DICT

Stack effect: -- a
Current dictionary and string compiling location, updatable with TO'.

1.6.3. SP0

Stack effect: -- n
Returns start position of the data-stack pointer.

1.6.4. SP@

Stack effect: -- n
Returns current position of the data-stack pointer.

1.6.5. SP!

Stack effect: n --
Sets current position of the data-stack pointer.

1.6.6. RP0

Stack effect: -- n
Returns start position of the return-stack pointer.

1.6.7. RP@

Stack effect: -- n
Returns current position of the return-stack pointer.

1.6.8. RP!

Stack effect: n --
Sets current position of the return-stack pointer.

2. Standard runtime library

2.1. Task system

2.2. Disk system

2.3. Graphic system