ok
f3bc270904
README: 392 tests, 200+ words, 12 word sets, optimization pipeline described CLAUDE.md: 200+ words, 12 word sets, 392 tests, added optimizer/config/consolidate to key files OPTIMIZATIONS.md: update all 14 section statuses (12 done, 2 not started) WAFER.md: correct line counts, add optimizer/config/consolidate/types to project layout, add FSP global
148 lines
6.6 KiB
Markdown
148 lines
6.6 KiB
Markdown
# WAFER
|
|
|
|
**WebAssembly Forth Engine in Rust**
|
|
|
|
An optimizing Forth 2012 compiler targeting WebAssembly.
|
|
|
|
## Status
|
|
|
|
WAFER is a working Forth system with an optimizing compiler. It JIT-compiles each word definition to a separate WASM module and executes via `wasmtime`. 392 tests passing (380 unit + 1 benchmark + 11 compliance), **0 errors on all 12 tested Forth 2012 word sets** including Floating-Point.
|
|
|
|
**Working features:**
|
|
|
|
- Colon definitions with full control flow (IF/ELSE/THEN, DO/LOOP/+LOOP, BEGIN/UNTIL, BEGIN/WHILE/REPEAT)
|
|
- 200+ words: stack, arithmetic, comparison, logic, memory, I/O, defining words, system, exceptions, double-cell, strings, floating-point (70+ float words)
|
|
- 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:**
|
|
|
|
```forth
|
|
: 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** with 6 optimization passes (peephole, constant folding, strength reduction, DCE, tail call detection, inlining) plus stack-to-local promotion and consolidation
|
|
- **Dictionary**: linked-list word headers in simulated linear memory
|
|
|
|
## Building
|
|
|
|
```bash
|
|
cargo build --workspace
|
|
```
|
|
|
|
## Running
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# All tests (392 currently passing)
|
|
cargo test --workspace
|
|
|
|
# Forth 2012 compliance dashboard
|
|
cargo test -p wafer-core --test compliance
|
|
|
|
# Optimization benchmark report
|
|
cargo test -p wafer-core --test benchmark_report -- --nocapture --ignored
|
|
|
|
# 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
|
|
|
|
12 word sets at 100% compliance: Core, Core Ext, Core Plus, Exception, Double-Number, String, Search-Order, Memory-Allocation, Programming-Tools, Facility, Locals, Floating-Point. 200+ words including VALUE, DEFER, CASE, DOES>, CATCH/THROW, double-cell arithmetic, string operations, and 70+ floating-point words.
|
|
|
|
## Compliance Status
|
|
|
|
Targeting 100% Forth 2012 compliance via [Gerry Jackson's test suite](https://github.com/gerryjackson/forth2012-test-suite).
|
|
|
|
| Word Set | Status |
|
|
| ------------------ | --------------------------------- |
|
|
| Core | **100%** (0 errors on test suite) |
|
|
| Core Extensions | **100%** (0 errors on test suite) |
|
|
| Double-Number | **100%** (0 errors on test suite) |
|
|
| Exception | **100%** (0 errors on test suite) |
|
|
| Facility | **100%** (0 errors on test suite) |
|
|
| File-Access | Pending (requires WASI) |
|
|
| Floating-Point | **100%** (0 errors on ak-fp-test) |
|
|
| Locals | **100%** (0 errors on test suite) |
|
|
| Memory-Allocation | **100%** (0 errors on test suite) |
|
|
| Programming-Tools | **100%** (0 errors on test suite) |
|
|
| Search-Order | **100%** (0 errors on test suite) |
|
|
| String | **100%** (0 errors on test suite) |
|
|
| Extended-Character | Pending |
|
|
|
|
## License
|
|
|
|
MIT OR Apache-2.0
|