WAFER

WebAssembly Forth Engine in Rust

An optimizing Forth 2012 compiler targeting WebAssembly.

Status

WAFER is a working Forth system. It JIT-compiles each word definition to a separate WASM module and executes via wasmtime. 219 unit tests passing, 3 errors on the Forth 2012 Core test suite.

Working features:

• Colon definitions with full control flow (IF/ELSE/THEN, DO/LOOP/+LOOP, BEGIN/UNTIL, BEGIN/WHILE/REPEAT)
• 90+ words: stack, arithmetic, comparison, logic, memory, I/O, defining words, system
• Recursion (RECURSE), nested control structures, loop counters (I, J)
• VARIABLE, CONSTANT, CREATE, DOES>
• Number bases (HEX, DECIMAL), number prefixes ($hex, #dec, %bin)
• Pictured numeric output (<# # #S #> HOLD SIGN)
• Comments (backslash, parentheses), string output (." ...)
• Interactive REPL with line editing

Example session:

: FIB DUP 2 < IF DROP 1 ELSE DUP 1 - RECURSE SWAP 2 - RECURSE + THEN ;
: FIBS 0 DO I FIB . LOOP ;
12 FIBS CR    \ prints: 1 1 2 3 5 8 13 21 34 55 89 144

VARIABLE COUNTER  0 COUNTER !
: BUMP COUNTER @ 1 + COUNTER ! ;
BUMP BUMP BUMP COUNTER @ .  \ prints: 3

Goals

• Full Forth 2012 compliance -- all word sets, 100% test suite pass rate
• Optimizing compiler -- constant folding, inlining, peephole optimization, stack-to-local promotion
• Multi-typed stack -- type inference uses WASM's native typed stack when possible
• Self-hosting -- minimal Rust kernel (~35 primitives), everything else in WAFER Forth
• Consolidation mode -- recompile all JIT words into a single optimized WASM module

Architecture

Forth Source -> Outer Interpreter -> IR -> [Optimize] -> WASM Codegen (wasm-encoder)
                                                              |
                                                    wasmtime instantiation
                                                    (shared memory + table)

• Subroutine threading via WASM function tables and call_indirect
• JIT mode: each new word compiles to a separate WASM module linked to shared memory/globals/table
• IR-based pipeline enables future optimization passes before WASM emission
• Dictionary: linked-list word headers in simulated linear memory

Building

cargo build --workspace

Running

# Interactive REPL
cargo run -p wafer

# Run a Forth file
cargo run -p wafer -- file.fth

# Pipe input
echo ': SQUARE DUP * ; 7 SQUARE .' | cargo run -p wafer

Testing

# All tests (185 currently passing)
cargo test --workspace

# Forth 2012 compliance dashboard
cargo test -p wafer-core --test compliance

# Lints
cargo clippy --workspace

Project Structure

crates/
  core/       wafer-core: dictionary, IR, codegen (wasm-encoder), outer interpreter
  cli/        wafer: CLI REPL and file execution (wasmtime, rustyline)
  web/        wafer-web: browser bindings (planned)
forth/        Standard library in WAFER Forth (planned, currently stubs)
tests/        Forth 2012 compliance suite (gerryjackson/forth2012-test-suite submodule)

Implemented Words

Core (Forth 2012 Section 6.1) -- In Progress

Category	Words
Stack	DUP DROP SWAP OVER ROT NIP TUCK 2DUP 2DROP 2SWAP 2OVER ?DUP PICK DEPTH
Arithmetic	+ - * / MOD /MOD NEGATE ABS MIN MAX 1+ 1- 2* 2/ */ */MOD M* UM* UM/MOD FM/MOD SM/REM S>D <# # #S #> HOLD SIGN
Comparison	= <> < > U< 0= 0< 0<> 0> WITHIN
Logic	AND OR XOR INVERT LSHIFT RSHIFT
Memory	@ ! C@ C! +! 2@ 2! HERE ALLOT , C, CELLS CELL+ CHARS CHAR+ ALIGNED ALIGN MOVE FILL CMOVE CMOVE>
Control	IF ELSE THEN DO LOOP +LOOP I J UNLOOP LEAVE BEGIN UNTIL WHILE REPEAT RECURSE EXIT
Defining	: ; VARIABLE CONSTANT CREATE DOES> IMMEDIATE
I/O	. U. .S CR EMIT SPACE SPACES TYPE ." S" ACCEPT
Return stack	>R R> R@
System	EXECUTE ' CHAR [CHAR] ['] DECIMAL HEX BASE STATE >IN >BODY ENVIRONMENT? SOURCE ABORT TRUE FALSE BL
Compiler	LITERAL POSTPONE [ ] EVALUATE ABORT"
Parsing	WORD FIND COUNT >NUMBER

Not Yet Implemented

3 remaining Core test failures:

• POSTPONE for non-immediate words in IMMEDIATE context (GT5)
• Double-DOES> in one definition (WEIRD: W1)
• : NOP : POSTPONE ; ; meta-programming pattern

Compliance Status

Targeting 100% Forth 2012 compliance via Gerry Jackson's test suite.

Word Set	Status
Core	97% (3 failures on test suite)
Core Extensions	Pending
Double-Number	Pending
Exception	Pending
Facility	Pending
File-Access	Pending
Floating-Point	Pending
Locals	Pending
Memory-Allocation	Pending
Programming-Tools	Pending
Search-Order	Pending
String	Pending
Extended-Character	Pending

License

MIT OR Apache-2.0