co-lambda 0.5.0__py3-none-any.whl

co_lambda/_hoas_latex.py

@@ -0,0 +1,144 @@
+"""Render a HOAS ``Builder`` term, with readable binder names and named constants, to LaTeX or to text.
+
+``_latex.term_to_latex`` renders the built de Bruijn ``Node``: it names binders ``x, y, z, ...`` by level
+and fully expands every constant, so a term built from a library (edit distance over ``Y``, the BinNat
+arithmetic, the Scott list) comes out as one enormous nameless expression. Here we render the ``Builder``
+instead, so a binder shows the name of the Python ``lambda`` parameter that introduced it, and a sub-term
+that *is* a named library constant, recognised by object identity through a caller-supplied ``names`` map,
+shows that name rather than being expanded. A definition therefore reads as itself and cross-references the
+others by name. This is what generates the paper's edit-distance code listing from the source terms.
+
+Two ``Style`` presets format the same structure differently: ``MATH_STYLE`` for inline LaTeX math (used in
+the prose), ``TEXT_STYLE`` for the ASCII lambda syntax of an auto-wrapping ``lstlisting`` (the appendix
+code listing, where math would overflow the line). ``names`` maps an ``id`` to the constant's *base* name
+(``"eq"``, ``"Y"``, ``"ed"``); the style turns that base into the rendered token.
+"""
+
+from __future__ import annotations
+
+import inspect
+
+from dataclasses import dataclass
+from typing import Callable, final
+
+from co_lambda._dsl import Builder, _AppBuilder, _LamBuilder, _VarBuilder
+
+
+@final
+@dataclass(frozen=True, kw_only=True, slots=True)
+class Style:
+    """How to format the four syntactic pieces, so one renderer serves both LaTeX math and ASCII text."""
+
+    constant: Callable[[str], str]
+    binder: Callable[[str], str]
+    abstraction: Callable[[str, str], str]
+    application: Callable[[str, str], str]
+    parenthesise: Callable[[str], str]
+
+
+def _math_constant(name: str) -> str:
+    return name if len(name) == 1 else f"\\mathtt{{{name}}}"
+
+
+def _math_binder(name: str) -> str:
+    head, _, tail = name.partition("_")
+    base = head if len(head) == 1 else f"\\mathit{{{head}}}"
+    return base if not tail else f"{base}_{{{tail}}}"
+
+
+MATH_STYLE: Style = Style(
+    constant=_math_constant,
+    binder=_math_binder,
+    abstraction=lambda binder, body: f"\\lambda {binder}.\\, {body}",
+    application=lambda function, argument: f"{function}\\, {argument}",
+    parenthesise=lambda inner: f"({inner})",
+)
+
+TEXT_STYLE: Style = Style(
+    constant=lambda name: name,
+    binder=lambda name: name,
+    abstraction=lambda binder, body: f"\\{binder}. {body}",
+    application=lambda function, argument: f"{function} {argument}",
+    parenthesise=lambda inner: f"({inner})",
+)
+
+
+class _NamedBinder(Builder):
+    """A stand-in for a bound variable while rendering: never built, only printed by its source name."""
+
+    __slots__ = ("source_name",)
+
+    def __init__(self, source_name: str) -> None:
+        super().__init__()
+        self.source_name = source_name
+
+    def _build_at(self, depth: int):  # pragma: no cover - a rendering placeholder is never built
+        raise AssertionError("a _NamedBinder is a rendering placeholder and must never be built")
+
+
+def _binder_source_name(builder: _LamBuilder) -> str:
+    """A lambda's bound-variable source name: its ``_binder_hint`` if set, else the Python parameter name."""
+    hint = builder._binder_hint
+    if hint is not None:
+        return hint
+    parameters = tuple(inspect.signature(builder._body).parameters)
+    single_name, = parameters
+    return single_name
+
+
+def _fresh(name: str, scope: "tuple[str, ...]") -> str:
+    """Disambiguate a binder name against those already in scope by priming, so two nested binders that
+    share a source name stay distinguishable."""
+    candidate = name
+    while candidate in scope:
+        candidate = f"{candidate}'"
+    return candidate
+
+
+def render(builder: Builder, names: "dict[int, str]", style: Style) -> str:
+    """The rendering of ``builder``, expanding it one level (its own name, if any, is not substituted) and
+    rendering every nested named constant in ``names`` by its name."""
+    return _render(builder, names, style, is_root=True, scope=())
+
+
+def _render(
+    builder: Builder, names: "dict[int, str]", style: Style, *, is_root: bool, scope: "tuple[str, ...]"
+) -> str:
+    if not is_root and id(builder) in names:
+        return style.constant(names[id(builder)])
+    if isinstance(builder, _NamedBinder):
+        return style.binder(builder.source_name)
+    if isinstance(builder, _LamBuilder):
+        name = _fresh(_binder_source_name(builder), scope)
+        body = builder._body(_NamedBinder(name))
+        rendered_body = _render(body, names, style, is_root=False, scope=(*scope, name))
+        return style.abstraction(style.binder(name), rendered_body)
+    if isinstance(builder, _AppBuilder):
+        function = _render_function(builder._function, names, style, scope)
+        argument = _render_argument(builder._argument, names, style, scope)
+        return style.application(function, argument)
+    if isinstance(builder, _VarBuilder):  # pragma: no cover - rendered terms introduce vars via lambdas
+        raise AssertionError("a free _VarBuilder reached the renderer; rendered terms must be closed")
+    raise TypeError(f"cannot render {builder!r}")
+
+
+def _is_atom(builder: Builder, names: "dict[int, str]") -> bool:
+    """An atom needs no parentheses in argument position: a bound variable or a named constant."""
+    return isinstance(builder, (_NamedBinder, _VarBuilder)) or id(builder) in names
+
+
+def _render_function(
+    builder: Builder, names: "dict[int, str]", style: Style, scope: "tuple[str, ...]"
+) -> str:
+    # A lambda shown expanded must be parenthesised in function position; a name or an application is bare.
+    inner = _render(builder, names, style, is_root=False, scope=scope)
+    if isinstance(builder, _LamBuilder) and id(builder) not in names:
+        return style.parenthesise(inner)
+    return inner
+
+
+def _render_argument(
+    builder: Builder, names: "dict[int, str]", style: Style, scope: "tuple[str, ...]"
+) -> str:
+    inner = _render(builder, names, style, is_root=False, scope=scope)
+    return inner if _is_atom(builder, names) else style.parenthesise(inner)

