fig-FORTH 79

A portable fig-FORTH 79 REPL in Python, compliant with the
FORTH-79 Standard.
Single-file implementation with a block-screen editor written in FORTH itself (screens 70–72).

---

Features

• ✅ 100% compliant with FORTH-79 Standard (Required Word Set + Double Number Extension)
• 📝 Built-in screen editor written in FORTH itself (screens 70–72)
• 🔄 Self-bootstrapping — editor loads from blocks
• 🖥️ Cross-platform — works on Linux, macOS, and Windows
• 📦 Single-file implementation for easy distribution

---

Quick Start

Linux/macOS:

git clone https://github.com/DonaldMoran/forth_79.git
cd forth_79
./run.sh

Windows (Command Prompt):

git clone https://github.com/DonaldMoran/forth_79.git
cd forth_79
run.bat

Then load the editor:

70 LOAD

---

Manual Setup

Linux/macOS:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 src/mkblocks.py   # Creates data/blocks.fb
python3 src/main.py

Windows:

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
python src\mkblocks.py   # Creates data\blocks.fb
python src\main.py

---

Linux Installation

Install System-Wide

git clone https://github.com/DonaldMoran/forth_79.git
cd forth_79
./scripts/linux/install.sh

The installer will:

• Create a virtual environment
• Install dependencies
• Build a standalone binary (dist/forth79)
• Generate a .desktop launcher (forth79.desktop)
• Generate icons (assets/icon.png and assets/icon.ico)

Run the Binary

./dist/forth79

Uninstall

To remove everything install.sh created:

./scripts/linux/uninstall.sh

To also remove the virtual environment:

CLEAN_VENV=1 ./scripts/linux/uninstall.sh

Desktop Launcher

The generated forth79.desktop works in-place (double-click or gtk-launch forth79.desktop).

To add to your system application menu:

Per user:

cp forth79.desktop ~/.local/share/applications/

System-wide:

sudo cp forth79.desktop /usr/share/applications/

---

Windows Installation

On Windows, the getch package is automatically skipped during installation (since Windows has built-in keyboard input support via msvcrt). Installation is clean and error-free.

Run from Source

Simply use run.bat — it handles everything:

run.bat

Build a Windows Executable

venv\Scripts\activate
pip install pyinstaller
pyinstaller --onefile --name forth79 src\main.py

The executable will be at dist\forth79.exe.

---

Defining Custom Words

You can extend the Forth environment by defining your own words. For example, to clear the terminal screen:

: PAGE  27 EMIT 91 EMIT 50 EMIT 74 EMIT 27 EMIT 91 EMIT 72 EMIT ;

This sends the ANSI escape sequence to clear the screen and move the cursor home. After defining it, simply type PAGE to clear the terminal.

---

Compliance

Component	Status
Required Word Set (149 words)	✅ 100%
Double Number Extension (18 words)	✅ 100%
Block Screen Editor (screens 70–72)	✅ Working
16-bit Signed Cell Arithmetic	✅ Implemented

Extra words: .S, BYE, CHAR, HEX, SEE, U<, VLIST, WORDS, THRU, FLUSH, TIB, COLD, WARM

---

Screen Editor

The editor is written in FORTH on screens 70–72.

Load and Enter the Editor

70 LOAD       \ load the editor
EDITOR        \ switch to editor vocabulary

Commands

Command	Description
L	List current screen (SCR) with line numbers
F	Fill current screen with spaces
N	Next screen (SCR+1) and list
B	Back screen (SCR-1) and list
n E <text>	Replace line n with text
n P <text>	Insert a line before n
n D	Delete line n
n T	Type line n

Return to FORTH

FORTH
SAVE-BUFFERS
FLUSH
ED            \ reload editor anytime

---

Loading Screens

n LIST        \ display screen n
n LOAD        \ interpret screen n
n1 n2 THRU    \ load screens n1 through n2 inclusive

---

Bootstrapping the Editor Without mkblocks.py

