uc-forth 0.1.0__py3-none-any.whl

uc_forth/__init__.py

@@ -0,0 +1,78 @@
+"""uc-forth — A Forth-based knowledge and execution kernel."""
+
+__version__ = "0.1.0"
+
+import os
+
+from .vm import VM, Word, WordType, Token, CatalogEntry, CatalogVersion, Fact
+from .engine import Engine
+from .primitives import register_primitives
+from .os_primitives import register_core_os_primitives
+from .syscall import register_syscall_primitives
+from .require import register_require_primitives
+from .builtins_catalog import register_builtin_catalog
+from .modules import register_modules
+
+# Must import catalog to ensure methods are patched onto VM
+import uc_forth.catalog  # noqa: F401
+
+
+def register_kernel(vm: VM) -> None:
+    """Register only the minimum kernel primitives and populate the module dict."""
+    register_primitives(vm)
+    register_core_os_primitives(vm)
+    register_syscall_primitives(vm)
+    register_require_primitives(vm)
+    register_builtin_catalog(vm)
+    register_modules(vm)
+
+
+def register_all(vm: VM) -> None:
+    """Register kernel primitives, populate modules, and load ALL modules."""
+    register_kernel(vm)
+    for module_name, loader in vm.modules.items():
+        module_key = f"module:{module_name}"
+        if module_key not in vm.loaded_files:
+            loader(vm)
+            vm.loaded_files[module_key] = True
+
+
+def load_core(vm: VM) -> int:
+    """Load core.fth and init.fth. Returns number of loaded definitions."""
+    loaded = 0
+    for filename in ("core.fth", "init.fth"):
+        # Search in multiple locations
+        candidates = [
+            os.path.join(os.path.dirname(__file__), "..", "..", "core", filename),
+            os.path.join(os.path.dirname(__file__), "core", filename),
+            os.path.join("core", filename),
+        ]
+        for path in candidates:
+            if os.path.isfile(path):
+                with open(path) as fh:
+                    for line in fh:
+                        line = line.strip()
+                        if not line or line.startswith("\\"):
+                            continue
+                        result = vm.eval(line)
+                        if not result.startswith("Error:"):
+                            loaded += 1
+                break
+    return loaded
+
+
+def create_vm() -> VM:
+    """Create a fully initialized VM with all primitives and core.fth loaded."""
+    vm = VM()
+    register_all(vm)
+    loaded = load_core(vm)
+    return vm
+
+
+__all__ = [
+    "VM", "Word", "WordType", "Token",
+    "CatalogEntry", "CatalogVersion", "Fact",
+    "Engine",
+    "register_kernel", "register_all", "load_core", "create_vm",
+    "__version__",
+]

uc_forth/__main__.py

@@ -0,0 +1,3 @@
+"""Allow running with `python -m uc_forth`."""
+from .cli import main
+main()

uc_forth/builtins_catalog.py

