@cplieger/deadset-ts 3.9.1 → 3.11.0

package/dist/src/reporters/template.js

@@ -0,0 +1,877 @@
+/**
+ * A user's template in a subset of Go's `text/template` action grammar, over the report
+ * document by its JSON member names. Text, comments, trim markers, pipelines, variables,
+ * `if`, `else if`, `with`, and `range` with `break` and `continue` are implemented; so are
+ * `and`, `or`, `not`, `len`, `index`, `eq`, `ne`, `lt`, `le`, `gt`, `ge`, `print`, `printf`
+ * and `println`. Any other function, `define`, `template` and `block` are refused at parse,
+ * and a member the document does not carry fails the rendering.
+ */
+import { RenderError } from "./reporter.js";
+import { utf8Bytes } from "./sha256.js";
+/** A template that does not parse, which refuses the invocation before any analysis. */
+export class TemplateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TemplateError";
+    }
+}
+const LEFT = "{{";
+const RIGHT = "}}";
+const TRIM_SPACE = new Set([" ", "\t", "\r", "\n"]);
+const FUNCTIONS = new Set([
+    "and",
+    "or",
+    "not",
+    "len",
+    "index",
+    "eq",
+    "ne",
+    "lt",
+    "le",
+    "gt",
+    "ge",
+    "print",
+    "printf",
+    "println",
+]);
+const REFUSED_KEYWORDS = new Set(["define", "template", "block"]);
+const ESCAPES = {
+    a: "\u0007",
+    b: "\b",
+    f: "\f",
+    n: "\n",
+    r: "\r",
+    t: "\t",
+    v: "\v",
+    "\\": "\\",
+    '"': '"',
+};
+/** The number of hexadecimal digits each numeric escape takes. */
+const ESCAPE_WIDTHS = { x: 2, u: 4, U: 8 };
+const IDENTIFIER = /[A-Za-z_][A-Za-z0-9_]*/uy;
+const NUMBER = /[+-]?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/uy;
+function lineOf(source, at) {
+    let line = 1;
+    for (let i = 0; i < at; i += 1) {
+        if (source[i] === "\n") {
+            line += 1;
+        }
+    }
+    return line;
+}
+/** The interpreted string literal starting at `at`, and the index after its closing quote. */
+function quoted(source, at, line) {
+    let value = "";
+    for (let i = at + 1; i < source.length; i += 1) {
+        const char = source[i] ?? "";
+        if (char === '"') {
+            return { value, end: i + 1 };
+        }
+        if (char === "\n") {
+            break;
+        }
+        if (char !== "\\") {
+            value += char;
+            continue;
+        }
+        const next = source[i + 1] ?? "";
+        const simple = ESCAPES[next];
+        if (simple !== undefined) {
+            value += simple;
+            i += 1;
+            continue;
+        }
+        const width = Object.hasOwn(ESCAPE_WIDTHS, next) ? ESCAPE_WIDTHS[next] : undefined;
+        const digits = width === undefined ? "" : source.slice(i + 2, i + 2 + width);
+        if (width === undefined || !/^[0-9A-Fa-f]+$/u.test(digits) || digits.length !== width) {
+            throw new TemplateError(`line ${String(line)}: the escape \\${next} is not supported`);
+        }
+        value += String.fromCodePoint(Number.parseInt(digits, 16));
+        i += 1 + width;
+    }
+    throw new TemplateError(`line ${String(line)}: unterminated quoted string`);
+}
+/** The tokens of one action, from `at` to its closing delimiter, and the index after it. */
+function lexAction(source, at, line) {
+    const tokens = [];
+    let i = at;
+    for (;;) {
+        const char = source[i];
+        if (char === undefined) {
+            throw new TemplateError(`line ${String(line)}: unclosed action`);
+        }
+        if (TRIM_SPACE.has(char) && source.startsWith(`-${RIGHT}`, i + 1)) {
+            return { tokens, end: i + 2 + RIGHT.length, trimRight: true };
+        }
+        if (source.startsWith(RIGHT, i)) {
+            return { tokens, end: i + RIGHT.length, trimRight: false };
+        }
+        if (TRIM_SPACE.has(char)) {
+            i += 1;
+            continue;
+        }
+        if (char === '"') {
+            const { value, end } = quoted(source, i, line);
+            tokens.push({ t: "lit", value });
+            i = end;
+            continue;
+        }
+        if (char === "`") {
+            const end = source.indexOf("`", i + 1);
+            if (end < 0) {
+                throw new TemplateError(`line ${String(line)}: unterminated raw quoted string`);
+            }
+            tokens.push({ t: "lit", value: source.slice(i + 1, end) });
+            i = end + 1;
+            continue;
+        }
+        if (source.startsWith(":=", i)) {
+            tokens.push({ t: "punct", text: ":=" });
+            i += 2;
+            continue;
+        }
+        if (char === "(" || char === ")" || char === "|" || char === "=" || char === ",") {
+            tokens.push({ t: "punct", text: char });
+            i += 1;
+            continue;
+        }
+        if (char === "." || char === "$") {
+            IDENTIFIER.lastIndex = i + 1;
+            const name = IDENTIFIER.exec(source)?.[0] ?? "";
+            if (char === "$") {
+                tokens.push({ t: "var", name: `$${name}` });
+            }
+            else if (name === "" && /[0-9]/u.test(source[i + 1] ?? "")) {
+                throw new TemplateError(`line ${String(line)}: a number is written with a leading digit`);
+            }
+            else {
+                tokens.push({ t: "field", name, attached: i > at && !TRIM_SPACE.has(source[i - 1] ?? "") });
+            }
+            i += 1 + name.length;
+            continue;
+        }
+        NUMBER.lastIndex = i;
+        const number = NUMBER.exec(source)?.[0];
+        if (number !== undefined) {
+            tokens.push({ t: "lit", value: Number(number) });
+            i += number.length;
+            continue;
+        }
+        IDENTIFIER.lastIndex = i;
+        const word = IDENTIFIER.exec(source)?.[0];
+        if (word !== undefined) {
+            const literal = { true: true, false: false, nil: null };
+            tokens.push(Object.hasOwn(literal, word)
+                ? { t: "lit", value: literal[word] ?? null }
+                : { t: "word", text: word });
+            i += word.length;
+            continue;
+        }
+        throw new TemplateError(`line ${String(line)}: unexpected ${JSON.stringify(char)} in an action`);
+    }
+}
+/** The template split into text and actions, trim markers and comments applied. */
+function lex(source) {
+    const pieces = [];
+    let i = 0;
+    let trimNext = false;
+    while (i < source.length) {
+        const open = source.indexOf(LEFT, i);
+        let text = source.slice(i, open < 0 ? source.length : open);
+        if (trimNext) {
+            text = text.replace(/^[ \t\r\n]+/u, "");
+        }
+        if (open < 0) {
+            pieces.push({ k: "text", text });
+            break;
+        }
+        const line = lineOf(source, open);
+        let at = open + LEFT.length;
+        if (source[at] === "-" && TRIM_SPACE.has(source[at + 1] ?? "")) {
+            text = text.replace(/[ \t\r\n]+$/u, "");
+            at += 2;
+        }
+        pieces.push({ k: "text", text });
+        if (source.startsWith("/*", at)) {
+            const close = source.indexOf("*/", at + 2);
+            if (close < 0) {
+                throw new TemplateError(`line ${String(line)}: unclosed comment`);
+            }
+            const after = close + 2;
+            if (source.startsWith(RIGHT, after)) {
+                i = after + RIGHT.length;
+                trimNext = false;
+            }
+            else if (source.startsWith(` -${RIGHT}`, after)) {
+                i = after + 2 + RIGHT.length;
+                trimNext = true;
+            }
+            else {
+                throw new TemplateError(`line ${String(line)}: a comment ends the action it is written in`);
+            }
+            continue;
+        }
+        const lexed = lexAction(source, at, line);
+        pieces.push({ k: "action", action: { tokens: lexed.tokens, line } });
+        i = lexed.end;
+        trimNext = lexed.trimRight;
+    }
+    return pieces.filter((piece) => piece.k !== "text" || piece.text !== "");
+}
+/** The parser over one template's pieces, with the variables in scope at each point. */
+class Parser {
+    at = 0;
+    scopes = [new Set(["$"])];
+    ranges = 0;
+    pieces;
+    constructor(pieces) {
+        this.pieces = pieces;
+    }
+    parse() {
+        const { list, ended } = this.list();
+        if (ended !== undefined) {
+            throw new TemplateError(`line ${String(ended.line)}: unexpected {{${ended.word}}}`);
+        }
+        return list;
+    }
+    /** Nodes up to the end of the template or to an `else` or `end`, which it returns. */
+    list() {
+        const list = [];
+        while (this.at < this.pieces.length) {
+            const piece = this.pieces[this.at];
+            this.at += 1;
+            if (piece === undefined) {
+                break;
+            }
+            if (piece.k === "text") {
+                list.push({ k: "text", text: piece.text });
+                continue;
+            }
+            const action = piece.action;
+            const first = action.tokens[0];
+            const word = first?.t === "word" ? first.text : undefined;
+            if (word === "end" || word === "else") {
+                return { list, ended: { word, action, line: action.line } };
+            }
+            list.push(this.node(action, word));
+        }
+        return { list, ended: undefined };
+    }
+    node(action, word) {
+        const line = action.line;
+        if (word === "if" || word === "with" || word === "range") {
+            return this.control(word, action.tokens.slice(1), line);
+        }
+        if (word === "break" || word === "continue") {
+            if (action.tokens.length !== 1) {
+                throw new TemplateError(`line ${String(line)}: {{${word}}} takes nothing`);
+            }
+            if (this.ranges === 0) {
+                throw new TemplateError(`line ${String(line)}: {{${word}}} outside {{range}}`);
+            }
+            return { k: word };
+        }
+        if (word !== undefined && REFUSED_KEYWORDS.has(word)) {
+            throw new TemplateError(`line ${String(line)}: {{${word}}} is not supported`);
+        }
+        return { k: "action", pipe: this.pipeline(action.tokens, line, "action") };
+    }
+    control(word, tokens, line) {
+        this.scopes.push(new Set());
+        try {
+            if (word === "range") {
+                this.ranges += 1;
+            }
+            const pipe = this.pipeline(tokens, line, word);
+            const body = this.list();
+            if (word === "range") {
+                this.ranges -= 1;
+            }
+            const ended = body.ended;
+            if (ended === undefined) {
+                throw new TemplateError(`line ${String(line)}: {{${word}}} has no {{end}}`);
+            }
+            const rest = ended.action.tokens.slice(1);
+            if (ended.word === "end") {
+                if (rest.length > 0) {
+                    throw new TemplateError(`line ${String(ended.line)}: unexpected tokens after {{end}}`);
+                }
+                return { k: word, pipe, list: body.list, otherwise: [] };
+            }
+            const chained = rest[0];
+            if (word !== "range" && chained?.t === "word" && chained.text === word) {
+                const otherwise = [this.control(word, rest.slice(1), ended.line)];
+                return { k: word, pipe, list: body.list, otherwise };
+            }
+            if (rest.length > 0) {
+                throw new TemplateError(`line ${String(ended.line)}: unexpected tokens after {{else}}`);
+            }
+            const tail = this.list();
+            if (tail.ended?.word !== "end" || tail.ended.action.tokens.length !== 1) {
+                throw new TemplateError(`line ${String(line)}: {{${word}}} has no {{end}} after its {{else}}`);
+            }
+            return { k: word, pipe, list: body.list, otherwise: tail.list };
+        }
+        finally {
+            this.scopes.pop();
+        }
+    }
+    declared(name) {
+        return this.scopes.some((scope) => scope.has(name));
+    }
+    pipeline(tokens, line, context) {
+        let rest = tokens;
+        let vars = [];
+        let assign = false;
+        const declaration = rest.findIndex((token) => token.t === "punct" && (token.text === ":=" || token.text === "="));
+        if (declaration > 0) {
+            const head = rest.slice(0, declaration);
+            const names = head.filter((_token, i) => i % 2 === 0);
+            const commas = head.filter((_token, i) => i % 2 === 1);
+            const valid = names.every((token) => token.t === "var" && token.name !== "$") &&
+                commas.every((token) => token.t === "punct" && token.text === ",") &&
+                names.length <= (context === "range" ? 2 : 1);
+            if (valid) {
+                vars = names.map((token) => (token.t === "var" ? token.name : ""));
+                const operator = rest[declaration];
+                assign = operator?.t === "punct" && operator.text === "=";
+                rest = rest.slice(declaration + 1);
+            }
+        }
+        const commands = this.commands(rest, line);
+        if (commands.length === 0) {
+            throw new TemplateError(`line ${String(line)}: missing value for ${context}`);
+        }
+        for (const name of vars) {
+            if (assign) {
+                if (!this.declared(name)) {
+                    throw new TemplateError(`line ${String(line)}: undefined variable ${name}`);
+                }
+            }
+            else {
+                this.scopes.at(-1)?.add(name);
+            }
+        }
+        return { vars, assign, commands };
+    }
+    commands(tokens, line) {
+        const commands = [];
+        let current = [];
+        let i = 0;
+        const finish = () => {
+            if (current.length === 0) {
+                throw new TemplateError(`line ${String(line)}: missing command in a pipeline`);
+            }
+            commands.push(current);
+            current = [];
+        };
+        while (i < tokens.length) {
+            const token = tokens[i];
+            if (token?.t === "punct" && token.text === "|") {
+                finish();
+                i += 1;
+                continue;
+            }
+            const { arg, next } = this.operand(tokens, i, line);
+            current.push(arg);
+            i = next;
+        }
+        if (current.length > 0 || commands.length > 0) {
+            finish();
+        }
+        return commands;
+    }
+    /** One operand starting at token `i`, its field chain included, and the index after it. */
+    operand(tokens, i, line) {
+        const token = tokens[i];
+        let arg;
+        let next = i + 1;
+        if (token === undefined) {
+            throw new TemplateError(`line ${String(line)}: missing operand`);
+        }
+        switch (token.t) {
+            case "lit":
+                arg = { k: "lit", value: token.value };
+                break;
+            case "word":
+                if (!FUNCTIONS.has(token.text)) {
+                    throw new TemplateError(`line ${String(line)}: function ${JSON.stringify(token.text)} not defined`);
+                }
+                return { arg: { k: "func", name: token.text }, next };
+            case "var":
+                if (!this.declared(token.name)) {
+                    throw new TemplateError(`line ${String(line)}: undefined variable ${token.name}`);
+                }
+                arg = { k: "var", name: token.name };
+                break;
+            case "field":
+                if (token.name === "") {
+                    arg = { k: "dot" };
+                    break;
+                }
+                arg = { k: "field", recv: undefined, names: [token.name] };
+                break;
+            case "punct": {
+                if (token.text !== "(") {
+                    throw new TemplateError(`line ${String(line)}: unexpected ${token.text} in an operand`);
+                }
+                let depth = 1;
+                let close = i + 1;
+                for (; close < tokens.length; close += 1) {
+                    const inner = tokens[close];
+                    if (inner?.t === "punct" && inner.text === "(") {
+                        depth += 1;
+                    }
+                    else if (inner?.t === "punct" && inner.text === ")") {
+                        depth -= 1;
+                        if (depth === 0) {
+                            break;
+                        }
+                    }
+                }
+                if (depth !== 0) {
+                    throw new TemplateError(`line ${String(line)}: unclosed left parenthesis`);
+                }
+                arg = {
+                    k: "pipe",
+                    pipe: this.pipeline(tokens.slice(i + 1, close), line, "parenthesized pipeline"),
+                };
+                next = close + 1;
+                break;
+            }
+        }
+        const names = [];
+        for (let chained = tokens[next]; chained?.t === "field" && chained.attached && chained.name !== ""; chained = tokens[next]) {
+            names.push(chained.name);
+            next += 1;
+        }
+        if (names.length > 0) {
+            if (arg.k === "lit") {
+                throw new TemplateError(`line ${String(line)}: a literal has no field`);
+            }
+            arg =
+                arg.k === "field" && arg.recv === undefined
+                    ? { k: "field", recv: undefined, names: [...arg.names, ...names] }
+                    : { k: "field", recv: arg, names };
+        }
+        return { arg, next };
+    }
+}
+/** Parses a template, or throws a {@link TemplateError} naming the line it fails at. */
+export function parseTemplate(source) {
+    return { nodes: new Parser(lex(source)).parse() };
+}
+/** The stop a `break` or a `continue` raises out of the body of its `range`. */
+class LoopStop extends Error {
+    kind;
+    constructor(kind) {
+        super(kind);
+        this.kind = kind;
+    }
+}
+function isList(value) {
+    return Array.isArray(value);
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !isList(value);
+}
+function truthy(value) {
+    if (value === null) {
+        return false;
+    }
+    if (typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return value !== 0;
+    }
+    if (typeof value === "string" || isList(value)) {
+        return value.length > 0;
+    }
+    return Object.keys(value).length > 0;
+}
+/** One value as an operand prints it: nested lists and objects in the bracketed form. */
+function formatted(value, nested) {
+    if (value === null) {
+        return nested ? "<nil>" : "<no value>";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    if (isList(value)) {
+        return `[${value.map((one) => formatted(one, true)).join(" ")}]`;
+    }
+    const object = value;
+    const entries = Object.keys(object)
+        .sort()
+        .map((key) => `${key}:${formatted(object[key] ?? null, true)}`);
+    return `map[${entries.join(" ")}]`;
+}
+function kindOf(value) {
+    if (value === null) {
+        return "nil";
+    }
+    if (isList(value)) {
+        return "list";
+    }
+    return typeof value === "object" ? "object" : typeof value;
+}
+function compareBasic(name, a, b) {
+    const kind = kindOf(a);
+    if (kind !== kindOf(b) || (kind !== "number" && kind !== "string" && kind !== "boolean")) {
+        throw new RenderError(`${name}: incompatible types for comparison: ${kindOf(a)} and ${kindOf(b)}`);
+    }
+    if (a === b) {
+        return 0;
+    }
+    if (kind === "boolean") {
+        return Number.NaN;
+    }
+    return a < b ? -1 : 1;
+}
+/** `printf`'s verbs, each over one operand. */
+function printf(format, args) {
+    let out = "";
+    let next = 0;
+    for (let i = 0; i < format.length; i += 1) {
+        const char = format[i];
+        if (char !== "%") {
+            out += char ?? "";
+            continue;
+        }
+        const verb = format[i + 1] ?? "";
+        i += 1;
+        if (verb === "%") {
+            out += "%";
+            continue;
+        }
+        if (next >= args.length) {
+            throw new RenderError(`printf: %${verb} has no operand`);
+        }
+        const arg = args[next] ?? null;
+        next += 1;
+        switch (verb) {
+            case "v":
+            case "s":
+                out += formatted(arg, false);
+                break;
+            case "q":
+                out += JSON.stringify(formatted(arg, false));
+                break;
+            case "d":
+                if (typeof arg !== "number" || !Number.isInteger(arg)) {
+                    throw new RenderError(`printf: %d over a ${kindOf(arg)}`);
+                }
+                out += String(arg);
+                break;
+            case "t":
+                if (typeof arg !== "boolean") {
+                    throw new RenderError(`printf: %t over a ${kindOf(arg)}`);
+                }
+                out += String(arg);
+                break;
+            default:
+                throw new RenderError(`printf: the verb %${verb} is not supported`);
+        }
+    }
+    if (next < args.length) {
+        throw new RenderError(`printf: ${String(args.length - next)} operand(s) left over`);
+    }
+    return out;
+}
+function ordered(name, order) {
+    switch (name) {
+        case "lt":
+            return order < 0;
+        case "le":
+            return order <= 0;
+        case "gt":
+            return order > 0;
+        case "ge":
+            return order >= 0;
+    }
+}
+/** The functions a command calls, each over its evaluated operands. */
+function call(name, args) {
+    const [first = null, second = null] = args;
+    const arity = (count) => {
+        if (args.length !== count) {
+            throw new RenderError(`${name} takes ${String(count)} operand(s), and ${String(args.length)} were given`);
+        }
+    };
+    switch (name) {
+        case "not":
+            arity(1);
+            return !truthy(first);
+        case "len":
+            arity(1);
+            if (typeof first === "string") {
+                return utf8Bytes(first).length;
+            }
+            if (isList(first)) {
+                return first.length;
+            }
+            if (isObject(first)) {
+                return Object.keys(first).length;
+            }
+            throw new RenderError(`len of a ${kindOf(first)}`);
+        case "index": {
+            let value = first;
+            for (const key of args.slice(1)) {
+                if (isList(value) && typeof key === "number" && Number.isInteger(key)) {
+                    if (key < 0 || key >= value.length) {
+                        throw new RenderError(`index out of range: ${String(key)}`);
+                    }
+                    value = value[key] ?? null;
+                }
+                else if (isObject(value) && typeof key === "string" && Object.hasOwn(value, key)) {
+                    value = value[key] ?? null;
+                }
+                else {
+                    throw new RenderError(`index of ${formatted(key, false)} into a ${kindOf(value)}`);
+                }
+            }
+            return value;
+        }
+        case "eq":
+            if (args.length < 2) {
+                throw new RenderError("eq takes at least two operands");
+            }
+            return args.slice(1).some((other) => compareBasic(name, first, other) === 0);
+        case "ne":
+            arity(2);
+            return compareBasic(name, first, second) !== 0;
+        case "lt":
+        case "le":
+        case "gt":
+        case "ge": {
+            arity(2);
+            const order = compareBasic(name, first, second);
+            if (Number.isNaN(order)) {
+                throw new RenderError(`${name}: booleans have no order`);
+            }
+            return ordered(name, order);
+        }
+        case "print":
+            return args
+                .map((arg, i) => {
+                const spaced = i > 0 && typeof arg !== "string" && typeof args[i - 1] !== "string";
+                return `${spaced ? " " : ""}${formatted(arg, false)}`;
+            })
+                .join("");
+        case "println":
+            return `${args.map((arg) => formatted(arg, false)).join(" ")}\n`;
+        case "printf":
+            if (typeof first !== "string") {
+                throw new RenderError("printf takes a format string first");
+            }
+            return printf(first, args.slice(1));
+        default:
+            throw new RenderError(`function ${JSON.stringify(name)} not defined`);
+    }
+}
+/** One execution of a template over a document. */
+class Execution {
+    scopes;
+    out = "";
+    constructor(root) {
+        this.scopes = [new Map([["$", root]])];
+    }
+    lookup(name) {
+        for (let i = this.scopes.length - 1; i >= 0; i -= 1) {
+            const scope = this.scopes[i];
+            if (scope?.has(name) === true) {
+                return scope.get(name) ?? null;
+            }
+        }
+        throw new RenderError(`undefined variable ${name}`);
+    }
+    assign(name, value) {
+        for (let i = this.scopes.length - 1; i >= 0; i -= 1) {
+            const scope = this.scopes[i];
+            if (scope?.has(name) === true) {
+                scope.set(name, value);
+                return;
+            }
+        }
+        throw new RenderError(`undefined variable ${name}`);
+    }
+    field(value, names) {
+        let held = value;
+        for (const name of names) {
+            if (!isObject(held)) {
+                throw new RenderError(`can't evaluate field ${name} in a ${kindOf(held)}`);
+            }
+            if (!Object.hasOwn(held, name)) {
+                throw new RenderError(`the document has no member ${JSON.stringify(name)} here`);
+            }
+            held = held[name] ?? null;
+        }
+        return held;
+    }
+    arg(arg, dot) {
+        switch (arg.k) {
+            case "dot":
+                return dot;
+            case "var":
+                return this.lookup(arg.name);
+            case "lit":
+                return arg.value;
+            case "pipe":
+                return this.pipeline(arg.pipe, dot, false);
+            case "field":
+                return this.field(arg.recv === undefined ? dot : this.arg(arg.recv, dot), arg.names);
+            case "func":
+                return call(arg.name, []);
+        }
+    }
+    command(command, dot, piped) {
+        const [head, ...rest] = command;
+        if (head === undefined) {
+            throw new RenderError("empty command");
+        }
+        if (head.k !== "func") {
+            if (rest.length > 0 || piped !== undefined) {
+                throw new RenderError("can't give an argument to a non-function");
+            }
+            return this.arg(head, dot);
+        }
+        const operands = () => {
+            const values = rest.map((one) => this.arg(one, dot));
+            return piped === undefined ? values : [...values, piped];
+        };
+        if (head.name === "and" || head.name === "or") {
+            const all = [
+                ...rest.map((one) => () => this.arg(one, dot)),
+                ...(piped === undefined ? [] : [() => piped]),
+            ];
+            if (all.length === 0) {
+                throw new RenderError(`${head.name} takes at least one operand`);
+            }
+            let value = null;
+            for (const operand of all) {
+                value = operand();
+                if (truthy(value) === (head.name === "or")) {
+                    return value;
+                }
+            }
+            return value;
+        }
+        return call(head.name, operands());
+    }
+    pipeline(pipe, dot, declares) {
+        let value;
+        for (const command of pipe.commands) {
+            value = this.command(command, dot, value);
+        }
+        const result = value ?? null;
+        const [only] = pipe.vars;
+        if (only !== undefined && (declares || pipe.assign)) {
+            if (pipe.assign) {
+                this.assign(only, result);
+            }
+            else {
+                this.scopes.at(-1)?.set(only, result);
+            }
+        }
+        return result;
+    }
+    run(nodes, dot) {
+        for (const node of nodes) {
+            switch (node.k) {
+                case "text":
+                    this.out += node.text;
+                    break;
+                case "action": {
+                    const value = this.pipeline(node.pipe, dot, true);
+                    if (node.pipe.vars.length === 0) {
+                        this.out += formatted(value, false);
+                    }
+                    break;
+                }
+                case "break":
+                case "continue":
+                    throw new LoopStop(node.k);
+                case "if":
+                case "with": {
+                    this.scopes.push(new Map());
+                    try {
+                        const value = this.pipeline(node.pipe, dot, true);
+                        const taken = truthy(value);
+                        this.run(taken ? node.list : node.otherwise, taken && node.k === "with" ? value : dot);
+                    }
+                    finally {
+                        this.scopes.pop();
+                    }
+                    break;
+                }
+                case "range":
+                    this.range(node, dot);
+                    break;
+            }
+        }
+    }
+    range(node, dot) {
+        this.scopes.push(new Map());
+        try {
+            const value = this.pipeline({ ...node.pipe, vars: [] }, dot, false);
+            let entries;
+            if (value === null) {
+                entries = [];
+            }
+            else if (isList(value)) {
+                entries = value.map((one, i) => [i, one]);
+            }
+            else if (isObject(value)) {
+                entries = Object.keys(value)
+                    .sort()
+                    .map((key) => [key, value[key] ?? null]);
+            }
+            else {
+                throw new RenderError(`range can't iterate over a ${kindOf(value)}`);
+            }
+            if (entries.length === 0) {
+                this.run(node.otherwise, dot);
+                return;
+            }
+            const [first, second] = node.pipe.vars;
+            for (const [key, element] of entries) {
+                const scope = this.scopes.at(-1);
+                if (second !== undefined && first !== undefined) {
+                    scope?.set(first, key);
+                    scope?.set(second, element);
+                }
+                else if (first !== undefined) {
+                    scope?.set(first, element);
+                }
+                try {
+                    this.run(node.list, element);
+                }
+                catch (stop) {
+                    if (!(stop instanceof LoopStop)) {
+                        throw stop;
+                    }
+                    if (stop.kind === "break") {
+                        break;
+                    }
+                }
+            }
+        }
+        finally {
+            this.scopes.pop();
+        }
+    }
+}
+/**
+ * The template's rendering of one document. The rendering is built whole, so a template
+ * that fails partway renders nothing, and the failure names what it could not evaluate.
+ */
+export function renderTemplate(template, document) {
+    const root = JSON.parse(JSON.stringify(document));
+    const execution = new Execution(root);
+    execution.run(template.nodes, root);
+    return execution.out;
+}