WAFER/README.md

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. 185 tests passing.

Working features:

• Colon definitions with full control flow (IF/ELSE/THEN, DO/LOOP/+LOOP, BEGIN/UNTIL, BEGIN/WHILE/REPEAT)
• 70+ words: stack, arithmetic, comparison, logic, memory, I/O, defining words, system
• Recursion (RECURSE), nested control structures, loop counters (I, J)
• VARIABLE, CONSTANT, CREATE
• Number bases (HEX, DECIMAL), number prefixes ($hex, #dec, %bin)
• 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

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/ Comparison: = <> < > U< 0= 0< 0<> 0> WITHIN Logic: AND OR XOR INVERT LSHIFT RSHIFT Memory: @ ! C@ C! +! HERE ALLOT , C, CELLS CELL+ CHARS CHAR+ ALIGNED ALIGN MOVE FILL Control (compile-time): IF ELSE THEN DO LOOP +LOOP I J UNLOOP LEAVE BEGIN UNTIL WHILE REPEAT RECURSE EXIT Defining: : ; VARIABLE CONSTANT CREATE IMMEDIATE I/O: . .S CR EMIT SPACE SPACES TYPE ." S" Return stack: >R R> R@ System: EXECUTE ' CHAR [CHAR] ['] DECIMAL HEX BASE >BODY ENVIRONMENT? SOURCE ABORT TRUE FALSE BL Compiler: LITERAL POSTPONE [ ]

Not Yet Implemented

DOES> EVALUATE >NUMBER ACCEPT WORD FIND COUNT CMOVE CMOVE> >IN #TIB STATE (as variable) ABORT" and others needed for full Core compliance.

Compliance Status

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

Word Set	Status
Core	In progress (~70%)
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