@@ -0,0 +1,80 @@
+"""Builtin catalog -- stack-effect docs for kernel primitives only."""
+
+from uc_forth.vm import VM, CatalogEntry
+
+# Must import catalog to ensure methods are patched onto VM
+import uc_forth.catalog  # noqa: F401
+
+
+def register_builtin_catalog(vm: VM) -> None:
+    """Add stack-effect documentation for kernel primitives."""
+    entries = {
+        # Stack
+        "DUP":   ("( a -- a a )", "Duplicate top of stack"),
+        "DROP":  ("( a -- )", "Remove top of stack"),
+        "SWAP":  ("( a b -- b a )", "Swap top two values"),
+        "DEPTH": ("( -- n )", "Number of items on stack"),
+
+        # Arithmetic
+        "+":      ("( a b -- a+b )", "Addition"),
+        "-":      ("( a b -- a-b )", "Subtraction"),
+        "*":      ("( a b -- a*b )", "Multiplication"),
+        "/":      ("( a b -- a/b )", "Integer division"),
+        "/MOD":   ("( a b -- rem quot )", "Division with remainder"),
+
+        # Comparison
+        "=":  ("( a b -- flag )", "Equal"),
+        "<":  ("( a b -- flag )", "Less than"),
+        "0=": ("( a -- flag )", "Equal to zero"),
+
+        # Logic
+        "AND": ("( a b -- a&b )", "Bitwise AND"),
+        "OR":  ("( a b -- a|b )", "Bitwise OR"),
+        "XOR": ("( a b -- a^b )", "Bitwise XOR"),
+
+        # Memory
+        "@":        ("( addr -- val )", "Fetch value from address"),
+        "!":        ("( val addr -- )", "Store value at address"),
+        "VARIABLE": ("( -- )", "Create a variable: VARIABLE name"),
+        "CONSTANT": ("( val -- )", "Create a constant: val CONSTANT name"),
+        "ALLOT":    ("( n -- )", "Reserve n cells of memory"),
+        "HERE":     ("( -- addr )", "Current memory pointer"),
+
+        # Return stack
+        ">R": ("( val -- ) R:( -- val )", "Move to return stack"),
+        "R>": ("( -- val ) R:( val -- )", "Move from return stack"),
+
+        # I/O
+        ".":      ("( n -- )", "Print number"),
+        ".S":     ("( -- )", "Show stack contents"),
+        "EMIT":   ("( char -- )", "Print character"),
+
+        # Compiler primitives for POSTPONE-based control structures
+        "POSTPONE":  ("( -- )", "Compile semantics of next word (IMMEDIATE)"),
+        "BODY-HERE": ("( -- addr )", "Current compilation body position"),
+        "BODY,":     ("( val -- )", "Append value to compilation body"),
+        "BODY!":     ("( val addr -- )", "Store value at body position"),
+        "IMMEDIATE": ("( -- )", "Mark last defined word as immediate"),
+        "EXIT":      ("( -- )", "Return from current word"),
+        "(DO)":      ("( limit index -- )", "Runtime: push loop params to return stack"),
+        "(LOOP)":    ("( -- flag )", "Runtime: increment index, push continue flag"),
+        "(+LOOP)":   ("( step -- flag )", "Runtime: add step to index, push continue flag"),
+        "J":         ("( -- index )", "Outer loop counter"),
+        "RECURSE":   ("( -- )", "Call the word being defined"),
+
+        # Compiler
+        ":": ("( -- )", "Begin word definition: : name ... ;"),
+
+        # System
+        "WORDS":  ("( -- )", "List all defined words"),
+        "SEE":    ("( -- )", "Show word definition: SEE name"),
+        ".STACK": ("( -- )", "Display stack contents"),
+    }
+
+    for name, (stack, description) in entries.items():
+        vm.set_catalog_entry(CatalogEntry(
+            name=name,
+            stack=stack,
+            description=description,
+            tags=["builtin"],
+        ))

uc_forth/catalog.py

