ai-forth-experiment/README.md

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:
  • 64-bit signed integer cells (int64_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 user memory limit (1M cells); dictionary and stacks grow dynamically
  • 64-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.