texmodel 0.2.0__py3-none-any.whl

texmodel/testing.py

@@ -0,0 +1,297 @@
+"""Unit tests of generated code with stubbed dependencies (§21a 20).
+
+Two tiers. The fast tier needs no TeX: `expand(node, stubs=[Fact])` walks the bodies the generator wrote, with the
+node's field values, and returns the text and the `Call` of every stubbed component, in order. The TeX tier is
+`Package.test_document(node, stub=[Fact])`: the real packages, each stub replaced by a macro that writes
+`texmodel:probe:callN=<call>` to the log, which `texmodel_build.testkit.run_probes` reads back as `Call`s. Both give the
+same `Call`s for the same node, so a test asserts what a component passes on, not a PDF. Layout is not covered.
+
+```python
+calls = [c for c in expand(card, stubs=[Fact]) if isinstance(c, Call)]
+assert calls == [Call("bkFact", ("First",)), Call("bkFact", ("R\\&D 50\\%",))]
+```
+
+A call's arguments are the TeX the stub received, as `\\detokenize` shows it: a space follows each control word and
+runs of spaces are one, so both tiers agree byte for byte.
+"""
+
+import dataclasses
+import re
+import typing
+from collections.abc import Mapping, Sequence
+
+from ._internal.render import Arg, argument_text, signature, tex_arguments
+from .body import HOLE, Comment, Cs, Group, Hole, Library, Lit, Ref, RefKind, Seq, TexRaw
+from .components import Command, Environment, Node, Passthrough, Resolved, control_name
+from .errors import DeclarationError, Violation
+from .types import Raw, escape
+
+type Component = type[Command] | type[Environment]
+
+if typing.TYPE_CHECKING:
+    from .package import Package
+
+_CONTROL_WORD = re.compile(r"\\[A-Za-z]+")
+_COUNTER = r"\tmstubcalls"
+_HEADS = {RefKind.CALL: "", RefKind.OPEN: "begin:", RefKind.CLOSE: "end:"}
+
+
+def _groups(text: str) -> list[str]:
+    """The top-level `{...}` groups of `text`; a backslash escapes the next character."""
+    out: list[str] = []
+    depth, start, i = 0, 0, 0
+    while i < len(text):
+        c = text[i]
+        if c == "\\":
+            i += 1
+        elif c == "{":
+            depth += 1
+            start = i + 1 if depth == 1 else start
+        elif c == "}":
+            depth -= 1
+            if depth == 0:
+                out.append(text[start:i])
+        i += 1
+    return out
+
+
+@dataclasses.dataclass(frozen=True)
+class Call:
+    """A stubbed component called: its control sequence name (`cdFact`, no backslash), its arguments in TeX order (the
+    optional one first, empty when left out) as `\\detokenize` shows them, and whether it is a command call or the
+    start or end of an environment."""
+
+    name: str
+    args: tuple[str, ...] = ()
+    kind: RefKind = RefKind.CALL
+
+    def probe_value(self) -> str:
+        """What the TeX stub writes after `texmodel:probe:callN=`: `cdFact{a}{b}`, `begin:cdBox{a}`, `end:cdBox`."""
+        return _HEADS[self.kind] + self.name + "".join(f"{{{a}}}" for a in self.args)
+
+    @classmethod
+    def parse(cls, value: str) -> "Call":
+        """The `Call` a probe value stands for; braces inside an argument are balanced or backslash-escaped."""
+        kind = next((k for k, head in _HEADS.items() if head and value.startswith(head)), RefKind.CALL)
+        name, brace, rest = value.removeprefix(_HEADS[kind]).partition("{")
+        return cls(name, tuple(_groups(brace + rest)), kind)
+
+
+def detokenized(tex: str) -> str:
+    """`tex` as `\\detokenize` shows a macro argument: leading spaces gone, a run of spaces one, and a space after
+    each control word (which also swallows the spaces that followed it)."""
+    out: list[str] = []
+    i, text = 0, tex.lstrip()
+    while i < len(text):
+        word = _CONTROL_WORD.match(text, i)
+        if word:
+            out.append(word[0] + " ")
+            i = word.end()
+        elif text[i] == "\\":
+            out.append(text[i : i + 2])
+            i += 2
+        else:
+            out.append(" " if text[i].isspace() else text[i])
+            i += 1
+        if out[-1].endswith(" "):  # after a control word or a space: further spaces are skipped
+            while i < len(text) and text[i].isspace():
+                i += 1
+    return "".join(out)
+
+
+def _args(cls: type) -> tuple[Arg, ...]:
+    return typing.cast("tuple[Arg, ...]", getattr(cls, "__tm_args__"))  # noqa: B009
+
+
+def _control(cls: type) -> str:
+    """The control sequence name of a registered component, or a refusal to stub what no package registered."""
+    if not hasattr(cls, "__tm_cs__"):
+        raise DeclarationError(
+            f"{cls.__name__}: not registered with a package, so it cannot be stubbed",
+            code="TM-M019",
+            path=cls.__name__,
+            hint="stub a class decorated with its package's command / environment",
+        )
+    return control_name(cls)
+
+
+def _call(cls: type, values: Mapping[str, str], kind: RefKind) -> Call:
+    shown = () if kind is RefKind.CLOSE else tuple(detokenized(values[a.name]) for a in tex_arguments(_args(cls)))
+    return Call(_control(cls), shown, kind)
+
+
+class _Out:
+    """The result under construction: text accumulates until a call splits it."""
+
+    def __init__(self) -> None:
+        self.items: list[Call | str] = []
+        self.text = ""
+
+    def write(self, text: str) -> None:
+        self.text += text
+
+    def call(self, call: Call) -> None:
+        self.flush()
+        self.items.append(call)
+
+    def flush(self) -> None:
+        if self.text:
+            self.items.append(self.text)
+            self.text = ""
+
+
+def _inline(piece: object, values: Mapping[str, str], stubs: frozenset[type], out: _Out) -> None:
+    if isinstance(piece, Ref):
+        _ref(piece, values, stubs, out)
+    elif isinstance(piece, Lit):
+        out.write(escape(piece.text))
+    elif isinstance(piece, Raw):
+        out.write(piece.tex)
+    elif isinstance(piece, Hole):
+        out.write(values[piece.name])
+    elif isinstance(piece, Cs):
+        out.write(f"\\{piece.name}")
+    elif isinstance(piece, Group | Seq):
+        braces = isinstance(piece, Group)
+        out.write("{" if braces else "")
+        for inner in typing.cast("tuple[object, ...]", piece.pieces):
+            _inline(inner, values, stubs, out)
+        out.write("}" if braces else "")
+
+
+def _pieces(pieces: Sequence[Resolved], values: Mapping[str, str], stubs: frozenset[type], out: _Out) -> None:
+    """One line per piece, as `join` writes them; a comment is no text."""
+    for piece in pieces:
+        if isinstance(piece, Comment):
+            continue
+        if isinstance(piece, TexRaw):
+            out.write(HOLE.sub(lambda m: "#" if m[0] == "##" else values[m["name"]], piece.body))
+        else:
+            _inline(piece, values, stubs, out)
+        out.write("\n")
+
+
+def _body(cls: type, which: int | None, values: Mapping[str, str], stubs: frozenset[type], out: _Out) -> None:
+    """The body of a registered component (`which` 0 or 1 for an environment's begin and end); an adopted component
+    has none, so it adds nothing."""
+    source = getattr(cls, "__tm_inline__")  # noqa: B009
+    found = source if which is None else source[which]
+    if found is not None:
+        _pieces(found[0], values, stubs, out)
+
+
+def _ref(ref: Ref, values: Mapping[str, str], stubs: frozenset[type], out: _Out) -> None:
+    mine = {
+        a.name: "" if v is None else values[v.name] if isinstance(v, Hole) else argument_text(a, v)
+        for a, v in zip(_args(ref.target), ref.values, strict=True)
+    }
+    if ref.target in stubs:
+        out.call(_call(ref.target, mine, ref.kind))
+    else:
+        _body(ref.target, None if ref.kind is RefKind.CALL else int(ref.kind is RefKind.CLOSE), mine, stubs, out)
+
+
+def _walk(node: Node, stubs: frozenset[type], out: _Out) -> None:
+    if isinstance(node, Comment):
+        return
+    if isinstance(node, Passthrough):
+        out.write(node.tex.tex + "\n")
+        return
+    cls = type(node)
+    values = {
+        a.name: "" if getattr(node, a.name) is None else argument_text(a, getattr(node, a.name)) for a in _args(cls)
+    }
+    if isinstance(node, Command):
+        if cls in stubs:
+            out.call(_call(cls, values, RefKind.CALL))
+        else:
+            _body(cls, None, values, stubs, out)
+        return
+    stubbed = cls in stubs
+    out.call(_call(cls, values, RefKind.OPEN)) if stubbed else _body(cls, 0, values, stubs, out)
+    for child in node.content:
+        _walk(child, stubs, out)
+    out.call(_call(cls, values, RefKind.CLOSE)) if stubbed else _body(cls, 1, values, stubs, out)
+
+
+def expand(node: Node, stubs: Sequence[Component] = ()) -> list[Call | str]:
+    """What `node` makes TeX do, without TeX: its body text and the `Call` of every stubbed component, in order.
+
+    A non-stubbed component is walked into through its body, with the arguments it was called with; a stubbed one
+    (a class registered with a package) becomes a `Call` and its body is not read. Children of an environment are
+    walked in order. Deterministic and pure."""
+    for cls in stubs:
+        _control(cls)  # refuses a class no package registered
+    out = _Out()
+    _walk(node, frozenset(stubs), out)
+    out.flush()
+    return out.items
+
+
+def _probe(head: str, tail: str) -> str:
+    return rf"\global\advance{_COUNTER} by 1 \typeout{{texmodel:probe:call\the{_COUNTER}={head}{tail}}}"
+
+
+def stub_tex(stubs: Sequence[Component]) -> str:
+    """The TeX that replaces each stub by a macro writing `texmodel:probe:callN=<Call.probe_value()>`, N counting every
+    call in the document, so the log keeps their order. Meant for `PreambleSlots.after_package`."""
+    lines = [rf"\newcount{_COUNTER}", r"\AtEndDocument{\null}"]  # the document needs a page to be compiled
+    for cls in stubs:
+        name, args = _control(cls), _args(cls)
+        shown = "".join(f"{{#{i}}}" for i in range(1, len(args) + 1))
+        arg_part = rf"\detokenize{{{shown}}}" if shown else ""
+        if issubclass(cls, Environment):
+            lines.append(rf"\providecommand{{\{name}}}{{}}\providecommand{{\end{name}}}{{}}")
+            lines.append(
+                rf"\renewenvironment{{{name}}}{signature(args)}{{{_probe(f'begin:{name}', arg_part)}}}"
+                rf"{{{_probe(f'end:{name}', '')}}}"
+            )
+        else:
+            lines.append(rf"\providecommand{{\{name}}}{{}}")
+            lines.append(rf"\renewcommand{{\{name}}}{signature(args)}{{{_probe(name, arg_part)}}}")
+    return "\n".join(lines)
+
+
+def _defined(package: "Package") -> list[tuple[Component, Library]]:
+    """The registered components a library block defines, with the block."""
+    return [
+        (c, c.defined_by) for c in typing.cast("tuple[Component, ...]", package.registered) if c.defined_by is not None
+    ]
+
+
+_EXPORT = (
+    r"\newcommand\tmexport[1]{\ifcsname #1\endcsname\typeout{texmodel:probe:def.#1=yes}"
+    r"\edef\tmexportmeaning{\expandafter\meaning\csname #1\endcsname}"
+    r'\directlua{local m=[==[\tmexportmeaning]==]; local _,e=m:find("macro:",1,true); local n="?"; '
+    r'if e then local t=m:find("->",e,true); local _,k=m:sub(e+1,t-1):gsub(string.char(35),""); n=k end; '
+    r'texio.write_nl("texmodel:probe:arity.#1="..n)}'
+    r"\else\typeout{texmodel:probe:def.#1=no}\fi}"
+)
+
+
+def export_probes(package: "Package") -> str:
+    """TeX for `PreambleSlots.after_package` that writes, per component a library block defines,
+    `texmodel:probe:def.<cs>` (`yes` or `no`) and `texmodel:probe:arity.<cs>` (the `#` parameters of its
+    `\\meaning`, `?` when that is not a macro's), for `check_exports` (§21a 12). Needs LuaTeX."""
+    calls = [rf"\tmexport{{{control_name(c)}}}" for c, _ in _defined(package)]
+    return "\n".join([_EXPORT, *calls]) if calls else ""
+
+
+def check_exports(package: "Package", probes: Mapping[str, str]) -> list[Violation]:
+    """The components a library block defines against what the compile found (`TM-C010` not defined, `TM-C011` another
+    number of arguments: an optional first one counts, and `?` checks existence only). `probes` are the `name=value`
+    pairs of the `texmodel:probe:` lines."""
+    out: list[Violation] = []
+    for cls, lib in _defined(package):
+        control, want = control_name(cls), str(len(cls.__tm_args__))
+        got = probes.get(f"arity.{control}", "?")
+        if probes.get(f"def.{control}") != "yes":
+            message = f"\\{control} is declared as defined by library {lib.name}, but the compile does not define it"
+            out.append(Violation("TM-C010", cls.__name__, message))
+        elif got not in ("?", want):
+            message = f"\\{control}: declared {want} argument(s), the compile defines {got}"
+            out.append(Violation("TM-C011", cls.__name__, message, hint="change the declaration or the block"))
+    return out
+
+
+__all__ = ["Call", "check_exports", "detokenized", "expand", "export_probes", "stub_tex"]

