godcode-engine 4.0.0__py3-none-any.whl

godcode/environment.py

@@ -0,0 +1,74 @@
+"""Lexically scoped environments for God Code.
+
+Scope rule: names resolve outward through parent environments. An unbound
+name does not raise — it resolves to a Symbol of that name, because in God
+Code every unnamed thing is still a named spirit (this is what makes
+`DECLARE seeker AS worthy` / `IF seeker IS worthy` work with no prior
+binding of `worthy`).
+
+DECLARE always defines in the *current* environment; it never rebinds an
+outer scope. Use set_existing() to reshape a name that must already exist.
+"""
+
+from __future__ import annotations
+
+from typing import Iterator
+
+from godcode.errors import GodRuntimeError
+from godcode.values import Symbol
+
+
+class Environment:
+    def __init__(self, parent: "Environment | None" = None):
+        self.parent = parent
+        self._bindings: dict[str, object] = {}
+
+    def define(self, name: str, value: object) -> None:
+        """Bind name in this environment, shadowing any outer binding."""
+        self._bindings[name] = value
+
+    def get(self, name: str) -> object:
+        """Walk outward for name; return Symbol(name) if nowhere bound."""
+        env: Environment | None = self
+        while env is not None:
+            if name in env._bindings:
+                return env._bindings[name]
+            env = env.parent
+        return Symbol(name)
+
+    def is_bound(self, name: str) -> bool:
+        """True if name is bound in this environment or any ancestor."""
+        env: Environment | None = self
+        while env is not None:
+            if name in env._bindings:
+                return True
+            env = env.parent
+        return False
+
+    def set_existing(self, name: str, value: object) -> None:
+        """Reshape an already-bound name where it lives; error if unbound."""
+        env: Environment | None = self
+        while env is not None:
+            if name in env._bindings:
+                env._bindings[name] = value
+                return
+            env = env.parent
+        raise GodRuntimeError(
+            f"There is no '{name}' to reshape — it was never spoken into being."
+        )
+
+    def names(self) -> list[str]:
+        """All visible names, innermost scope first, without duplicates."""
+        seen: list[str] = []
+        env: Environment | None = self
+        while env is not None:
+            for key in env._bindings:
+                if key not in seen:
+                    seen.append(key)
+            env = env.parent
+        return seen
+
+    def items(self) -> Iterator[tuple[str, object]]:
+        """(name, value) pairs for every visible name, innermost first."""
+        for name in self.names():
+            yield name, self.get(name)

godcode/errors.py

@@ -0,0 +1,69 @@
+"""Error hierarchy for God Code v2.0.
+
+All errors carry line (and where known, column) numbers so the faithful
+can find where the heavens objected. Messages are divine-flavored but
+genuinely helpful -- never mocking.
+
+Control-flow signals (ReturnSignal / AscendSignal) are plain Exceptions,
+*not* GodCodeError subclasses, so a broad ``except GodCodeError`` in the
+interpreter can never accidentally swallow a return or an ascension.
+"""
+
+from __future__ import annotations
+
+
+class GodCodeError(Exception):
+    """Base class for every God Code failure. ``line``/``col`` are 1-based."""
+
+    def __init__(self, msg: str, line: int | None = None, col: int | None = None):
+        super().__init__(msg)
+        self.msg = msg
+        self.line = line
+        self.col = col
+
+    def __str__(self) -> str:
+        if self.line is None or f"line {self.line}" in self.msg:
+            return self.msg
+        loc = f" (line {self.line}"
+        if self.col is not None:
+            loc += f", col {self.col}"
+        return self.msg + loc + ")"
+
+
+class LexerError(GodCodeError):
+    """The source could not be turned into tokens."""
+
+
+class ParseError(GodCodeError):
+    """The tokens did not form a holy grammar."""
+
+
+class GodRuntimeError(GodCodeError):
+    """The creation failed while it was being brought to life.
+
+    Named to avoid clashing with the builtin RuntimeError.
+    """
+
+
+class SandboxViolation(GodCodeError):
+    """A power the sandbox withholds.
+
+    Raised when a creation running under ``godcode.sandbox`` reaches for
+    something its policy does not grant: a forbidden scroll, a denied
+    rite (such as ASK when stdin is closed), a spent step budget, or an
+    expired time grant. Carries a line number like every other
+    GodCodeError, so the faithful can see exactly where the heavens
+    objected.
+    """
+
+
+class ReturnSignal(Exception):
+    """Carries a rite's return value up to the rite-call boundary."""
+
+    def __init__(self, value=None):
+        super().__init__(value)
+        self.value = value
+
+
+class AscendSignal(Exception):
+    """Raised by ASCEND; ends the creation in peace."""