co_lambda/_latex.py

@@ -0,0 +1,58 @@
+"""Render a source lambda term to LaTeX with readable bound-variable names.
+
+A binder is named by its de Bruijn level (its depth at introduction): the binder introduced at depth
+``d`` is level ``d``, and a ``Var(i)`` seen at depth ``d`` refers to level ``d - 1 - i``. Each binder
+thus has a distinct level, hence a distinct readable name (``x``, ``y``, ``z``, ...), so the rendering
+is unambiguous and reads naturally. The compiler names the same binder ``v{level}`` in the emitted
+Python, so the lambda's name at level ``k`` corresponds to the Python parameter ``v{k}``.
+"""
+
+from __future__ import annotations
+
+from co_lambda._ast import App, Lam, Native, Node, Var
+
+# Readable bound-variable names indexed by de Bruijn level; deeper levels fall back to a subscript.
+_READABLE_NAMES = (
+    "x", "y", "z", "w", "u", "s", "t", "p", "q", "r",
+    "k", "m", "n", "a", "b", "c", "d", "e", "g", "h",
+)
+
+
+def term_to_latex(node: Node) -> str:
+    """The source term as a LaTeX math string (no surrounding ``$``), with readable names."""
+    return _latex(node, 0)
+
+
+def _name(level: int) -> str:
+    assert level >= 0, "a closed term references only bound variables, so every level is nonnegative"
+    if level < len(_READABLE_NAMES):
+        return _READABLE_NAMES[level]
+    return f"x_{{{level - len(_READABLE_NAMES) + 1}}}"
+
+
+def _latex(node: Node, depth: int) -> str:
+    match node:
+        case Var(index=index):
+            return _name(depth - 1 - index)
+        case Lam(body=body):
+            return f"\\lambda {_name(depth)}.\\, {_latex(body, depth + 1)}"
+        case App(function=function, argument=argument):
+            return f"{_function(function, depth)}\\, {_argument(argument, depth)}"
+        case Native(arity=arity):
+            return f"\\langle\\mathrm{{native}}/{arity}\\rangle"
+        case _:
+            raise TypeError(f"cannot render {node!r}")
+
+
+def _function(node: Node, depth: int) -> str:
+    # A lambda in function position must be parenthesised; an application stays bare (left associative).
+    if isinstance(node, Lam):
+        return f"({_latex(node, depth)})"
+    return _latex(node, depth)
+
+
+def _argument(node: Node, depth: int) -> str:
+    # Only a variable is atomic in argument position; an application or lambda is parenthesised.
+    if isinstance(node, Var):
+        return _latex(node, depth)
+    return f"({_latex(node, depth)})"

