Iteration

(each @collection as item) … (end) renders its body once per element, in source order. It is how you turn a collection into a table of contents, a list, a set of cards — any repeated view of your data.

Over scalars and over records

#themes: [ solitude, vigilance, return ]

(each @themes as item) The watch returned to @item. (end)

Inside the body, @item is the whole element. When the elements are records, walk into them with a dotted access:

#watchers: [ { name - Ada, post - lamp }, { name - Bo, post - log } ]

(each @watchers as item) @item.name kept the @item.post. (end)

(each-over-records.) Loop variables are usable inside parameter values too — @watch |keeper @item.name| (body-with-params).

Collections only

The target must be a collection. A record or scalar is not iterable — E_NOT_ITERABLE. There is no "iterate a record's fields" form; to loop a nested list, point at it with a dotted target like @deck.hands.

Scope and shadowing

The loop variable is body-local and shadows a same-named global:

#item: solitary
#hands: [ { name - Ada }, { name - Bo } ]

Outside the loop, @item is solitary.

(each @hands as item) @item.name (end)

Outside, @item is the global solitary; inside, it is each element in turn. Resolution precedence is: iteration frames (innermost first), then data definitions, then node definitions.

What iteration does not give you

There is no index, position, first, last, or counter variable — call it out when you plan a layout that needs numbering, and supply the numbers in the data or via a script. An empty collection emits nothing(not an error; fixture empty-collection), an empty body is legal (empty-body), and order is always preserved (iteration-order-preservation).

Nesting and combining with conditions

Loops nest — the inner loop gets its own frame, and the outer element stays visible:

(each @decks as deck)
  (each @deck.hands as hand) @hand, (end)
(end)

(nested-each; (end) tokens pair last-in-first-out, end-token-pairing.) A loop and a condition compose, with the condition resolved through the iteration frame:

(each @hands as item)
  (if @item.awake is true) @item.name is on watch. (end)
(end)

Common mistakes

• Iterating a record — use a collection, or a dotted list inside it.
• Expecting an index variable — there is none.
• Gluing (each …)(if …) with no space — the inner statement is not recognised. Keep a space or newline (see Gotchas).

See also

· Data · Data access · Self-organising documents · Multi-file references