Forth Language Reference
st-forth implements a subset of ANS Forth with a 4-tier vocabulary system.
Vocabulary Tiers
Each tier builds on the previous one. Use the tier selector to choose which words are available.
| Tier | Description |
|---|
| Kernel | ~35 Rust-native primitives only |
| Core | + ~20 derived stack/math words (NIP, TUCK, 2DUP, MAX, MIN...) |
| Standard | + boolean constants, formatting (TRUE, FALSE, AND, OR...) |
| Full | + utility words (SQUARE, CUBE, GCD, STARS...) |
Stack Operations
| Word | Stack Effect | Description |
|---|
| DUP | ( x -- x x ) | Duplicate top of stack |
| DROP | ( x -- ) | Discard top of stack |
| SWAP | ( a b -- b a ) | Swap top two items |
| OVER | ( a b -- a b a ) | Copy second item to top |
| ROT | ( a b c -- b c a ) | Rotate third item to top |
| ?DUP | ( x -- x x | 0 ) | Duplicate if non-zero |
| DEPTH | ( -- n ) | Stack depth |
| .S | ( -- ) | Print entire stack |
| >R | ( x -- ) R:( -- x ) | Move to return stack |
| R> | ( -- x ) R:( x -- ) | Move from return stack |
| R@ | ( -- x ) R:( x -- x ) | Copy from return stack |
Arithmetic
| Word | Stack Effect | Description |
|---|
| + | ( a b -- a+b ) | Add |
| - | ( a b -- a-b ) | Subtract |
| * | ( a b -- a*b ) | Multiply |
| / | ( a b -- a/b ) | Integer divide |
| MOD | ( a b -- a%b ) | Modulo |
| /MOD | ( a b -- rem quot ) | Division with remainder |
| NEGATE | ( n -- -n ) | Negate |
| ABS | ( n -- |n| ) | Absolute value |
Comparison
Comparison words return -1 (true) or 0 (false).
| Word | Stack Effect | Description |
|---|
| = | ( a b -- flag ) | Equal |
| < | ( a b -- flag ) | Less than |
| > | ( a b -- flag ) | Greater than |
| <> | ( a b -- flag ) | Not equal |
| 0= | ( n -- flag ) | Equal to zero |
| 0< | ( n -- flag ) | Less than zero |
| 0> | ( n -- flag ) | Greater than zero |
Memory
| Word | Stack Effect | Description |
|---|
| @ | ( addr -- n ) | Fetch from memory |
| ! | ( n addr -- ) | Store to memory |
| +! | ( n addr -- ) | Add to memory |
| VARIABLE | VARIABLE name | Create a variable |
| CONSTANT | n CONSTANT name | Create a constant |
| ALLOT | ( n -- ) | Reserve n cells |
Input/Output
| Word | Stack Effect | Description |
|---|
| . | ( n -- ) | Print number |
| EMIT | ( c -- ) | Print character |
| CR | ( -- ) | Print newline |
| SPACE | ( -- ) | Print space |
| TYPE | ( str -- ) | Print string |
| ." text" | ( -- ) | Print inline string |
Control Flow
| Word | Usage | Description |
|---|
| IF...THEN | flag IF ... THEN | Conditional |
| IF...ELSE...THEN | flag IF ... ELSE ... THEN | Conditional with else |
| DO...LOOP | limit start DO ... LOOP | Counted loop |
| DO...+LOOP | limit start DO ... step +LOOP | Counted loop with step |
| I | ( -- index ) | Current loop index |
| J | ( -- index ) | Outer loop index |
| BEGIN...UNTIL | BEGIN ... flag UNTIL | Loop until true |
| BEGIN...WHILE...REPEAT | BEGIN ... flag WHILE ... REPEAT | Loop while true |
| RECURSE | RECURSE | Call current word recursively |
Defining Words
| Word | Usage | Description |
|---|
| : ; | : name ... ; | Define a new word |
| VARIABLE | VARIABLE name | Create a variable (use @ and ! to access) |
| CONSTANT | value CONSTANT name | Create a constant |
| IMMEDIATE | IMMEDIATE | Mark last word as immediate |