PyForth Overview
This is a Forth interpreter written in Python with a modular extension system. The project consists of several key components:
Core Architecture
forth_vm.py - The main virtual machine implementation (26KB)
- Heap-based Forth VM without using a heap based dictionary of forth words and code
- Implements data stack (S) and return stack (R)
- 64KB heap for dictionary storage
- Full Forth language features including:
- Control structures (IF/ELSE/THEN, BEGIN/AGAIN/UNTIL, DO/LOOP)
- Word definition and compilation
- Variables, constants, and CREATE/DOES> constructs
- Number base conversion (HEX/DECIMAL)
- Stack manipulation words
pf.py - Main entry point
- Initializes the VM
- Loads extensions
- Auto-loads
0.txt if present (for startup scripts)
- Starts the REPL
Extension System
The project uses a clean extension mechanism:
Extn.py - Core extensions module
- Bitwise operations (LSHIFT, RSHIFT, AND, OR, XOR, INVERT)
- Python integration (
PYTHON word to load/execute Python files)
- File I/O and system integration
Times3.py - Simple example extension
- Demonstrates how to add custom words
- Adds a
3* word that multiplies top of stack by 3
geek-pin.py - Hardware interface for Geek RP2040 board
- GPIO pin manipulation for embedded applications
- Uses CircuitPython's
board and digitalio libraries
- Pin mapping for RP2040 GPIO pins
- Forth words for pin control
Key Features
- Extension Protocol: Extensions must have an
install(vm) function that adds words using vm.add_fn(forth_name, python_function)
- Auto-loading: Looks for
0.txt on startup for initialization scripts
- Hardware Integration: Designed to work with microcontrollers (RP2040)
- Clean Architecture: Separates core VM from extensions for modularity
Usage Instructions
The markdown file provides clear guidance:
- Don't modify
forth_vm.py directly
- Add new functionality to
Extn.py or create new extension files
- Extensions are loaded using the
PYTHON word in Forth