co_lambda/_prelude.py

@@ -0,0 +1,163 @@
+"""Pure-lambda prelude: the combinators and Scott data vocabulary, written as literal HOAS.
+
+This module is pure lambda calculus (one of the four strictly separated kinds: codec / sugar /
+runtime / pure-lambda source): every top-level binding is a ``Builder`` lambda term, transcribed
+one-to-one through the ``_dsl`` notation. Encodings of Python data (Church numeral rendering,
+Scott-list building) live in ``_codec``; appliers and other writing sugar live in ``_sugar``; the
+built example ``Node``s and the demo encoders (Datalog, tree DP, game search harnesses) live in
+``_examples``.
+"""
+
+from __future__ import annotations
+
+from co_lambda._dsl import Builder, app, lam
+
+# Combinators.
+IDENTITY: Builder = lam(lambda x: x)
+KESTREL: Builder = lam(lambda x: lam(lambda y: x))  # K = lambda x. lambda y. x
+SELF_APPLY: Builder = lam(lambda x: app(x, x))
+Y: Builder = lam(
+    lambda f: app(
+        lam(lambda x: app(f, app(x, x))),
+        lam(lambda x: app(f, app(x, x))),
+    )
+)
+
+# Church booleans.
+TRUE: Builder = lam(lambda a: lam(lambda b: a))
+FALSE: Builder = lam(lambda a: lam(lambda b: b))
+AND: Builder = lam(lambda p: lam(lambda q: app(app(p, q), FALSE)))  # p and q
+OR: Builder = lam(lambda p: lam(lambda q: app(app(p, TRUE), q)))    # p or q
+
+# Church-numeral literals the prelude's own terms need (the general renderer is ``_codec.church``).
+ZERO: Builder = lam(lambda s: lam(lambda z: z))
+ONE: Builder = lam(lambda s: lam(lambda z: app(s, z)))
+
+# Peano arithmetic on Church numerals.
+SUCC: Builder = lam(lambda n: lam(lambda s: lam(lambda z: app(s, app(app(n, s), z)))))
+PLUS: Builder = lam(
+    lambda m: lam(lambda n: lam(lambda s: lam(lambda z: app(app(m, s), app(app(n, s), z)))))
+)
+MULT: Builder = lam(lambda m: lam(lambda n: lam(lambda s: app(m, app(n, s)))))
+EXP: Builder = lam(lambda m: lam(lambda n: app(n, m)))  # m ^ n = n m
+IS_ZERO: Builder = lam(lambda n: app(app(n, lam(lambda x: FALSE)), TRUE))
+PRED: Builder = lam(
+    lambda n: lam(lambda s: lam(lambda z: app(
+        app(
+            app(n, lam(lambda g: lam(lambda h: app(h, app(g, s))))),
+            lam(lambda u: z),
+        ),
+        lam(lambda u: u),
+    )))
+)
+
+# factorial n = if n = 0 then 1 else n * factorial (n - 1); the Church boolean selects.
+FACTORIAL: Builder = app(
+    Y,
+    lam(lambda f: lam(lambda n: app(
+        app(app(IS_ZERO, n), ONE),
+        app(app(MULT, n), app(f, app(PRED, n))),
+    ))),
+)
+
+# fib n = if n = 0 then 0 else if (n - 1) = 0 then 1 else fib (n-1) + fib (n-2)
+FIBONACCI: Builder = app(
+    Y,
+    lam(lambda f: lam(lambda n: app(
+        app(app(IS_ZERO, n), ZERO),
+        app(
+            app(app(IS_ZERO, app(PRED, n)), ONE),
+            app(
+                app(PLUS, app(f, app(PRED, n))),
+                app(f, app(PRED, app(PRED, n))),
+            ),
+        ),
+    ))),
+)
+
+# Scott-encoded lists, for cyclic data.
+SCOTT_CONS: Builder = lam(
+    lambda h: lam(lambda t: lam(lambda c: lam(lambda n: app(app(c, h), t))))
+)
+SCOTT_NIL: Builder = lam(lambda c: lam(lambda n: n))
+SCOTT_PRESENT: Builder = lam(lambda a: lam(lambda b: a))  # = TRUE / first Scott constructor
+
+# The ordinary singly-linked-list map: nothing is cycle-aware. map f = Y (lambda self.
+# lambda lst. lst (lambda h. lambda t. cons (f h) (self t)) nil). The recursion is guarded
+# (a cons is exposed before the recursive call), so on a cyclic list the recursive
+# application self t re-enters the same closed position and the least fixpoint folds it into
+# a finite cyclic result, where head reduction would unfold the mapped stream forever.
+MAP: Builder = lam(
+    lambda f: app(
+        Y,
+        lam(lambda self_recursion: lam(lambda source: app(
+            app(
+                source,
+                lam(lambda head: lam(lambda tail: app(
+                    app(SCOTT_CONS, app(f, head)),
+                    app(self_recursion, tail),
+                ))),
+            ),
+            SCOTT_NIL,
+        ))),
+    )
+)
+
+# =====================================================================
+# Dynamic programming with a tree state space: memoisation for free.
+#
+# A binary tree is Scott-encoded with two constructors, node(l, r) and leaf(v); a tree DP is an
+# ordinary Y-recursion whose subproblems are the subtrees. Interning makes structurally-identical
+# subtrees one node, so a DP over a DAG-compressed tree computes each distinct subtree once.
+# =====================================================================
+
+TREE_NODE: Builder = lam(
+    lambda l: lam(lambda r: lam(lambda on_node: lam(lambda on_leaf: app(app(on_node, l), r))))
+)
+TREE_LEAF: Builder = lam(lambda v: lam(lambda on_node: lam(lambda on_leaf: app(on_leaf, v))))
+
+# tree_any t = OR over the leaves of t of the leaf's boolean. As a tree DP:
+#   tree_any = Y (lambda self. lambda t. t (lambda l. lambda r. OR (self l) (self r)) (lambda v. v))
+TREE_ANY: Builder = app(
+    Y,
+    lam(lambda self_recursion: lam(lambda tree: app(
+        app(
+            tree,
+            lam(lambda left: lam(lambda right: app(
+                app(OR, app(self_recursion, left)), app(self_recursion, right)
+            ))),
+        ),
+        lam(lambda value: value),
+    ))),
+)
+
+# =====================================================================
+# Minimax / AND-OR game search with a transposition table for free.
+#
+# A game position is a MAX node (OR over moves), a MIN node (AND over moves), or a terminal LEAF
+# carrying a Boolean outcome. A transposition is the same interned node, so its value is computed
+# once: interning is the transposition table.
+# =====================================================================
+
+MAX_NODE: Builder = lam(lambda l: lam(lambda r: lam(
+    lambda on_max: lam(lambda on_min: lam(lambda on_leaf: app(app(on_max, l), r))))))
+MIN_NODE: Builder = lam(lambda l: lam(lambda r: lam(
+    lambda on_max: lam(lambda on_min: lam(lambda on_leaf: app(app(on_min, l), r))))))
+GAME_LEAF: Builder = lam(lambda v: lam(
+    lambda on_max: lam(lambda on_min: lam(lambda on_leaf: app(on_leaf, v)))))
+
+# minimax = Y (lambda self. lambda pos. pos (max: OR (self l) (self r)) (min: AND (self l) (self r))
+#                                            (leaf: lambda v. v))
+MINIMAX: Builder = app(
+    Y,
+    lam(lambda self_recursion: lam(lambda position: app(app(app(
+        position,
+        lam(lambda left: lam(lambda right: app(
+            app(OR, app(self_recursion, left)), app(self_recursion, right)))),       # MAX: OR
+        ),
+        lam(lambda left: lam(lambda right: app(
+            app(AND, app(self_recursion, left)), app(self_recursion, right)))),       # MIN: AND
+        ),
+        lam(lambda value: value),                                                     # LEAF
+    ))),
+)