plan-kernel 0.1.1__py3-none-any.whl

plan_kernel/__init__.py

@@ -0,0 +1,3 @@
+"""plan-kernel — a Jupyter kernel for the PLAN virtual machine."""
+
+__version__ = "0.1.0"

plan_kernel/__main__.py

@@ -0,0 +1,14 @@
+"""``python -m plan_kernel`` entry point.
+
+With no args (or with ``-f <connection_file>`` supplied by Jupyter) this
+launches the kernel. With the ``install`` subcommand it registers the
+kernelspec.
+"""
+
+import sys
+
+from .kernel import _cli_main
+
+
+if __name__ == "__main__":
+    sys.exit(_cli_main(sys.argv))

plan_kernel/evaluator.py

@@ -0,0 +1,305 @@
+"""Cell-level driver.
+
+``PlanKernelEvaluator`` ties parser → expander → runtime together with a
+notebook-scoped ``Env``. ``eval_cell(source)`` returns a ``CellResult`` that
+the kernel layer (phase 8) translates into a Jupyter MIME bundle.
+
+Pipeline per cell: parse leading magics → apply them → parse_many on the
+remaining body → for each form, macroexpand → thunk → backend evaluator.
+Bind-only and trailing-bind cells produce ``bind <name>`` summary lines;
+expression cells render the last form's value via ``plan_kernel.render``. Per-
+stage exceptions become structured error envelopes; Python's recursion
+limit is bumped to 200K so user-level recursion gets a fair shot.
+
+Magic semantics:
+- ``%backend NAME`` is per-cell — the backend reverts at end-of-cell.
+- ``%reset`` is persistent — cleared bindings stay cleared.
+- ``%env`` is read-only.
+
+Deferred to phase 7: BPLAN op prelude auto-loading. ``%reset`` will
+preserve the prelude once that lands.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+
+from .expander import Env, MacroError, macroexpand, thunk
+from .magics import MagicDirective, MagicError, parse_magics
+from .parser import ParseError, parse_many
+from .prelude import load_prelude
+from .render import render_value
+from .runtime.plan import (
+    is_nat,
+    nat_str, str_nat,
+    evaluate,
+    _unapp,
+)
+
+
+__all__ = ["CellResult", "PlanKernelEvaluator"]
+
+
+_BIND_NAT = str_nat("#bind")
+
+
+# ---------------------------------------------------------------------------
+# CellResult — public output shape (mirrors gallowglass's kernel).
+# ---------------------------------------------------------------------------
+
+@dataclass
+class CellResult:
+    """Result of evaluating one cell.
+
+    Exactly one of ``value_text`` / ``error`` is populated for non-silent
+    cells. ``decls_only=True`` indicates a silent cell (empty source, or all
+    forms were silent assignments with no displayable summary).
+    """
+
+    value_text: str | None = None
+    value_html: str | None = None
+    error: dict | None = None
+    decls_only: bool = False
+
+
+# ---------------------------------------------------------------------------
+# Internal error envelope — same shape as gallowglass's ``_error_envelope``.
+# ---------------------------------------------------------------------------
+
+def _error_envelope(stage: str, err: Exception) -> dict:
+    loc = None
+    if isinstance(err, ParseError):
+        loc = {"file": None, "line": err.line, "col": err.col}
+    return {
+        "stage": stage,
+        "message": str(err),
+        "type": type(err).__name__,
+        "loc": loc,
+    }
+
+
+def _stage_for(err: Exception) -> str:
+    if isinstance(err, ParseError):
+        return "parse"
+    if isinstance(err, MacroError):
+        return "expand"
+    if isinstance(err, MagicError):
+        return "magic"
+    if isinstance(err, RecursionError):
+        return "runtime"
+    return "internal"
+
+
+# ---------------------------------------------------------------------------
+# Helpers.
+# ---------------------------------------------------------------------------
+
+def _pretty_nat(n) -> str:
+    # ``n`` may be a Marduk ``Val`` (post Phase E swap) or a raw int
+    # (legacy callers). Normalize to int via ``.nat`` when needed.
+    if hasattr(n, "type") and n.type == "nat":
+        n = n.nat
+    if not isinstance(n, int):
+        return repr(n)
+    s = nat_str(n)
+    if s and not s.startswith("<nat:"):
+        return s
+    return str(n)
+
+
+def _is_bind_form(form) -> bool:
+    """Structurally check whether ``form`` is a ``(#bind ...)`` macro call."""
+    parts = _unapp(form)
+    return (
+        len(parts) >= 2
+        and is_nat(parts[0]) and parts[0].nat == 0
+        and is_nat(parts[1]) and parts[1].nat == _BIND_NAT
+    )
+
+
+
+
+# ---------------------------------------------------------------------------
+# PlanKernelEvaluator.
+# ---------------------------------------------------------------------------
+
+class PlanKernelEvaluator:
+    """Stateful plan-kernel evaluator.
+
+    Owns a notebook-scoped ``Env``. ``eval_cell(source)`` parses, expands,
+    and evaluates one cell, returning a ``CellResult``. Side-effects from
+    ``#bind`` accumulate across cells.
+
+    Parameters
+    ----------
+    env
+        A pre-existing ``Env`` to use; if ``None``, a fresh empty one is
+        created. Useful when the kernel needs to share an env across
+        instances.
+    backend
+        Either ``"evaluate"`` (formal Python evaluator, default) or
+        ``"bevaluate"`` (jet-aware, faster for arithmetic). The
+        ``%backend`` magic switches this at cell granularity.
+    prelude
+        If ``True`` (default), load the BPLAN op prelude into ``env`` so
+        ``(Add 2 3)`` and friends work in cell 1. ``%reset`` reloads the
+        prelude. Pass ``False`` for a fully empty env.
+    """
+
+    def __init__(self, env: Env | None = None, backend: str = "evaluate",
+                 prelude: bool = True):
+        self.env = env if env is not None else Env()
+        self._set_backend(backend)
+        self._prelude_loaded = bool(prelude)
+        self._prelude_names: set[int] = set()
+        if prelude:
+            self._prelude_names = load_prelude(self.env)
+
+    # ------------------------------------------------------------------
+    # Public entry points.
+    # ------------------------------------------------------------------
+
+    def eval_cell(self, source: str) -> CellResult:
+        if not source.strip():
+            return CellResult(decls_only=True)
+
+        directives, body = parse_magics(source)
+
+        # Save backend state for cell-scoped %backend reverts. (env/reset
+        # changes deliberately persist.)
+        saved_backend = self._backend
+        saved_backend_name = self._backend_name
+        try:
+            magic_outputs: list[str] = []
+            try:
+                for d in directives:
+                    out = self._apply_magic(d)
+                    if out is not None:
+                        magic_outputs.append(out)
+            except MagicError as e:
+                return CellResult(error=_error_envelope("magic", e))
+
+            return self._eval_body(body, magic_outputs)
+        finally:
+            self._backend = saved_backend
+            self._backend_name = saved_backend_name
+
+    def _eval_body(self, body: str, magic_outputs: list[str]) -> CellResult:
+        if not body.strip():
+            if magic_outputs:
+                return CellResult(value_text="\n".join(magic_outputs))
+            return CellResult(decls_only=True)
+
+        try:
+            forms = parse_many(body)
+        except ParseError as e:
+            return CellResult(error=_error_envelope("parse", e))
+        except Exception as e:    # pragma: no cover — defensive
+            return CellResult(error=_error_envelope("internal", e))
+
+        if not forms:
+            if magic_outputs:
+                return CellResult(value_text="\n".join(magic_outputs))
+            return CellResult(decls_only=True)
+
+        old_limit = sys.getrecursionlimit()
+        sys.setrecursionlimit(max(old_limit, 200_000))
+        try:
+            result = self._evaluate_forms(forms)
+        except (MacroError, RecursionError) as e:
+            return CellResult(error=_error_envelope(_stage_for(e), e))
+        except Exception as e:
+            return CellResult(error=_error_envelope("internal", e))
+        finally:
+            sys.setrecursionlimit(old_limit)
+
+        if magic_outputs and result.value_text is not None:
+            result.value_text = "\n".join(magic_outputs) + "\n" + result.value_text
+        return result
+
+    def reset(self) -> None:
+        """Clear all user bindings. The prelude (if loaded) is reloaded."""
+        self.env.reset()
+        if self._prelude_loaded:
+            self._prelude_names = load_prelude(self.env)
+
+    @property
+    def backend_name(self) -> str:
+        return self._backend_name
+
+    # ------------------------------------------------------------------
+    # Internals.
+    # ------------------------------------------------------------------
+
+    def _set_backend(self, name: str) -> None:
+        if name == "evaluate":
+            self._backend = evaluate
+            self._backend_name = name
+            return
+        if name == "bevaluate":
+            # Resolved on first use (lazy import — bplan pulls in jet
+            # registration code we don't need until selected).
+            from .runtime.bplan import bevaluate
+            self._backend = bevaluate
+            self._backend_name = name
+            return
+        raise ValueError(
+            f"unknown backend: {name!r} (expected 'evaluate' or 'bevaluate')"
+        )
+
+    def _apply_magic(self, d: MagicDirective) -> str | None:
+        """Apply one magic directive. Returns optional display output."""
+        if d.name == "backend":
+            if len(d.args) != 1:
+                raise MagicError(f"{d.line}: %backend takes exactly one argument")
+            try:
+                self._set_backend(d.args[0])
+            except ValueError as e:
+                raise MagicError(f"{d.line}: {e}") from e
+            return None
+        if d.name == "reset":
+            if d.args:
+                raise MagicError(f"{d.line}: %reset takes no arguments")
+            self.reset()
+            return None
+        if d.name == "env":
+            if d.args:
+                raise MagicError(f"{d.line}: %env takes no arguments")
+            user_names = sorted(
+                _pretty_nat(n)
+                for n in self.env.names()
+                if n not in self._prelude_names
+            )
+            return ", ".join(user_names) if user_names else "(env empty)"
+        raise MagicError(f"unknown magic: %{d.name}")
+
+    def _eval_one(self, form):
+        """Run one form through expand → thunk → backend."""
+        expanded = macroexpand(form, self.env)
+        thunked = thunk(expanded, self.env)
+        return self._backend(thunked)
+
+    def _evaluate_forms(self, forms) -> CellResult:
+        bind_summaries: list[str] = []
+        last_value = None
+        last_was_bind = False
+
+        for form in forms:
+            is_bind = _is_bind_form(form)
+            result = self._eval_one(form)
+            if is_bind:
+                bind_summaries.append(f"bind {_pretty_nat(result)}")
+            else:
+                last_value = result
+            last_was_bind = is_bind
+
+        # Trailing-bind cells (and all-binds cells) display the bind summary
+        # block; expression-cells display their final value.
+        if last_was_bind:
+            if not bind_summaries:
+                return CellResult(decls_only=True)    # pragma: no cover
+            return CellResult(value_text="\n".join(bind_summaries))
+
+        text, html = render_value(last_value)
+        return CellResult(value_text=text, value_html=html)

plan_kernel/expander.py

@@ -0,0 +1,23 @@
+"""Macro expander — compatibility shim.
+
+Lifted to :mod:`marduk.asm.expander` as part of the Phase E Marduk swap.
+This module re-exports the same API for callers that still import via
+``plan_kernel.expander``. New code should import from ``marduk.asm``.
+"""
+
+from marduk.asm.expander import (
+    Env,
+    MacroError,
+    macroexpand,
+    thunk,
+    eval_form,
+)
+
+
+__all__ = [
+    "Env",
+    "MacroError",
+    "macroexpand",
+    "thunk",
+    "eval_form",
+]

plan_kernel/kernel.py

@@ -0,0 +1,219 @@
+"""Jupyter kernel and CLI entry points.
+
+Two surface areas:
+
+- :func:`_kernel_main` — invoked via ``python -m plan_kernel`` (i.e.
+  ``plan_kernel/__main__.py``). Lazy-imports ``ipykernel`` and launches the
+  kernel via ``IPKernelApp.launch_instance``.
+
+- :func:`_install_kernelspec` — registers ``PLAN`` with Jupyter's
+  ``KernelSpecManager`` so the kernel picker shows it. The kernel.json's
+  ``argv`` is ``[sys.executable, '-m', 'plan_kernel', '-f', '{connection_file}']``,
+  so launching the kernel reuses the Python interpreter that ran ``install``.
+
+The ``PlanKernel`` class is defined inside :func:`_kernel_main` so that
+importing this module doesn't pull in ``ipykernel`` — that keeps test
+environments without ``ipykernel`` (and the kernel-startup path itself)
+fast and importable.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import tempfile
+import traceback
+
+
+__all__ = [
+    "_install_kernelspec",
+    "_kernel_main",
+    "_cli_main",
+]
+
+
+_KERNEL_NAME = "plan_kernel"
+_DISPLAY_NAME = "PLAN"
+_IMPLEMENTATION = "plan-kernel"
+
+
+def _kernel_main() -> None:
+    """Launch the kernel under ``ipykernel.IPKernelApp.launch_instance``."""
+    from ipykernel.kernelapp import IPKernelApp
+    from ipykernel.kernelbase import Kernel
+
+    from . import __version__
+    from .evaluator import PlanKernelEvaluator
+
+    class PlanKernel(Kernel):
+        implementation = _IMPLEMENTATION
+        implementation_version = __version__
+        language_info = {
+            "name": "plan",
+            "mimetype": "text/x-plan",
+            "file_extension": ".plan",
+            "pygments_lexer": "lisp",
+        }
+        banner = (
+            "PLAN kernel (plan-kernel) — type Plan Asm in a cell, see the reduced "
+            "PLAN value back. The BPLAN op prelude is auto-loaded; %backend, "
+            "%reset, %env are available as cell magics."
+        )
+
+        def __init__(self, **kwargs):
+            super().__init__(**kwargs)
+            self._evaluator = PlanKernelEvaluator()
+
+        def do_execute(self, code, silent, store_history=True,
+                       user_expressions=None, allow_stdin=False, *,
+                       cell_id=None):
+            try:
+                result = self._evaluator.eval_cell(code)
+            except Exception as e:    # noqa: BLE001 — last-resort guard
+                tb = traceback.format_exception(type(e), e, e.__traceback__)
+                if not silent:
+                    self.send_response(self.iopub_socket, "stream", {
+                        "name": "stderr",
+                        "text": "".join(tb),
+                    })
+                return {
+                    "status": "error",
+                    "execution_count": self.execution_count,
+                    "ename": type(e).__name__,
+                    "evalue": str(e),
+                    "traceback": tb,
+                }
+
+            if result.error is not None:
+                error_text = _format_error(result.error)
+                if not silent:
+                    self.send_response(self.iopub_socket, "stream", {
+                        "name": "stderr",
+                        "text": error_text,
+                    })
+                return {
+                    "status": "error",
+                    "execution_count": self.execution_count,
+                    "ename": result.error.get("type", "Error"),
+                    "evalue": result.error.get("message", ""),
+                    "traceback": [error_text],
+                }
+
+            if result.value_text is not None and not silent:
+                data = {"text/plain": result.value_text}
+                if result.value_html is not None:
+                    data["text/html"] = result.value_html
+                self.send_response(self.iopub_socket, "execute_result", {
+                    "execution_count": self.execution_count,
+                    "data": data,
+                    "metadata": {},
+                })
+
+            return {
+                "status": "ok",
+                "execution_count": self.execution_count,
+                "payload": [],
+                "user_expressions": {},
+            }
+
+    IPKernelApp.launch_instance(kernel_class=PlanKernel)
+
+
+def _format_error(envelope: dict) -> str:
+    """Render an error envelope for the Jupyter ``stream`` channel.
+
+    Format: ``[file:line:col: ]<stage> error: <message>``. The location
+    block is dropped when no ``loc`` is present (most expand/runtime
+    errors).
+    """
+    stage = envelope.get("stage", "error")
+    msg = envelope.get("message", "")
+    loc = envelope.get("loc")
+    if loc is not None:
+        file_part = loc.get("file") or "<cell>"
+        prefix = f"{file_part}:{loc['line']}:{loc['col']}: "
+    else:
+        prefix = ""
+    return f"{prefix}{stage} error: {msg}\n"
+
+
+def _install_kernelspec(user: bool = True, prefix: str | None = None) -> str:
+    """Register the plan-kernel kernelspec with Jupyter.
+
+    Returns the install path (the directory containing ``kernel.json``).
+
+    Parameters
+    ----------
+    user
+        Install to the per-user kernels directory (default). Set to
+        ``False`` together with a ``prefix`` for an isolated install.
+    prefix
+        Optional prefix path. When set, the kernelspec is written under
+        ``<prefix>/share/jupyter/kernels/plan-kernel/``. Useful for venv-scoped
+        installs (``--prefix .venv``).
+    """
+    from jupyter_client.kernelspec import KernelSpecManager
+
+    spec = {
+        "argv": [
+            sys.executable,
+            "-m",
+            "plan_kernel",
+            "-f",
+            "{connection_file}",
+        ],
+        "display_name": _DISPLAY_NAME,
+        "language": "plan",
+        "metadata": {
+            "description": "plan-kernel — Jupyter kernel for the PLAN virtual machine",
+        },
+    }
+
+    with tempfile.TemporaryDirectory() as td:
+        spec_path = os.path.join(td, "kernel.json")
+        with open(spec_path, "w") as f:
+            json.dump(spec, f, indent=2)
+        ksm = KernelSpecManager()
+        installed = ksm.install_kernel_spec(
+            td,
+            kernel_name=_KERNEL_NAME,
+            user=user,
+            prefix=prefix,
+        )
+    return installed
+
+
+def _cli_main(argv: list[str]) -> int:
+    """CLI entry point. Returns process exit code.
+
+    Subcommands:
+    - ``plan-kernel install [--prefix DIR] [--system]`` registers the
+      kernelspec and prints the install path.
+    - Any other invocation (typically ``-f <connection_file>`` from
+      Jupyter) falls through to :func:`_kernel_main`.
+    """
+    if len(argv) >= 2 and argv[1] == "install":
+        parser = argparse.ArgumentParser(
+            prog="plan-kernel install",
+            description="Register the plan-kernel kernelspec with Jupyter.",
+        )
+        parser.add_argument(
+            "--prefix",
+            default=None,
+            help="install under PREFIX/share/jupyter/kernels/plan-kernel (overrides --user)",
+        )
+        parser.add_argument(
+            "--system",
+            action="store_true",
+            help="install system-wide instead of per-user (the default)",
+        )
+        args = parser.parse_args(argv[2:])
+        user = not args.system and args.prefix is None
+        installed = _install_kernelspec(user=user, prefix=args.prefix)
+        print(f"Installed plan-kernel kernelspec at {installed}")
+        return 0
+
+    _kernel_main()
+    return 0

plan_kernel/magics.py

@@ -0,0 +1,72 @@
+"""Cell-leading ``%magic`` parsing.
+
+A cell's *magic block* is its run of leading ``%``-prefixed lines, with
+blank lines between them allowed once at least one magic has been seen.
+Anything else — comments, source forms, blank cells — ends the magic
+block, and the rest is the cell's source body.
+
+Three magics are recognized by the evaluator:
+
+- ``%backend evaluate | bevaluate`` — pick the runtime evaluator. The
+  evaluator scopes this to the current cell only.
+- ``%reset`` — clear all bindings from the env. (Persistent.)
+- ``%env`` — display the names currently bound. (Read-only.)
+
+This module just *parses* the magic block; the evaluator dispatches each
+directive (and decides what counts as a per-cell vs. persistent action).
+Unknown directives are returned as-is — the dispatcher raises
+``MagicError`` if it can't handle one.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+__all__ = ["MagicDirective", "MagicError", "parse_magics"]
+
+
+class MagicError(Exception):
+    """Raised when a magic directive is malformed, unsupported, or its
+    arguments don't validate."""
+
+
+@dataclass
+class MagicDirective:
+    name: str                            # e.g. 'backend', 'reset', 'env'
+    args: list[str] = field(default_factory=list)
+
+    @property
+    def line(self) -> str:
+        if not self.args:
+            return f"%{self.name}"
+        return f"%{self.name} {' '.join(self.args)}"
+
+
+def parse_magics(source: str) -> tuple[list[MagicDirective], str]:
+    """Split a cell's leading ``%magic`` lines from its source body.
+
+    The body retains its original indentation/whitespace — only the
+    consumed magic lines (and any blank lines between them) are removed.
+    """
+    lines = source.splitlines(keepends=True)
+    directives: list[MagicDirective] = []
+    i = 0
+    while i < len(lines):
+        stripped = lines[i].lstrip()
+        if stripped.startswith("%"):
+            tokens = stripped[1:].split()
+            if not tokens:
+                # Bare `%` line — not a magic; treat as body so the user
+                # gets a clear parse error rather than a silent skip.
+                break
+            directives.append(MagicDirective(name=tokens[0], args=tokens[1:]))
+            i += 1
+            continue
+        if stripped == "" and directives:
+            # Blank line *between* magics — absorb so a multi-magic block
+            # can be visually separated without breaking the parse.
+            i += 1
+            continue
+        break
+    return directives, "".join(lines[i:])

plan_kernel/parser.py

@@ -0,0 +1,11 @@
+"""Plan Asm reader — compatibility shim.
+
+Lifted to :mod:`marduk.asm.reader` as part of the Phase E Marduk swap.
+This module re-exports the same API for callers that still import via
+``plan_kernel.parser``. New code should import from ``marduk.asm``.
+"""
+
+from marduk.asm.reader import ParseError, parse, parse_many
+
+
+__all__ = ["ParseError", "parse", "parse_many"]