diff options
Diffstat (limited to 'forth/foreforthfourth/README.md')
| -rw-r--r-- | forth/foreforthfourth/README.md | 138 |
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 |