Template Engine: Blocks, Variables and Loops

Template Engine: Blocks, Variables and Loops

You've joined the team that owns templating, the small template engine behind transactional emails and receipts. Templates are stored by name, compiled when they are defined, and rendered against a JSON context. The engine currently handles plain text and {% if %} blocks only; a bug report is open against it, and three roadmap tickets are queued behind that.

Codebase

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh registry and returns exactly one result per operation. Errors are returned as "error: <message>" strings, never raised.

• name and source are strings and context is a JSON object. A wrong number of arguments or a wrong type returns "error: invalid arguments"; an unknown operation name returns "error: unknown operation".
• Redefining a name replaces the template. A define that fails leaves any previous definition of that name untouched.

Worked example

[["define", "hi", "Hi{% if vip %}, valued guest{% endif %}!"],
 ["render", "hi", {"vip": true}],
 ["render", "hi", {}],
 ["render", "nope", {}]]

returns

[true, "Hi, valued guest!", "Hi!", "error: unknown template 'nope'"]

Template syntax

• {{ ... }} is a variable and {% ... %} is a tag. Whitespace just inside the delimiters is ignored. Everything else is literal text and is copied to the output unchanged.
• Blocks (if now, for in Part 3) are closed by endif / endfor, and may be nested.
• Syntax errors are detected by define. Each message ends with at line N, where N is the 1-based line on which the offending tag starts (except "unclosed", see below): unterminated tag (a {{ or {% with no closing }} / %}), empty expression ({{ }} or {% %}), invalid expression, unknown tag '<name>', unexpected '<tag>' and unclosed '<tag>' opened. When several things are wrong, the first problem in document order is reported; "unclosed" is checked last and names the innermost block still open.

Part 1 — Nested blocks render the wrong text

Goal. Customer emails with an {% if %} inside another {% if %} sometimes drop or misplace text, and conditions on empty values take the wrong branch. Fix the engine so the rules below hold.

Rules

1. {% if path %}, {% if not path %}, {% else %} and {% endif %} work as in the existing tests. In Part 1 path is a top-level key of the context.
2. An {% else %} or {% endif %} always applies to the innermost block that is still open. A block has at most one {% else %}.
3. An {% endif %} or {% else %} with no matching open block is unexpected 'endif' / unexpected 'else' (at the tag's line). So is any endif/else that carries extra text.
4. A condition is false when the value is missing, null, false, 0 (or 0.0), "", [] or {}. Everything else is true, including the string "0" and "false" and a list such as [0].

Example

[["define", "t", "[{% if a %}A{% if b %}B{% else %}b{% endif %}Z{% else %}a{% endif %}]"],
 ["render", "t", {"a": true, "b": false}],
 ["render", "t", {"a": false, "b": true}]]

returns [true, "[AbZ]", "[a]"].

Part 2 — Variables with escaping and dotted paths

Goal. Support {{ path }} so templates can show data, safely.

Rules

1. A path is one or more segments of letters, digits and _, joined by . (for example user.address.city or items.0.sku). Any other expression inside {{ }} is an invalid expression. {% if %} conditions accept the same dotted paths.
2. The first segment is looked up in the context. Each later segment indexes into the value found so far: into an object by key, or into a list by a non-negative integer. If any step is impossible (no such key, index out of range, the value is a string/number/boolean/null) the whole path is missing.
3. A missing path or a null value renders as the empty string. Strings render as they are, true / false render as true / false, and numbers render the way JSON writes them (42, 2.5).
4. A list or an object cannot be shown: the render fails with "error: '<path>' is not a scalar".
5. Every value written by {{ }} is HTML-escaped: & becomes &, < &lt;, > >, " " and ' '. Literal template text is never escaped, and a value that already contains & is escaped again (&).
6. {{ path|raw }} (whitespace around | allowed) writes the value without escaping. Any other filter name is a syntax error unknown filter '<name>'; more than one | is an invalid expression. New filters should go through the FILTERS registry.

Example

[["define", "c", "<p>{{ user.name }} ({{ user.tags.1 }}) {{ user.bio|raw }}</p>"],
 ["render", "c", {"user": {"name": "Tom & <Jerry>", "tags": ["a", "it's"], "bio": "<b>hi</b>"}}]]

returns [true, "<p>Tom &amp; &lt;Jerry&gt; (it&#39;s) <b>hi</b></p>"].

Part 3 — {% for %} loops

Goal. Let templates repeat a section for each item of a list.

Rules

1. {% for name in path %} ... {% endfor %} renders its body once per item of the list at path, in order. name is an identifier (letters, digits, _, not starting with a digit) and may not be loop; anything else malformed in the tag is an invalid expression.
2. Inside the body name is bound to the current item and shadows any context key of the same name. After the loop (and in its else section) the earlier meaning of name is back.
3. Inside the body, loop is an object with loop.index (1-based), loop.index0, loop.first and loop.last (booleans), and loop.length. Loops nest: the inner loop shadows the outer one and the outer one is visible again after the inner loop ends. A loop key in the context is shadowed the same way and is untouched outside loops.
4. An optional {% else %} before {% endfor %} renders when the list is empty, missing or null.
5. If the value at path is anything else (object, string, number, boolean) the render fails with "error: cannot iterate over '<path>'".
6. {% else %} belongs to the innermost open block, whether that is an if or a for; each end tag must close the innermost block of its own kind, otherwise it is unexpected 'endfor' / unexpected 'endif'. unclosed 'for' opened applies as in Part 1.
7. Items can be anything: objects ({{ user.name }}), lists ({{ row.0 }}), and so on, and all of Parts 1-2 keeps working inside loops.

Example

[["define", "l", "{% for x in xs %}{{ x }}{% if not loop.last %}, {% endif %}{% else %}none{% endfor %}"],
 ["render", "l", {"xs": ["a", "b", "c"]}],
 ["render", "l", {"xs": []}]]

returns [true, "a, b, c", "none"].

Part 4 — Large renders are too slow (stretch)

Goal. Nightly statement jobs render nested loops that produce hundreds of kilobytes per call, and some render the same page thousands of times. Both take too long. Make rendering fast without changing any output.

Rules

1. Output must be identical to Parts 1-3 for every input, including every error message.
2. Rendering a template with about 75,000 loop iterations in total (for example three nested loops of 42 items) must finish well inside the time limit, and 250 renders of one mid-sized template (about 200 tags) must as well.
3. Redefining a template must take effect immediately for later renders; a failed define must not change what renders.

Notes

• lexer.py, errors.py and nodes.py are known-good apart from the additions the parts ask for.
• You may use the AI assistant freely. Later parts must not break earlier ones; the hidden tests re-check every part. Parts 1-3 is a strong result; Part 4 is a stretch.