aboutsummaryrefslogtreecommitdiffstats
path: root/forth/foreforthfourth/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'forth/foreforthfourth/README.md')
-rw-r--r--forth/foreforthfourth/README.md138
1 files changed, 138 insertions, 0 deletions
diff --git a/forth/foreforthfourth/README.md b/forth/foreforthfourth/README.md
new file mode 100644
index 0000000..381053d
--- /dev/null
+++ b/forth/foreforthfourth/README.md
@@ -0,0 +1,138 @@
+# 4-Stack Toy Forth Interpreter
+
+A pure functional implementation of a toy Forth interpreter with a unique 4-stack architecture, written in JavaScript.
+
+## Architecture
+
+This Forth interpreter features **4 separate stacks** that users can juggle between, unlike traditional single-stack Forth implementations:
+
+- **Stack 1 (Red)** - Default stack for most operations
+- **Stack 2 (Teal)** - Secondary stack for data organization
+- **Stack 3 (Blue)** - Tertiary stack for complex operations
+- **Stack 4 (Yellow)** - Quaternary stack for additional data
+
+## Features
+
+### Core Forth Operations
+- **Stack Manipulation**: `dup`, `swap`, `drop`, `2dup`, `2drop`, `over`, `rot`, `-rot`
+- **Arithmetic**: `+`, `-`, `*`, `/`, `mod`
+- **Comparison**: `=`, `<`, `>`, `and`, `or`, `not`
+- **Math Utilities**: `abs`, `min`, `max`
+- **Stack Inspection**: `.s` (non-destructive), `depth`
+
+### Multi-Stack Operations
+- **Push Operations**: `push.red`, `push.teal`, `push.blue`, `push.yellow`
+- **Pop Operations**: `pop.red`, `pop.teal`, `pop.blue`, `pop.yellow`
+- **Move Operation**: `move` (interactive stack-to-stack movement)
+
+### Word Definition System
+- **Define Words**: `: name ... ;` syntax
+- **List Words**: `words` command shows all available words
+- **User Dictionary**: Persistent storage of custom words
+
+## Project Structure
+
+```
+foreforthfourth/
+├── index.html # Web interface
+├── forth.js # Core Forth interpreter (standalone)
+├── test-forth.js # Test suite for the interpreter
+└── README.md # This file
+```
+
+## Testing
+
+### Run Tests
+```bash
+node test-forth.js
+```
+
+### Test Coverage
+The test suite covers:
+- Basic number pushing and arithmetic
+- Stack manipulation operations
+- Comparison and logical operators
+- Word definition and usage
+- Multi-stack operations
+- Error handling
+
+## Web Interface
+
+Open `index.html` in a web browser to use the interactive Forth interpreter with:
+- Visual representation of all 4 stacks
+- Real-time command execution
+- Output history
+- Responsive design for mobile and desktop
+
+## Usage Examples
+
+### Basic Stack Operations
+```forth
+5 3 2 .s # Push numbers and show stack
+dup over # Duplicate top, copy second over top
+2dup # Duplicate top two items
+```
+
+### Arithmetic
+```forth
+10 3 / # Integer division (result: 3)
+10 3 mod # Modulo (result: 1)
+-5 abs # Absolute value (result: 5)
+```
+
+### Multi-Stack Juggling
+```forth
+5 3 2 # Push to red stack
+push.teal # Move top of red to teal stack
+push.blue # Move top of red to blue stack
+```
+
+### Word Definition
+```forth
+: double dup + ; # Define 'double' word
+5 double # Use the word (result: 10)
+```
+
+### Comparison and Logic
+```forth
+5 3 > # 5 > 3 (result: -1 for true)
+5 3 < # 5 < 3 (result: 0 for false)
+5 3 > not # NOT (5 > 3) (result: 0)
+```
+
+## Design Principles
+
+### Pure Functional
+- **Immutable State**: All state updates return new state objects
+- **No Side Effects**: Functions are pure and predictable
+- **Functional Composition**: Operations compose naturally
+
+### 4-Stack Architecture
+- **Stack Independence**: Each stack operates independently
+- **Flexible Data Flow**: Move data between stacks as needed
+- **Organized Workflows**: Use different stacks for different purposes
+
+### ANS Forth Compatibility
+- **Standard Words**: Implements core ANS Forth words
+- **Familiar Syntax**: Standard Forth syntax and semantics
+- **Extensible**: Easy to add new words and functionality
+
+## Future Enhancements
+
+### Planned Features
+- **Control Flow**: `IF ... THEN`, `DO ... LOOP` constructs
+- **String Operations**: String literals and manipulation
+- **File I/O**: Load and save Forth programs
+- **Debugging Tools**: Step-by-step execution, breakpoints
+
+### Potential Extensions
+- **Graphics**: Simple drawing operations
+- **Networking**: HTTP requests and responses
+- **Persistence**: Save state between sessions
+- **Modules**: Import/export word definitions
+
+## Known Issues
+
+- The `move` operation requires two separate command inputs
+- Some edge cases in error handling may need refinement
+- Performance optimization for large programs