Achieve 100% Core compliance, implement CATCH/THROW
Core word set: 0 errors on Gerry Jackson's forth2012-test-suite/core.fr - Fix POSTPONE for non-immediate words via COMPILE, mechanism - Fix double-DOES> (WEIRD: pattern) with does-body scanning and runtime patching via _DOES_PATCH_ - Implement CATCH/THROW exception handling using wasmtime trap mechanism with stack pointer save/restore - 232 tests passing
This commit is contained in:
@@ -1,9 +1,11 @@
|
||||
# WAFER Project Conventions
|
||||
|
||||
## What is WAFER?
|
||||
|
||||
WAFER (WebAssembly Forth Engine in Rust) is an optimizing Forth 2012 compiler targeting WebAssembly. Currently a working Forth system with 70+ words and JIT compilation.
|
||||
|
||||
## Architecture
|
||||
|
||||
- Each Forth word compiles to its own WASM module via `wasm-encoder`
|
||||
- Modules share memory, globals (dsp/rsp), and a function table via wasmtime imports
|
||||
- IR-based compilation: Forth -> `Vec<IrOp>` -> WASM codegen -> wasmtime instantiation
|
||||
@@ -11,6 +13,7 @@ WAFER (WebAssembly Forth Engine in Rust) is an optimizing Forth 2012 compiler ta
|
||||
- Primitives: either IR-based (compiled to WASM) or host functions (Rust closures in wasmtime)
|
||||
|
||||
## Key Files
|
||||
|
||||
- `crates/core/src/outer.rs` -- ForthVM: the main runtime, outer interpreter, compiler, all primitives
|
||||
- `crates/core/src/codegen.rs` -- IR-to-WASM translation, module generation, wasmtime execution tests
|
||||
- `crates/core/src/dictionary.rs` -- Dictionary data structure with create/find/reveal
|
||||
@@ -21,11 +24,13 @@ WAFER (WebAssembly Forth Engine in Rust) is an optimizing Forth 2012 compiler ta
|
||||
## Adding a New Word
|
||||
|
||||
**IR primitive** (simple stack/arithmetic/logic -- preferred when possible):
|
||||
|
||||
```rust
|
||||
self.register_primitive("WORD_NAME", false, vec![IrOp::Dup, IrOp::Mul])?;
|
||||
```
|
||||
|
||||
**Host function** (needs Rust logic -- I/O, dictionary manipulation, complex stack access):
|
||||
|
||||
```rust
|
||||
let func = Func::new(&mut self.store, func_type.clone(), move |mut caller, _params, _results| {
|
||||
// manipulate memory/globals directly
|
||||
@@ -38,18 +43,21 @@ self.register_host_primitive("WORD_NAME", false, func)?;
|
||||
Handle in `interpret_token_immediate()` or `compile_token()` as a special case.
|
||||
|
||||
## Code Style
|
||||
|
||||
- `cargo fmt --all` and `cargo clippy --workspace` must pass with no warnings
|
||||
- Every public function needs a doc comment
|
||||
- Use `thiserror` for error types in core crate, `anyhow` for CLI
|
||||
- Prefer returning `Result` over panicking
|
||||
|
||||
## Testing
|
||||
|
||||
- Run `cargo test --workspace` before committing (currently 185 tests)
|
||||
- Forth 2012 compliance: `cargo test -p wafer-core --test compliance`
|
||||
- Test helper in outer.rs: `eval_output("forth code")` returns printed output as String
|
||||
- Test helper: `eval_stack("forth code")` returns data stack as Vec<i32>
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. Correctness first, performance second
|
||||
2. Maximize Forth, minimize Rust (self-hosting goal -- not yet started)
|
||||
3. Test-driven: if it's not tested, it doesn't work
|
||||
|
||||
Reference in New Issue
Block a user