@@ -0,0 +1,265 @@
+"""Catalog methods for uc-forth VM — ported from Go catalog.go."""
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+from uc_forth.vm import VM, CatalogEntry, CatalogVersion
+
+
+def _set_catalog_entry(self, entry: CatalogEntry) -> None:
+    """Add or update a catalog entry with version tracking."""
+    now = datetime.now(timezone.utc).isoformat()
+    key = entry.name.upper()
+
+    with self._mu:
+        existing = self.catalog.get(key)
+        if existing is not None:
+            # Save previous version to history
+            timestamp = existing.updated_at if existing.updated_at else existing.created
+            history_entry = CatalogVersion(
+                version=existing.version,
+                code=existing.code,
+                author=existing.author,
+                timestamp=timestamp,
+            )
+            entry.history = existing.history + [history_entry]
+            entry.version = existing.version + 1
+            # Preserve original created timestamp
+            if not entry.created:
+                entry.created = existing.created
+        else:
+            entry.version = 1
+            if not entry.created:
+                entry.created = now
+
+        entry.updated_at = now
+        self.catalog[key] = entry
+
+    self._auto_save()
+
+
+def _get_catalog_entry(self, name: str) -> CatalogEntry | None:
+    """Retrieve a catalog entry."""
+    with self._mu:
+        return self.catalog.get(name.upper())
+
+
+def _search_by_tag(self, tag: str) -> list[CatalogEntry]:
+    """Return all words matching a tag."""
+    with self._mu:
+        tag_lower = tag.lower()
+        results = []
+        for entry in self.catalog.values():
+            for entry_tag in entry.tags:
+                if entry_tag.lower() == tag_lower:
+                    results.append(entry)
+                    break
+        return results
+
+
+def _search_by_name(self, substring: str) -> list[CatalogEntry]:
+    """Return all entries where the name contains the substring (case-insensitive)."""
+    with self._mu:
+        sub_upper = substring.upper()
+        results = []
+        for entry in self.catalog.values():
+            if sub_upper in entry.name.upper():
+                results.append(entry)
+        return results
+
+
+def _search_fuzzy(self, query: str) -> list[CatalogEntry]:
+    """Search catalog by name, tags, and description. Scored by relevance."""
+    with self._mu:
+        query_lower = query.lower()
+        words = query_lower.split()
+
+        hits: list[tuple[CatalogEntry, int]] = []
+
+        for entry in self.catalog.values():
+            score = 0
+            name_lower = entry.name.lower()
+            desc_lower = entry.description.lower()
+
+            for word in words:
+                if name_lower == word:
+                    score += 100
+                elif word in name_lower:
+                    score += 50
+
+                for tag in entry.tags:
+                    tag_lower = tag.lower()
+                    if tag_lower == word:
+                        score += 30
+                    elif word in tag_lower:
+                        score += 15
+
+                if word in desc_lower:
+                    score += 10
+
+                if word in entry.stack.lower():
+                    score += 5
+
+            if score > 0:
+                hits.append((entry, score))
+
+        hits.sort(key=lambda item: item[1], reverse=True)
+        return [entry for entry, _score in hits]
+
+
+def _all_catalog_entries(self) -> list[CatalogEntry]:
+    """Return the full catalog."""
+    with self._mu:
+        return list(self.catalog.values())
+
+
+def _catalog_dump(self) -> bytes:
+    """Export the catalog as JSON bytes."""
+    entries = self.all_catalog_entries()
+    data = {
+        "version": "1.0",
+        "exported": datetime.now(timezone.utc).isoformat(),
+        "word_count": len(entries),
+        "words": [_entry_to_dict(entry) for entry in entries],
+    }
+    return json.dumps(data, indent=2).encode("utf-8")
+
+
+def _catalog_load(self, data: bytes) -> None:
+    """Import a catalog from JSON bytes."""
+    parsed = json.loads(data)
+    for word_data in parsed.get("words", []):
+        entry = _dict_to_entry(word_data)
+        self.set_catalog_entry(entry)
+        # Eval the code to define the word — but skip builtin words
+        # (those come from core.fth and modules, reloading them causes issues
+        # with IMMEDIATE words and compile-time stack manipulation)
+        if entry.code and entry.author != "forth":
+            self.eval(entry.code)
+
+
+def _catalog_save(self, filename: str) -> None:
+    """Save the catalog to a file."""
+    data = self.catalog_dump()
+    with open(filename, "wb") as fh:
+        fh.write(data)
+
+
+def _catalog_load_file(self, filename: str) -> None:
+    """Load a catalog from a file."""
+    with open(filename, "rb") as fh:
+        data = fh.read()
+    self.catalog_load(data)
+
+
+def _enable_auto_save(self, filename: str) -> None:
+    """Activate automatic catalog persistence."""
+    directory = os.path.dirname(filename)
+    if directory:
+        try:
+            os.makedirs(directory, exist_ok=True)
+        except OSError as exc:
+            print(f"Warning: cannot create catalog directory {directory}: {exc}", file=sys.stderr)
+            return
+
+    self.catalog_file = filename
+    self.auto_save_enabled = True
+
+    # Load existing catalog if the file exists
+    if os.path.isfile(filename):
+        try:
+            self.catalog_load_file(filename)
+        except Exception as exc:
+            print(f"Warning: could not load catalog {filename}: {exc}", file=sys.stderr)
+
+
+def _auto_save(self) -> None:
+    """Persist the catalog if auto-save is enabled."""
+    if not self.auto_save_enabled:
+        return
+    try:
+        self.catalog_save(self.catalog_file)
+    except Exception:
+        pass
+
+
+# -- Serialization helpers --
+
+def _entry_to_dict(entry: CatalogEntry) -> dict:
+    result = {
+        "name": entry.name,
+        "stack": entry.stack,
+        "description": entry.description,
+        "tags": entry.tags,
+        "version": entry.version,
+    }
+    if entry.code:
+        result["code"] = entry.code
+    if entry.depends:
+        result["depends"] = entry.depends
+    if entry.author:
+        result["author"] = entry.author
+    if entry.created:
+        result["created"] = entry.created
+    if entry.updated_at:
+        result["updated_at"] = entry.updated_at
+    if entry.test_in:
+        result["test_in"] = entry.test_in
+    if entry.test_out:
+        result["test_out"] = entry.test_out
+    if entry.history:
+        result["history"] = [
+            {
+                "version": hist.version,
+                "code": hist.code,
+                "author": hist.author,
+                "timestamp": hist.timestamp,
+            }
+            for hist in entry.history
+        ]
+    return result
+
+
+def _dict_to_entry(data: dict) -> CatalogEntry:
+    history = []
+    for hist_data in data.get("history", []):
+        history.append(CatalogVersion(
+            version=hist_data.get("version", 0),
+            code=hist_data.get("code", ""),
+            author=hist_data.get("author", ""),
+            timestamp=hist_data.get("timestamp", ""),
+        ))
+
+    return CatalogEntry(
+        name=data.get("name", ""),
+        code=data.get("code", ""),
+        stack=data.get("stack", ""),
+        description=data.get("description", ""),
+        tags=data.get("tags", []),
+        depends=data.get("depends", []),
+        author=data.get("author", ""),
+        created=data.get("created", ""),
+        test_in=data.get("test_in", ""),
+        test_out=data.get("test_out", ""),
+        version=data.get("version", 0),
+        updated_at=data.get("updated_at", ""),
+        history=history,
+    )
+
+
+# -- Monkey-patch methods onto VM --
+
+VM.set_catalog_entry = _set_catalog_entry
+VM.get_catalog_entry = _get_catalog_entry
+VM.search_by_tag = _search_by_tag
+VM.search_by_name = _search_by_name
+VM.search_fuzzy = _search_fuzzy
+VM.all_catalog_entries = _all_catalog_entries
+VM.catalog_dump = _catalog_dump
+VM.catalog_load = _catalog_load
+VM.catalog_save = _catalog_save
+VM.catalog_load_file = _catalog_load_file
+VM.enable_auto_save = _enable_auto_save
+VM._auto_save = _auto_save

