Metadata-Version: 2.4
Name: uc-forth
Version: 1.0.0
Summary: Embeddable Forth interpreter — scripting engine with module system, catalog, REST API, and inference
Project-URL: Homepage, https://github.com/cuber-it/uc-forth
Project-URL: Repository, https://github.com/cuber-it/uc-forth
Project-URL: Changelog, https://github.com/cuber-it/uc-forth/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/cuber-it/uc-forth/issues
Author-email: Ulrich Cuber <ulrich@cuber-it.de>
License-Expression: Apache-2.0
Keywords: embedded,forth,interpreter,scripting,stack-machine
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Interpreters
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# uc-forth — Python

Zero external dependencies. Embeddable. Available on [PyPI](https://pypi.org/project/uc-forth/).

Part of [uc-forth](https://github.com/cuber-it/uc-forth).

## Install

```bash
pip install uc-forth
```

## Use as library

```python
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

```python
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)

```python
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)

```python
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

```bash
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

```bash
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.
