Files

T

ok cb270c8765 Reach 97% Core compliance: 58 errors down to 3

- Fix HERE corruption: sync user_here before writing to shared cell
- Fix DOES> without CREATE: patch most-recent word, not read new name
- Implement >BODY via word_pfa_map tracking parameter field addresses
- Nested BEGIN...WHILE...WHILE...REPEAT...ELSE...THEN support
- DEPTH overflow protection
- Forth 2012 core.fr: 3 errors remaining (POSTPONE edge case,
  double-DOES>, NOP meta-programming)

2026-03-30 21:02:00 +02:00

5.8 KiB

Raw Blame History

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

5.8 KiB Raw Blame History