ok2
ca07d358fb
README now documents all 70+ implemented words, working examples, architecture overview, and accurate compliance status. CLAUDE.md updated with actual file descriptions, patterns for adding new words, and current test count.
139 lines
4.4 KiB
Markdown
139 lines
4.4 KiB
Markdown
# 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:**
|
|
```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** enables future optimization passes before WASM emission
|
|
- **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 (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](https://github.com/gerryjackson/forth2012-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
|