#!/usr/bin/env python3 """Compile every example, run it, and hold its output to a recorded answer key. This is the spine of the library. A lesson page never hand-types what a program prints; it marks the spot and this tool fills it from a real run: Inside the markers is generated, outside is yours. Three modes ----------- python3 tools/run_examples.py verify + refill the .md blocks python3 tools/run_examples.py --update accept current output as the key python3 tools/run_examples.py --check write nothing; fail on any drift (CI) python3 tools/run_examples.py --only X touch example X and nothing else --only X,Y or --only X --only Y for several ``--only`` exists because this checkout is sometimes open in two sessions at once. A full ``--update`` re-records *every* answer key and refills *every* page, so recording your own key adopts whatever a colleague's half-finished example happens to print. ``--only`` narrows both halves to the stems you name. It is never right in CI: a partial run cannot see repo-wide drift, which is the whole job there. An example is any ``*.rs`` under a folder named ``examples/``. Its answer key is the sibling ``.out``. Stems must be unique repo-wide, because a Markdown block names a bare stem with no path — the same rule the star-voting-library uses for its generated case pages. Stdlib only, on purpose: the docs build already needs Python, and a teaching repo should not make you install a toolchain to read it. """ from __future__ import annotations import argparse import os import re import subprocess import sys import tempfile from pathlib import Path REPO = Path(__file__).resolve().parent.parent EDITION = "2024" # ...generated... # ...generated... # # Two kinds, one mechanism. `output` pastes what the program printed; `source` # pastes the program itself. The second exists for kata solutions: a solution # hand-copied into a fence is a solution that can quietly stop compiling, which # is the one thing a practice page must never do. BLOCK = re.compile( r"(?P)" r"(?P.*?)" r"(?P)", re.DOTALL, ) SKIP_DIRS = {".git", "site", ".venv", "target", "__pycache__", ".github"} # A fenced code block, opened or closed. Needed because the pages that DOCUMENT # this mechanism (README.md, CONTRIBUTING.md) show the markers as examples inside # a fence — those must be left alone, not treated as blocks to fill. FENCE = re.compile(r"^[ \t]*(?P`{3,}|~{3,})", re.MULTILINE) def fenced_spans(text: str) -> list[tuple[int, int]]: """Character ranges covered by fenced code blocks.""" spans: list[tuple[int, int]] = [] open_at: int | None = None open_fence = "" for m in FENCE.finditer(text): fence = m.group("f") if open_at is None: open_at, open_fence = m.start(), fence elif fence[0] == open_fence[0] and len(fence) >= len(open_fence): spans.append((open_at, m.end())) open_at = None if open_at is not None: spans.append((open_at, len(text))) return spans def walk(root: Path): for dirpath, dirnames, filenames in os.walk(root): dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS] for name in filenames: yield Path(dirpath) / name def find_examples() -> dict[str, Path]: """Map stem -> path for every .rs under an examples/ folder. Stems are unique.""" found: dict[str, Path] = {} for path in sorted(walk(REPO)): if path.suffix != ".rs" or path.parent.name != "examples": continue stem = path.stem if stem in found: sys.exit( f"ERROR: duplicate example stem {stem!r}\n" f" {found[stem].relative_to(REPO)}\n {path.relative_to(REPO)}\n" "Stems are named bare in Markdown blocks, so they must be unique." ) found[stem] = path return found def run_example(src: Path, workdir: Path) -> str: """Compile and run one example; return its stdout. Exits on failure.""" binary = workdir / src.stem build = subprocess.run( ["rustc", "--edition", EDITION, str(src), "-o", str(binary)], capture_output=True, text=True, ) if build.returncode != 0: sys.exit(f"ERROR: {src.relative_to(REPO)} failed to compile\n{build.stderr}") if build.stderr.strip(): print(f" note: {src.relative_to(REPO)} compiled with warnings:\n{build.stderr}") run = subprocess.run([str(binary)], capture_output=True, text=True, timeout=60) if run.returncode != 0: sys.exit( f"ERROR: {src.relative_to(REPO)} exited {run.returncode}\n{run.stderr}" ) return run.stdout def rendered_block(kind: str, src: Path, output: str, page: Path) -> str: """The generated body that goes between the markers on `page`.""" href = os.path.relpath(src, page.parent) if kind == "source": body = src.read_text(encoding="utf-8").strip("\n") return ( f"\n*[`{src.name}`]({href}) in full — pasted here by " f"`tools/run_examples.py` from the file CI compiles and runs.*\n\n" f"```rust\n{body}\n```\n" ) body = output.strip("\n") return ( f"\n*Verified output of [`{src.name}`]({href}) — regenerated by " f"`tools/run_examples.py`, never hand-typed.*\n\n" f"```text\n{body}\n```\n" ) def fill_pages( outputs: dict[str, str], sources: dict[str, Path], write: bool, problems: list[str], only: set[str] | None = None, ) -> list[str]: """Refill every output block on every Markdown page. Returns drift descriptions. A block naming a stem that no longer exists is recorded in `problems` and left untouched, rather than exiting on the spot. It is still a failure — but dying on the first one would leave every *other* page unfilled, which matters when a page mid-rename is sitting in the working tree beside work that is ready. With `only` set, a block naming any other stem is left exactly as it is, and is reported as neither drift nor a problem. That holds for `source:` blocks as well as `output:` ones — the selection is checked before the kind is, so a run scoped to one stem cannot rewrite either half of somebody else's page. That is the point of `--only`: the blocks it does not fill belong to an example it did not run, and rewriting one from a key this run never verified is how a colleague's page gets edited by somebody who was working two folders away. """ drift: list[str] = [] for page in sorted(walk(REPO)): if page.suffix != ".md": continue text = page.read_text(encoding="utf-8") if "