Forth Language Reference
st-forth implements a subset of ANS Forth with a 4-tier vocabulary system.
Using the Editor
The main page is split into three panels: an editor on the left, a REPL terminal in the center, and a live stack display on the right.
| Control | Description |
|---|
| Tier selector | Choose which vocabulary tier is active (Kernel, Core, Standard, Full). Changing the tier reinitializes the interpreter. |
| Run | Execute the editor contents in the REPL. Output and stack changes appear immediately. |
| Save & Share | Save the current editor contents and generate a shareable URL. The link appears next to the button. |
The REPL terminal at the center accepts one-line Forth input. Type a Forth expression and press Enter to evaluate it. The stack panel on the right updates after every evaluation.
Visit the Gallery to try example programs. Clicking "Try it" loads the program into the editor.
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 |