If blocks.fb doesn't exist or screen 70 is empty, define the editor vocabulary manually:

Screen 70

( EDITOR - Block Screen Editor  70 LOAD )
( Commands: L F N B E P D               )
VOCABULARY EDITOR
EDITOR DEFINITIONS
: LINE ( n -- addr )
  64 * SCR @ BLOCK + ;
: L ( -- )  CR  ." Scr " SCR @ . CR
  16 0 DO  CR I . SPACE  I LINE
  64 TYPE  LOOP CR ;
: F ( -- )  SCR @ BUFFER
  1024 32 FILL UPDATE ;
: N  SCR @ 1+  LIST ;
: B  SCR @ 1-  LIST ;
71 LOAD 72 LOAD

Screen 71

( EDITOR cont'd )
VARIABLE L#
: E ( n -- )  L# !  SCR @ BLOCK
  DUP  L# @ 64 * +  64 32 FILL
  L# @ 64 * +  0 WORD
  COUNT  64 MIN  >R  SWAP  R>  CMOVE
  UPDATE ;
: P ( n -- )  L# !  SCR @ BUFFER
  L# @ 15 DO  DUP I 1- 64 * +
  OVER I 64 * +  64 CMOVE  -1 +LOOP
  DROP  L# @ LINE  64 32 FILL
  L# @ LINE  0 WORD
  COUNT  64 MIN  >R  SWAP  R>  CMOVE
  UPDATE ;

Screen 72

( EDITOR cont'd )
: D ( n -- )  L# !  SCR @ BUFFER
  15 L# @ 1+ DO  DUP I 64 * +
  OVER I 1- 64 * +  64 CMOVE  LOOP
  DROP  SCR @ BLOCK  15 64 * +
  64 32 FILL  UPDATE ;
: T ( n -- )  DUP L# !  LINE 64 TYPE ;
FORTH DEFINITIONS
: ED 70 LOAD ;

Once defined, use the editor to populate screens 70–72, then SAVE-BUFFERS.

---

Block File

blocks.fb stores 73 blocks × 1024 bytes (16 lines × 64 chars). Created automatically by mkblocks.py. Missing blocks read as spaces; SAVE-BUFFERS/FLUSH creates the file if absent.

---

Architecture

• 16-bit cells, signed two's complement arithmetic, modulo 64K addressing
• Flat byte-addressed memory via a Python dict
• System variables at fixed low addresses: BASE_ADDR=0, STATE_ADDR=2, TOIN_ADDR=4, BLK_ADDR=6, CONTEXT_ADDR=8, CURRENT_ADDR=10, HERE_ADDR=12, HLD_ADDR=14, SCR_ADDR=16, TIB_ADDR=2048
• Dictionary starts at HERE_ADDR (1024). Colon word bodies store execution tokens (xts) as integers. Internal xts are negative (−1 to −12), user xts start at 1.
• Block storage: 73 blocks × 1024 bytes in blocks.fb. Two memory buffers at BLK_BUF_ADDR (8192). Missing blocks are space-filled on read; SAVE-BUFFERS/FLUSH creates the file if absent.
• Vocabulary system: FORTH is default. CONTEXT and CURRENT manage search order. Vocabulary words (FORTH, EDITOR, etc.) switch CONTEXT without pushing an address.
• Editor text input: E and P use 0 WORD COUNT to read the rest of the input line.

---

Known Limitations

• Two block buffers only — heavy loading may cause thrashing
• No write-back on buffer reassignment (only on explicit SAVE-BUFFERS/FLUSH)
• No built-in disk formatting / cold-start (use mkblocks.py)
• No test suite yet

---

Requirements

• Python 3.8+
• (Optional) ImageMagick — for icon generation during install.sh:
  • Fedora: sudo dnf install ImageMagick
  • Debian/Ubuntu: sudo apt install imagemagick

---

License

MIT License — see the LICENSE file for details.

---

Contributing

Contributions are welcome! Please open an issue or pull request.

---

Built with ❤️ for the FORTH community