author | Alan Dipert
<alan@dipert.org> 2025-10-06 19:28:25 UTC |
committer | Alan Dipert
<alan@dipert.org> 2025-10-06 19:28:25 UTC |
parent | 2775062e9e32e2c22102f5e70c291e0f4c1da074 |
README.md | +0 | -47 |
diff --git a/README.md b/README.md index d2e0625..745b3d4 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,6 @@ A hyper-minimal, embeddable Forth for the browser, written in JavaScript. Design goals: tiny core, clear semantics, strong introspection and debugging hooks for pedagogical IDEs. -This README is plain-text ASCII. Copy freely. - ---- - ## Features - Minimal stack-based VM with numeric bytecodes. @@ -27,8 +23,6 @@ This README is plain-text ASCII. Copy freely. - Disassembler and memory map - QUnit test suite (browser-based). ---- - ## Quick Start Include Fjorth in a page: @@ -56,8 +50,6 @@ Include Fjorth in a page: Console should show: `49` followed by newline. ---- - ## Public API (runtime) ```js @@ -85,8 +77,6 @@ Stacks and memory helpers (JS-level, if you extend VM): - vm.push(n), vm.pop(), vm.peek() - vm.H (memory cells), vm.here (next free cell) ---- - ## Words provided by the core Stack (data): @@ -120,8 +110,6 @@ Comments: Numbers: - Only base-10 integers are recognized by default (e.g., -42, 0, 123). ---- - ## Structured Error Handling Fjorth does not throw for normal program faults. Instead, it: @@ -150,16 +138,12 @@ vm.load("NOPE"); vm.run(err => { /* err === same Error object */ }); ``` ---- - ## Preemption and Scheduling - Time-sliced loop with configurable `stepBudget` and `sliceMs`. - Call `vm.pause()` to stop at a safe boundary. Call `vm.resume()` or `vm.run()` to continue. - Errors halt the scheduler and call your callbacks. ---- - ## Debugging and Introspection Enable tracing and breakpoints when needed. This layer is opt-in and incurs minimal overhead when disabled. @@ -223,8 +207,6 @@ Notes: - Source maps: each emitted cell records the token index that produced it; symbolication finds line/col. - Frames: calls to colon words push a readable frame; returning pops it. ---- - ## Extending with JS Define a JS-backed word: @@ -250,8 +232,6 @@ vm.defineJS("IWORD", function() { }, true); ``` ---- - ## Testing with QUnit The project includes a browser QUnit suite. You can run tests by loading: @@ -261,8 +241,6 @@ The project includes a browser QUnit suite. You can run tests by loading: If you cannot or do not want to rely on a network CDN, keep local copies of QUnit assets and reference them directly. ---- - ## Design Notes Why numeric bytecodes? @@ -282,8 +260,6 @@ Future work: - Watchpoints and time-travel snapshots (ring buffer) for reverse stepping. - A REPL UI with SEE/WORDS and live stack graphs. ---- - ## Minimal Cheat Sheet : @@ -323,32 +299,9 @@ Comments: Numbers: Base-10 integers only by default. ---- - ## Embedding Tips - Provide `print` and/or `println` so users see output. - Use `onError` to surface structured errors in your IDE (decorate gutter, highlight token, etc.). - Enable `vm.debug` only when you need it (breakpoints, tracing). - For long-running student code, keep `stepBudget` moderate (e.g., 1000 - 5000) to preserve UI responsiveness. - ---- - -## Contributing - -- Keep the interpreter tiny and readable. -- Add tests for every public API and new word. -- Do not change existing tests unless they are clearly wrong. -- Prefer structured errors over thrown exceptions. - ---- - -## License - -MIT (or your preferred permissive license). Replace this line if you adopt something else. - ---- - -## Acknowledgments - -Inspired by classic Forth systems and educational interpreters. Fjorth focuses on clarity, debuggability, and embeddability for teaching environments.