Forth-like Stack Language Interpreter

This is a Python implementation of a Forth-like stack-based programming language interpreter. It provides a minimal but functional environment for experimenting with stack-based programming.

Features

• Basic arithmetic operations (+, -, *, /, mod)
• Stack manipulation operations (dup, drop, swap, over, rot, nip, tuck)
• Comparison operations (=, <, >, <=, >=, <>)
• Logical operations (and, or, not)
• I/O operations (., .s, cr)
• User-defined words (functions)
• Simple memory operations (!, @)
• Conditional execution (if-then-else)
• Loop constructs (begin-until, begin-while-repeat)
• CREATE word for defining expandable words
• String literals and printing

Usage

Run the interpreter in interactive mode:

python forth.py

Run a Forth script file:

python forth.py example.fth

Run tests:

python test_forth.py

The interpreter will run some examples and then enter interactive mode where you can type Forth commands. When running a script file, the interpreter will execute all commands in the file and exit. Comments (lines starting with \) and empty lines are ignored when running script files.

Examples

Basic Arithmetic

> 5 3 + .
8

Stack Operations

> 1 2 3 dup .s
<1 2 3 3>
> swap .s
<1 3 2>
> drop .s
<1 3>

User-defined Words

> : square dup * ;
> 5 square .
25

CREATE Word

> create sum 1 2 ;
> : add-sum sum + . cr ;
> add-sum
3

Conditionals

> 10 5 > if 1 . else 0 . then
1

Loops

> : countdown ( n -- ) begin dup . 1 - dup 0 = until drop ;
> 5 countdown
5 4 3 2 1

Memory Operations

> 42 100 !    \ Store 42 at address 100
> 100 @ .     \ Fetch value from address 100
42

Language Reference

Arithmetic

• + - Add top two numbers
• - - Subtract top number from second
• * - Multiply top two numbers
• / - Divide second number by top (integer division)
• mod - Modulo operation

Stack Manipulation

• dup - Duplicate top item
• drop - Remove top item
• swap - Swap top two items
• over - Copy second item to top
• rot - Rotate third item to top
• nip - Remove second item
• tuck - Copy top item below second item
• depth - Push stack depth onto stack

Comparison

• = - Equal
• < - Less than
• > - Greater than
• <= - Less than or equal
• >= - Greater than or equal
• <> - Not equal

Logic

• and - Logical AND
• or - Logical OR
• not - Logical NOT

I/O

• . - Print and remove top number
• .s - Print entire stack
• cr - Print newline
• ." - Print a string literal (e.g., ." Hello, World!")
• vlist - List all defined words

Example:

> ." Hello, World!" cr
Hello, World!
> : greet ." Welcome to Forth!" cr ;
> greet
Welcome to Forth!

Memory

• ! - Store (value address !)
• @ - Fetch (address @)

Control Flow

• if ... then - Conditional execution
• if ... else ... then - Conditional with alternative
• begin ... until - Loop until condition is true
• begin ... while ... repeat - Loop while condition is true

Word Definition

• : name ... ; - Define a new word
• create name ... ; - Define an expandable word that can be used in other definitions

Forth Concepts

In Forth:

• Numbers are pushed onto a stack
• Operations consume values from the stack and push results back
• True is represented as -1, false as 0
• Words are separated by whitespace
• Comments start with \ and continue to the end of the line

CREATE Word

The create word allows defining words that expand to their definition when used in other word definitions. This enables composability where complex words can be built from simpler ones.

Example:

create sum 1 2 ;
: add-sum sum + . cr ;
add-sum  \ Prints 3

In this example:

1. create sum 1 2 ; defines a word sum that pushes 1 and 2 to the stack
2. : add-sum sum + . cr ; defines a word that uses sum - when compiled, sum expands to 1 2
3. When add-sum is executed, it pushes 1 and 2 to the stack, adds them, and prints the result

Testing

Run the test suite:

python test_forth.py

The test suite verifies all core functionality including arithmetic, stack operations, comparisons, logic operations, user-defined words, memory operations, and control flow.

Limitations

This is a simplified implementation and lacks many features of a full Forth system:

• Simplified loop implementation
• No floating-point support
• No proper error handling for all cases
• No support for strings
• No file I/O
• No multitasking

License

This is free and unencumbered software released into the public domain.