@for

Repeats its body a number of times, over a range, or once per row of a dataset.

On this page

#Attributes

nRequiredImplicit
How many times, or over what: a whole count (@for:3), an inclusive range that counts upward (@for:0..6, @for:-1..1), or a tabular dataset (@for:#islands, @for:#biology.lynx-hare), walked top to bottom.
number | interval | reference
Can be written as shorthand: @for:value
as
The binding's name, i when omitted: as: k makes it {{k}}. Over a dataset it renames the cells too, {{row.area}}. A nested loop with the same name hides the outer one's.

#Allowed content

Body { }The content to repeat — spliced once per iteration with {{i}} (and, over a dataset, {{i.column}}) substituted

#Examples

graph{
    @for:0..4{
        point(x: {{i}}; y: {{i}})
    }
}
@for(n: 1..3; as: k){
    Attempt {{k}} of 3.
}
@data#islands{
    island     | area   | species
    Baltra     | 25.09  | 58
    Bartolomé  | 1.24   | 31
    Santa Cruz | 903.82 | 444
}

@for:#islands{
    {{i}}. {{i.island}} covers {{i.area}} km$^2$.
}
@data#islands{
    island     | area   | species
    Baltra     | 25.09  | 58
    Bartolomé  | 1.24   | 31
    Santa Cruz | 903.82 | 444
}

@for(n: #islands; as: row){
    @if(when: row.island = Santa Cruz){
        {{row.island}} has {{row.species}} species.
    }
}

#Notes

  • {{i}} is the counter: the value in the range, or the row number from 1 over a dataset. Over a dataset {{i.column}} is that row's cell, spliced as text and parsed by the position it lands in.
  • A count of 0 repeats nothing. A count that is not a whole number is refused: n must be a non-negative integer count, an inclusive from..to range, or a tabular dataset #id, got 2.5.
  • A descending range is refused: descending range 4..2 — from..to iterates upward, so from must not exceed to.
  • The dataset is declared above the loop: @for reads its dataset in document order, so the @data must come first.
  • A column is refused, with the fix: #islands.area names a column, and @for goes through rows — loop over #islands and write {{i.area}} in the body. A geo dataset has no rows to go through.
  • A cell name the dataset lacks is refused with the list of columns: row i has no column nope — its columns are area, island, species.
  • n is decided as the document compiles. An implicit value cannot hold a {{…}} expression, so a computed count is written @for(n: {{count}}), and a bound value is refused.
  • An id in the body that splices the counter, point#p-{{i}}, gives one id per pass.
  • There is no filter or sort; an @if in the body chooses rows.

Last updated