docs: add README with project overview and AI disclaimer

Co-authored-by: aider (openrouter/moonshotai/kimi-k2.6) <aider@aider.chat>
2026-05-03 17:57:21 +03:00
parent 55d06ce43f
commit a882bf6888
1 changed files with 39 additions and 0 deletions
@@ -0,0 +1,39 @@
+# Forth Interpreter in C
+
+A minimal Forth interpreter written in C. This project implements a subset of the Forth programming language using a threaded-code architecture with separate data and return stacks.
+
+## What This Is
+
+This is a toy/subset Forth interpreter designed for educational purposes. It provides an interactive REPL where you can define words, manipulate the stack, and execute built-in primitives.
+
+## How It Works
+
+- **Threaded Code**: The interpreter uses an inner/outer interpreter model. Colon definitions are sequences of word addresses (threaded code) traversed by an instruction pointer.
+- **Architecture**: 
+  - 32-bit signed integer cells (`int32_t`)
+  - Separate data and return stacks
+  - Fixed-size dictionary, user memory, and compile buffer
+  - Dictionary is a singly-linked list searched linearly
+- **Supported Features**:
+  - Stack manipulation (`DUP`, `DROP`, `SWAP`, `OVER`, `ROT`, etc.)
+  - Arithmetic and logic (`+`, `-`, `*`, `/`, `MOD`, bitwise ops, comparisons)
+  - Colon definitions (`: word ... ;`)
+  - Variables and constants
+  - Control flow (`IF ... ELSE ... THEN`, `BEGIN ... UNTIL`, `BEGIN ... WHILE ... REPEAT`)
+  - Memory access (`@`, `!`, `C@`, `C!`, `HERE`, `ALLOT`)
+  - Simple string output (`."`)
+- **Limitations**:
+  - Fixed memory limits (dictionary, stacks, user memory)
+  - 32-bit signed integers only; no floating-point support
+  - No file I/O or operating system interface beyond stdin/stdout
+  - No immediate user-defined words or advanced introspection
+  - Single-threaded execution
+  - Error handling is basic (prints message and often returns zero or ignores)
+
+## Building
+
+Run `make` to build the project. The resulting binary can be run directly for an interactive Forth session.
+
+## Disclaimer
+
+This project was written with the assistance of AI. It is provided as-is for educational and experimental use.