# Temple — FAQ
Implementation-level questions about how the engine actually works. For the
design see [`DESIGN.md`](DESIGN.md); for where the code lives,
[`ARCHITECTURE.md`](ARCHITECTURE.md).
---
## How are `{{ … }}` placeholders filled in?
At compile, the output literal becomes a tree of `OutNode`s; each `{{ … }}` is
recorded as a hole with an expression ID. At render, the engine recursively
walks the tree and builds the output `Value`:
```rust
enum OutNode {
Literal(Value), // "POST", 3, true — no holes
Hole(ExprId), // {{ expr }} as a value
Object(Vec<(SmolStr, NodeId)>), // { "k": <node>, ... }
Array(Vec<NodeId>), // [ <node>, ... ] — literal brackets in the template
Interp(Vec<StrPart>), // "Hi {{ name }}!"
}
enum StrPart { Text(SmolStr), Hole(ExprId) }
fn build(node: NodeId, ctx: &Ctx) -> Result<Value, RenderError> {
match &nodes[node] {
OutNode::Literal(v) => Ok(v.clone()),
OutNode::Hole(eid) => eval_expr(*eid, ctx),
OutNode::Object(fs) => Ok(Value::Obj(
fs.iter().map(|(k, n)| Ok((k.clone(), build(*n, ctx)?))).collect()?
)),
OutNode::Array(items) => Ok(Value::Arr(
items.iter().map(|n| build(*n, ctx)).collect()?
)),
OutNode::Interp(ps) => { /* text parts as-is; holes stringified */ }
}
}
```
- A **bare hole** emits the expression's typed `Value`.
- A **quoted hole** (interp string) stringifies each hole's value and
concatenates with the literal text parts.
---
## How does input get parsed, and how is `input.value.nestedValue` resolved?
The caller hands `render` any `impl Into<Value>` — `serde_json::Value`,
`HashMap<String, V>`, or your own struct via `Serialize`. The `From` impls drop
it into Temple's `Value` enum **once**, before render starts. From there it's
just a `Value::Obj(IndexMap<SmolStr, Value>)` sitting under the name `input`.
At parse, `input.value.nestedValue` becomes a root + segment list — built
**once** at compile, not re-parsed per render:
```rust
enum Expr { Path { root: PathRoot, segs: Vec<Seg> }, /* … */ }
enum PathRoot { Input, This, Var(VarId) }
enum Seg { Field(SmolStr), Index(i64), OptField(SmolStr), OptIndex(i64) }
```
At render, walk one segment at a time:
```rust
fn eval_path(root: &Value, segs: &[Seg], ctx: &Ctx) -> Result<Value, RenderError> {
let mut cur = root;
for seg in segs {
cur = match (cur, seg) {
(Value::Obj(m), Seg::Field(k)) => m.get(k).ok_or_else(|| missing(k, ctx))?,
(Value::Arr(v), Seg::Index(i)) => v.get(*i as usize).ok_or_else(|| out_of_range(*i, ctx))?,
(Value::Obj(m), Seg::OptField(k)) => m.get(k).unwrap_or(&Value::Null),
(Value::Arr(v), Seg::OptIndex(i)) => v.get(*i as usize).unwrap_or(&Value::Null),
(Value::Null, Seg::OptField(_) | Seg::OptIndex(_)) => &Value::Null,
(other, Seg::Field(_) | Seg::Index(_)) => return Err(type_mismatch(other.kind(), ctx)),
// …
};
}
Ok(cur.clone())
}
```
So `input.value.nestedValue` is just three dictionary lookups on the input
`Value`. No reflection, no string parsing per call. `?.` flips the same lookup
into "missing ⇒ Null, propagate."
---
## How are arrays handled at runtime?
Two distinct cases — important to keep straight:
**(a) Array *literals* in the output template** — when you write:
```
"keys": [{{ input.a }}, {{ input.b }}, 42]
```
This is a fixed-shape, three-element array. The parser builds it as
`OutNode::Array([NodeId(hole_a), NodeId(hole_b), NodeId(literal_42)])`. At
render, each child is built; results collect into a `Value::Arr` of length 3.
**(b) Computed arrays inside an expression** — when you write:
```
"items": {{ input.cart.items.map(it -> it.qty * it.price) }}
```
The output node is a single `OutNode::Hole(eid)`. The expression at `eid` is a
method call:
```rust
enum Expr {
Method { receiver: ExprId, kind: MethodKind, args: Vec<ExprId> },
Lambda { params: Vec<VarId>, body: ExprId },
// …
}
enum MethodKind { Map, Filter, Fold, Len, Sum, Any, All }
```
Evaluation:
```rust
fn eval_method(recv: Value, kind: MethodKind, args: &[ExprId], scope: &mut Scope) -> Result<Value, RenderError> {
let items = match recv {
Value::Arr(v) => v,
other => return Err(method_on_non_array(other)),
};
match kind {
MethodKind::Map => {
let (param, body) = unwrap_lambda(args[0]);
let mut out = Vec::with_capacity(items.len());
for it in items {
scope.vars[param.0] = it;
out.push(eval_expr(body, scope)?);
}
Ok(Value::Arr(out))
}
MethodKind::Filter => { /* same loop, keep where body == Bool(true) */ }
MethodKind::Fold => {
let init = eval_expr(args[0], scope)?;
let ([acc_p, x_p], body) = unwrap_lambda2(args[1]);
let mut acc = init;
for it in items {
scope.vars[acc_p.0] = acc;
scope.vars[x_p.0] = it;
acc = eval_expr(body, scope)?;
}
Ok(acc)
}
MethodKind::Len => Ok(Value::Int(items.len() as i64)),
// sum/any/all — literally fold under the hood
}
}
```
Lambdas are AST nodes, not values; their params are pre-allocated `VarId`s, so
a call is just "write the param slot, eval the body." No allocation per call.
---
## If my hole evaluates to an array, can I `.map` over it?
**Yes.** The two cases above aren't a constraint — they're how the AST records
*statically-written* arrays differently from *computed* arrays. From the
template author's point of view there's no choice to make: write any
expression in `{{ … }}`, including chained collection methods.
`OutNode::Array([ … ])` exists only when the *template literal* has brackets:
`"keys": [a, b, c]`. The brackets were in your source.
If your hole's expression produces an array, the output node is
`OutNode::Hole(eid)`, and inside the expression you have the full language:
```
"high_value": {{ input.items.map(it -> it.price).filter(p -> p > 100) }}
"total": {{ input.items.map(it -> it.qty * it.price).fold(0, (a, b) -> a + b) }}
"first_skus": {{ input.items.filter(it -> it.in_stock).map(it -> it.sku) }}
```
Each is a single output hole — `OutNode::Hole(eid)` — whose expression yields
a `Value::Arr` of whatever length. The output node doesn't care about shape;
the expression does the work.
The thing you *can't* do is mix the template's bracket syntax with method
syntax outside a hole — e.g. write `[1, 2, 3].map(...)` at the output level.
Methods live in expressions, so the chain has to be inside a `{{ … }}`.
---
## A complete render trace
For `{{ input.cart.items.map(it -> it.qty * it.price).fold(0, (a, b) -> a + b) }}`:
1. The output AST has `Hole(eid)` here. `build` calls `eval_expr(eid)`.
2. `eval_expr` sees `Method { kind: Fold, … }` — evaluate the receiver first.
3. Receiver is `Method { kind: Map, … }` — evaluate *its* receiver first.
4. Receiver of `map` is `Path { Input, [Field("cart"), Field("items")] }` — `eval_path` walks two `.get`s on the input → `Value::Arr(items)`.
5. `.map(it -> it.qty * it.price)` — loop items, bind `it`, evaluate `it.qty * it.price` (two paths + a `Decimal *`) → `Value::Arr(prices)`.
6. `.fold(0, (a, b) -> a + b)` — loop, bind `a, b`, evaluate `a + b`, accumulate → `Value::Decimal(total)`.
7. That `Value` becomes the hole's result. `build` slots it into the output object at the current key.
No reflection, no string lookups, no type erasure. Everything is a `match` on
small enums plus array indexing.
---
## Why does Temple have its own `Value` instead of `serde_json::Value`?
Because of **one variant**. Both enums are "data in memory", but they disagree
on what a number is:
```text
serde_json::Value temple_dsl::Value
───────────────── ─────────────────
Null Null
Bool(bool) Bool(bool)
Number(Number) ◄── ONE number slot Int(i64) ◄── TWO number slots
(i64 | u64 | f64) Decimal(Decimal) ◄──
String(String) Str(SmolStr)
Array(Vec) Arr(Vec)
Object(Map) Obj(IndexMap)
```
In `serde_json`, any number with a decimal point becomes an `f64` — a *binary*
float that physically cannot store most decimal fractions:
```text
0.1 + 0.2 == 0.30000000000000004 ← visibly wrong
129.99 is stored as 129.99000000000000909495 ← prints as "129.99", but it's lying
```
The second line is the dangerous one: the error is usually invisible (printing
rounds it away) and surfaces randomly — a total off by a cent, a `==` that
fails. Temple's contract is *exact decimals*, so its `Value` keeps integers in
`Int` and fractional numbers in `Decimal` — and has **no f64 variant at all**.
The wrong type doesn't exist, so the mistake can't be made.
Owning the type also bought three things a borrowed type couldn't:
| **Ordered keys** | `Obj` is an `IndexMap` — output keys always come out in template order |
| **`render::<Value>` is a compile error** | `Value` deliberately doesn't implement `Deserialize` (see below) |
| **Stack-safe drop** | `Value` has an iterative `Drop`, so even a pathologically deep value can't overflow the stack — part of the no-panic guarantee |
---
## How does `Decimal` stay exact end to end?
`rust_decimal::Decimal` stores **base-10 digits** — an integer mantissa plus a
"where's the decimal point" scale — so decimal math is integer math underneath:
```text
129.99 is stored as (mantissa: 12999, scale: 2) → 12999 × 10⁻²
0.0825 is stored as (mantissa: 825, scale: 4) → 825 × 10⁻⁴
multiply: 12999 × 825 = 10724175, scales add 2+4=6 → 10.724175 EXACT
```
The danger zones are the **boundaries** — anywhere data crosses in or out, an
f64 detour could silently corrupt the digits. Every crossing is guarded:
```mermaid
sequenceDiagram
participant J as JSON text "129.99"
participant T as temple::Value
participant E as Evaluator
participant O as Your Rust struct
Note over J,T: ① INPUT boundary
J->>T: verbatim token "129.99" → Decimal(12999, scale 2)
Note right of T: never via as_f64() — text → Decimal directly
Note over T,E: ② TEMPLATE literals
Note right of E: `0.0825` in source is parsed by Temple's<br/>own parser straight into Decimal
Note over E: ③ MATH
E->>E: Decimal × Decimal = Decimal (exact, checked)
Note over E,O: ④ OUTPUT boundary (render::<T>)
E->>O: Decimal handed over as the digit-string "10.724175"
Note right of O: rust_decimal's Deserialize re-parses the<br/>exact digits into YOUR Decimal field
```
1. **Input** — library callers build `Value::Decimal` directly (this is why
`render` takes `impl Into<Value>`, not `impl Serialize`: a generic
`Serialize` would let a struct's `f64` field sneak corrupted digits in).
JSON input converts via the `json` feature's `From<serde_json::Value>`,
which parses the **verbatim number token** into `Decimal` — never `as_f64()`.
2. **Template literals** — `0.0825` in template source never touches serde;
Temple's parser reads the characters into a `Decimal`.
3. **Math** — decimal-to-decimal with checked arithmetic; `Int` mixed with
`Decimal` promotes to `Decimal`. No float ever appears mid-evaluation.
4. **Output** — serde's number vocabulary is i64/u64/f64, so handing a
`Decimal` over *as a number* would force the f64 detour at the last step.
Instead the custom `Deserializer` emits it as a **string of exact digits**;
`rust_decimal`'s own `Deserialize` re-parses them losslessly into your
struct's `Decimal` field. (An `f64` struct field still works — that's an
explicit opt-in where *you* chose the approximation.) Converting to
`serde_json::Value` via the `json` feature emits a real JSON **number
token** with the exact digits, courtesy of `arbitrary_precision`.
---
## Why is `render::<Value>` a compile error?
Deserializing a `Value` into a `Value` would be a pointless full copy through
serde. Because Temple owns the type, the trap became a compile error: `Value`
simply doesn't implement `Deserialize`.
```rust
template.render::<Receipt>(input) // ✓ typed output
template.render::<serde_json::Value>(input) // ✓ JSON output
template.render::<temple_dsl::Value>(input) // ✗ does not compile
template.render_value(input) // ✓ the direct way — no serde round-trip
```
Internally this is why the AST stores literals as a separate `Lit` type rather
than `Value`: the serialized blob needs `Deserialize` on everything it
contains, and keeping `Value` out of the AST keeps it out of `Deserialize`.
---
## How do I use `serde_json::Value` with Temple?
Enable the `json` feature and the conversions are built in, exact in both
directions:
```toml
temple-dsl = { git = "…", branch = "release", features = ["json"] }
```
```rust
// IN: serde_json::Value goes straight into render (via From / Into<Value>)
let input: serde_json::Value = serde_json::from_str(body)?;
let out = template.render_value(input)?;
// OUT: convert back — decimals become exact JSON number tokens
let json = serde_json::Value::from(out);
```
The input conversion parses each number's verbatim token (`"129.99"` →
`Decimal`, never through `f64`); the output conversion emits decimals as real
JSON numbers with the exact digits. A number beyond `Decimal`'s range
(≈ ±7.9 × 10²⁸) converts to `Null` rather than silently rounding. The core
crate stays dependency-lean: `serde_json` only enters the tree when the `json`
(or `cli`) feature is on.