uc_forth/catalog_primitives.py

@@ -0,0 +1,144 @@
+"""Catalog introspection primitives -- ported from Go catalog_primitives.go."""
+
+from uc_forth.vm import VM, CatalogEntry, Word, WordType
+from uc_forth.primitives import prim
+
+# Must import catalog to ensure methods are patched onto VM
+import uc_forth.catalog  # noqa: F401
+
+
+def format_catalog_entry(entry: CatalogEntry) -> str:
+    """Format a catalog entry for display."""
+    parts = [f"Name: {entry.name}"]
+
+    word_type = "compiled" if entry.code else "primitive"
+    parts.append(f"Type: {word_type}")
+
+    if entry.stack:
+        parts.append(f"Stack: {entry.stack}")
+    if entry.description:
+        parts.append(f"Description: {entry.description}")
+    if entry.tags:
+        parts.append(f"Tags: {', '.join(entry.tags)}")
+    if entry.author:
+        parts.append(f"Author: {entry.author}")
+
+    return "\n".join(parts) + "\n"
+
+
+def register_catalog_primitives(vm: VM) -> None:
+    """Add catalog introspection words and their catalog entries to the VM."""
+
+    # CAN? ( search-str -- result-str )
+    def _can(vm: VM) -> None:
+        idx = vm.must_pop()
+        if vm.aborted:
+            return
+        search, ok = vm.get_string(idx)
+        if not ok:
+            vm.abort("invalid string reference")
+            return
+
+        results = vm.search_fuzzy(search)
+        names = [entry.name for entry in results]
+        vm.push(vm.store_string("\n".join(names)))
+
+    prim(vm, "CAN?", _can)
+
+    # CAN-TAG? ( tag-str -- result-str )
+    def _can_tag(vm: VM) -> None:
+        idx = vm.must_pop()
+        if vm.aborted:
+            return
+        tag, ok = vm.get_string(idx)
+        if not ok:
+            vm.abort("invalid string reference")
+            return
+
+        results = vm.search_by_tag(tag)
+        names = [entry.name for entry in results]
+        vm.push(vm.store_string("\n".join(names)))
+
+    prim(vm, "CAN-TAG?", _can_tag)
+
+    # ABOUT ( name-str -- )
+    def _about(vm: VM) -> None:
+        idx = vm.must_pop()
+        if vm.aborted:
+            return
+        name, ok = vm.get_string(idx)
+        if not ok:
+            vm.abort("invalid string reference")
+            return
+
+        entry = vm.get_catalog_entry(name)
+        if entry is None:
+            vm.abort(f"no catalog entry for {name}")
+            return
+
+        vm.write_string(format_catalog_entry(entry))
+
+    prim(vm, "ABOUT", _about)
+
+    # ABOUT>STR ( name-str -- info-str )
+    def _about_str(vm: VM) -> None:
+        idx = vm.must_pop()
+        if vm.aborted:
+            return
+        name, ok = vm.get_string(idx)
+        if not ok:
+            vm.abort("invalid string reference")
+            return
+
+        entry = vm.get_catalog_entry(name)
+        if entry is None:
+            vm.abort(f"no catalog entry for {name}")
+            return
+
+        vm.push(vm.store_string(format_catalog_entry(entry)))
+
+    prim(vm, "ABOUT>STR", _about_str)
+
+    # WORD-COUNT ( -- n )
+    def _word_count(vm: VM) -> None:
+        entries = vm.all_catalog_entries()
+        vm.push(len(entries))
+
+    prim(vm, "WORD-COUNT", _word_count)
+
+    # WORD-VERSION ( name-str -- n )
+    def _word_version(vm: VM) -> None:
+        idx = vm.must_pop()
+        if vm.aborted:
+            return
+        name, ok = vm.get_string(idx)
+        if not ok:
+            vm.abort("invalid string reference")
+            return
+
+        entry = vm.get_catalog_entry(name)
+        if entry is None:
+            vm.abort(f"no catalog entry for {name}")
+            return
+
+        vm.push(entry.version)
+
+    prim(vm, "WORD-VERSION", _word_version)
+
+    # Catalog entries
+    entries = {
+        "CAN?":         ("( search-str -- result-str )", "Search catalog by tag or name substring, returns matching word names"),
+        "CAN-TAG?":     ("( tag-str -- result-str )", "Search catalog by tag only"),
+        "ABOUT":        ("( name-str -- )", "Print catalog info for a word"),
+        "ABOUT>STR":    ("( name-str -- info-str )", "Return catalog info for a word as string"),
+        "WORD-COUNT":   ("( -- n )", "Number of catalog entries"),
+        "WORD-VERSION": ("( name-str -- n )", "Get version number of a catalog entry"),
+    }
+
+    for name, (stack, description) in entries.items():
+        vm.set_catalog_entry(CatalogEntry(
+            name=name,
+            stack=stack,
+            description=description,
+            tags=["builtin", "catalog"],
+        ))