uc-forth 1.0.0

Embeddable Forth interpreter — scripting engine with module system, catalog, REST API, and inference

uc-forth — Python

Zero external dependencies. Embeddable. Available on PyPI.

Part of uc-forth.

Install

pip install uc-forth

Use as library

from uc_forth import create_vm

vm = create_vm()
vm.eval("3 4 + .")           # "7 ok"
vm.eval(": SQUARE DUP * ;")  # "ok"
vm.eval("5 SQUARE .")        # "25 ok"

Engine facade

from uc_forth import Engine

engine = Engine()
engine.eval("3 4 + .")
engine.define("DOUBLE", ": DOUBLE DUP + ;",
              stack="( n -- 2n )",
              description="Double a number",
              tags=["math"])
print(engine.listing())       # user-defined words
engine.save_db("words.json")

Minimal kernel (no modules)

from uc_forth import VM, register_kernel, load_core

vm = VM()
register_kernel(vm)   # 49 primitives + module registry
load_core(vm)         # bootstrap core.fth
# load modules on demand:
vm.eval("REQUIRE http")
vm.eval('S" https://example.com" HTTP-GET')

Full setup (all modules pre-loaded)

from uc_forth import VM, register_all, load_core

vm = VM()
register_all(vm)      # kernel + all modules
load_core(vm)         # core.fth + init.fth

Run as CLI

python3 -m uc_forth --repl               # interactive REPL
python3 -m uc_forth --port 4001          # server + web GUI
uc-forth --repl --port 4001              # after pip install

Flags

Flag	Default	Description
--port	4000	HTTP server port
--repl	false	Start interactive REPL
--no-server	false	Disable HTTP server
--catalog	~/.uc-forth/catalog.json	Catalog persistence path
--load		Load a catalog file on startup
-v	false	Verbose logging

Tests

python3 -m pytest tests/ -v

Structure

py-forth/
  pyproject.toml          PyPI package config (hatchling)
  main.py                 standalone entry point
  uc_forth/
    __init__.py           create_vm, register_all, load_core
    __main__.py           python -m uc_forth
    cli.py                CLI with argparse
    vm.py                 stack machine, inner interpreter
    primitives.py         49 kernel primitives
    modules.py            vocabulary module registry
    os_primitives.py      S", FILE-READ, SHELL
    string_extra_primitives.py
    time_primitives.py
    env_primitives.py
    fs_extra_primitives.py
    http_primitives.py
    json_primitives.py    JSON-GET, JSON{...}JSON builder
    inference.py          ASSERT, QUERY?
    catalog.py            persistence, fuzzy search
    catalog_primitives.py
    syscall.py            extensible SYSCALL dispatcher
    require.py            REQUIRE / REQUIRED
    session.py            session isolation
    builtins_catalog.py   kernel documentation
    engine.py             unified Engine facade
    core/                 bundled vocabularies (from ../core/)
  server/
    server.py             REST API + SSE (stdlib only)
  tests/
    conftest.py           pytest fixtures
    test_vm.py            unit tests
    test_e2e.py           shared E2E test runner

PyPI package contents

The wheel bundles the Forth vocabularies (core.fth, init.fth) so the engine is fully functional after pip install without needing the monorepo.