texmodel/types.py

@@ -0,0 +1,264 @@
+"""Field types (T1): the closed vocabulary a component field may use.
+
+`Text` is plain `str` to a type checker, so `Fact("A soft woof.")` type-checks, and a marker at runtime, so the renderer
+and (later) the escaper know the field holds untrusted text that must be escaped on render (T3).
+"""
+
+import dataclasses
+import enum
+import math
+import re
+from decimal import Decimal
+from fractions import Fraction
+from typing import TYPE_CHECKING, Annotated, ClassVar, Final
+
+from .errors import DeclarationError, ValidationError
+
+if TYPE_CHECKING:
+    from pydantic_core import CoreSchema
+
+
+class _TextMarker:
+    def __repr__(self) -> str:
+        return "Text"
+
+
+TEXT: Final = _TextMarker()
+Text = Annotated[str, TEXT]
+
+
+class _PdfMarker:
+    def __repr__(self) -> str:
+        return "PdfString"
+
+
+PDF: Final = _PdfMarker()
+PdfString = Annotated[str, PDF]  # text for the inside of a PDF literal string, see `pdf_escape`
+
+_ESCAPES = str.maketrans(
+    {
+        "\\": r"\textbackslash{}",
+        "&": r"\&",
+        "%": r"\%",
+        "$": r"\$",
+        "#": r"\#",
+        "_": r"\_",
+        "{": r"\{",
+        "}": r"\}",
+        "~": r"\textasciitilde{}",
+        "^": r"\textasciicircum{}",
+    }
+)
+
+
+def escape(text: str) -> str:
+    """`Text` on render (T3): every TeX special becomes its literal; one pass, so output is never re-escaped."""
+    return text.translate(_ESCAPES)
+
+
+_PDF_SAFE = re.compile(r"[\\(){}%#&$_^~\x00-\x1f\x7f]")
+
+
+def pdf_escape(text: str) -> str:
+    """`PdfString` on render (§21a 9): the body of a PDF literal string that cannot end early and that a reader decodes
+    to `text`.
+
+    A character that opens or ends a string (`\\ ( )`), that TeX reads as markup (`% # & $ _ ^ ~ { }`) or that is a
+    control character becomes a three-digit octal escape (`\\050`); so does a space after a space, since TeX reads a
+    run of spaces as one. Text with a non-ASCII character is written as UTF-16BE with a byte order mark, every byte an
+    octal escape: a PDF text string is PDFDocEncoding or UTF-16BE, never UTF-8. A lone surrogate raises
+    `UnicodeEncodeError`. The result is emitted inside `\\detokenize{}`."""
+    if not text.isascii():
+        return "".join(f"\\{b:03o}" for b in ("\ufeff" + text).encode("utf-16-be"))
+    out = _PDF_SAFE.sub(lambda m: f"\\{ord(m[0]):03o}", text)
+    return re.sub(r"(?<= ) ", r"\\040", out)
+
+
+def balanced(tex: str) -> bool:
+    """Braces balance, ignoring escaped ones and comments: unbalanced TeX would swallow what follows it."""
+    depth = 0
+    i = 0
+    while i < len(tex):
+        c = tex[i]
+        if c == "\\":
+            i += 1  # the escaped character is not a brace
+        elif c == "%":
+            while i < len(tex) and tex[i] != "\n":
+                i += 1
+        elif c == "{":
+            depth += 1
+        elif c == "}":
+            depth -= 1
+            if depth < 0:
+                return False
+        i += 1
+    return depth == 0
+
+
+@dataclasses.dataclass(frozen=True)
+class Raw:
+    """TeX passed through unescaped, only where a field is declared `Raw` (T3). A distinct class, never a `str`."""
+
+    tex: str
+
+    def __post_init__(self) -> None:
+        if not balanced(self.tex):
+            raise ValidationError("Raw: unbalanced braces", code="TM-C007", hint="close every { and } in the TeX")
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source: object, handler: object) -> CoreSchema:
+        """Data gives `Raw` as a string (S, D2); a `Raw` passes as it is; unbalanced braces are a data error."""
+        from pydantic_core import core_schema as cs
+
+        def make(value: object) -> Raw:
+            if isinstance(value, Raw):
+                return value
+            if not isinstance(value, str):
+                raise ValueError("expected TeX as a string")  # noqa: TRY004  # pydantic reports ValueError, not TypeError
+            try:
+                return Raw(value)
+            except ValidationError as exc:
+                raise ValueError(str(exc)) from exc
+
+        return cs.json_or_python_schema(
+            json_schema=cs.chain_schema([cs.str_schema(), cs.no_info_plain_validator_function(make)]),
+            python_schema=cs.no_info_plain_validator_function(make),
+            serialization=cs.plain_serializer_function_ser_schema(lambda raw: raw.tex),
+        )
+
+
+class Choice(enum.Enum):
+    """A closed set a field takes (T1): subclass it, decorate the subclass with `@enum.unique`, and give each member the
+    TeX it stands for, a `Raw` (passes through) or a `str` (escaped as text). Data names a member by its name."""
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}.{self.name}"
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source: object, handler: object) -> CoreSchema:
+        from pydantic_core import core_schema as cs
+
+        names = list(cls.__members__)
+
+        def make(value: object) -> Choice:
+            if isinstance(value, cls):
+                return value
+            if isinstance(value, str) and value in names:
+                return cls[value]
+            raise ValueError(f"expected one of {names}")
+
+        return cs.json_or_python_schema(
+            json_schema=cs.chain_schema([cs.literal_schema(names), cs.no_info_plain_validator_function(make)]),
+            python_schema=cs.no_info_plain_validator_function(make),
+            serialization=cs.plain_serializer_function_ser_schema(lambda member: member.name),
+        )
+
+
+# --- Values (T2, T4, T5): what a `Value[T]` holds. Immutable, validated on construction, stable to format. ---
+
+_NUMBER = r"[+-]?(?:\d+(?:\.\d*)?|\.\d+)"
+_LENGTH = re.compile(rf"(?P<n>{_NUMBER})(?P<u>[a-z]+)")
+_INCHES_PER = {  # None: relative to the font, no fixed size
+    "in": Fraction(1),
+    "mm": Fraction(10, 254),
+    "cm": Fraction(100, 254),
+    "pt": Fraction(100, 7227),  # TeX points: 72.27 to the inch
+    "bp": Fraction(1, 72),  # big (PostScript) points: 72 to the inch
+    "pc": Fraction(1200, 7227),
+    "em": None,
+    "ex": None,
+}
+
+
+def _plain(d: Decimal) -> str:
+    """No exponent, no trailing zeros, no `-0`: `2.0` -> `2`, `1e-05` -> `0.00001`."""
+    s = format(d, "f")
+    if "." in s:
+        s = s.rstrip("0").rstrip(".")
+    return "0" if s in ("-0", "") else s
+
+
+def _decimal(x: float) -> Decimal:
+    return Decimal(repr(float(x)))
+
+
+@dataclasses.dataclass(frozen=True, init=False)
+class Length:
+    """A TeX dimension: `Length("2mm")`, `Length(1.5, "pt")`. Units are kept as written, never converted."""
+
+    value: Decimal
+    unit: str
+
+    def __init__(self, value: str | float, unit: str | None = None) -> None:
+        hint = 'write a number and a unit (mm cm in pt bp pc em ex), e.g. Length("2mm")'
+        if unit is None:
+            m = _LENGTH.fullmatch(value) if isinstance(value, str) else None
+            if not m:
+                raise DeclarationError(f"Length({value!r}): not a number with a unit", code="TM-M016", hint=hint)
+            value, unit = m["n"], m["u"]
+        if unit not in _INCHES_PER:
+            raise DeclarationError(f"Length: unknown unit {unit!r}", code="TM-M016", hint=hint)
+        if isinstance(value, str):
+            if not re.fullmatch(_NUMBER, value):
+                raise DeclarationError(f"Length({value!r}): not a number", code="TM-M016", hint=hint)
+            number = Decimal(value)
+        elif math.isfinite(value):
+            number = _decimal(value)
+        else:
+            raise DeclarationError(f"Length({value!r}): not finite", code="TM-M016", hint=hint)
+        object.__setattr__(self, "value", number)
+        object.__setattr__(self, "unit", unit)
+
+    def __str__(self) -> str:
+        return f"{_plain(self.value)}{self.unit}"
+
+    @property
+    def inches(self) -> Fraction:
+        """Exact size in inches (T4); `em` and `ex` depend on the font and have none."""
+        per = _INCHES_PER[self.unit]
+        if per is None:
+            raise DeclarationError(f"{self}: {self.unit} is relative to the font", code="TM-M016")
+        return Fraction(self.value) * per
+
+
+class _Colour:
+    """Components in [0, 1], refused outside it; `str()` is what `\\definecolor` takes."""
+
+    model: ClassVar[str]
+
+    def __post_init__(self) -> None:
+        for name, v in vars(self).items():
+            if not 0 <= v <= 1:  # also false for nan
+                raise DeclarationError(
+                    f"{type(self).__name__}.{name}={v!r}: components are in [0, 1]", code="TM-M017", path=name
+                )
+
+    def __str__(self) -> str:
+        return ",".join(_plain(_decimal(v)) for v in vars(self).values())
+
+
+@dataclasses.dataclass(frozen=True)
+class CMYK(_Colour):
+    c: float
+    m: float
+    y: float
+    k: float
+    model: ClassVar[str] = "cmyk"
+
+
+@dataclasses.dataclass(frozen=True)
+class RGB(_Colour):
+    r: float
+    g: float
+    b: float
+    model: ClassVar[str] = "rgb"
+
+
+@dataclasses.dataclass(frozen=True)
+class Gray(_Colour):
+    g: float
+    model: ClassVar[str] = "gray"
+
+
+Colour = CMYK | RGB | Gray
+"""One colour model each; there is no conversion between them (T5)."""