Files

T

ok f99f9d5290 Achieve 100% Core Extensions compliance, 261 tests

Implement 25+ Core Extension words:
- VALUE/TO, DEFER/IS/ACTION-OF, :NONAME
- CASE/OF/ENDOF/ENDCASE, ?DO, AGAIN
- PARSE, PARSE-NAME, S\", C", HOLDS, BUFFER:
- 2>R, 2R>, 2R@, U>, .R, U.R, PAD, ERASE, UNUSED
- REFILL, SOURCE-ID, MARKER (stub)

Fix panic on invalid memory access (bounds check in FIND).
Rewrite FIND/WORD host functions for inline operation.
Add BeginAgain IR variant and codegen.

Three word sets at 100%: Core, Core Extensions, Exception.

2026-03-30 22:19:49 +02:00

5.9 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. 261 unit tests passing, 0 errors on Core, Core Extensions, and Exception test suites.

Working features:

Colon definitions with full control flow (IF/ELSE/THEN, DO/LOOP/+LOOP, BEGIN/UNTIL, BEGIN/WHILE/REPEAT)
110+ words: stack, arithmetic, comparison, logic, memory, I/O, defining words, system, exceptions
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

All Core and Core Extension words implemented. Exception word set (CATCH/THROW) also complete. VALUE, TO, DEFER, IS, CASE/OF/ENDOF/ENDCASE, :NONAME, PARSE-NAME, S\", BUFFER:, ?DO, AGAIN, and more.

Compliance Status

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

Word Set	Status
Core	100% (0 errors on test suite)
Core Extensions	100% (0 errors on test suite)
Double-Number	Pending
Exception	100% (0 errors on test suite)
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.9 KiB Raw Blame History