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.