Sfairadora

  • Reference Guide

for Cycle

for(Type ctl_var = DOMAIN) body endfor
for(Type ctl_var = DOMAIN & filter) body endfor
for(Type &ctl_var = DOMAIN) body endfor
for(Type &ctl_var = DOMAIN & filter) body endfor
DOMAIN is one of the following:
N0..Nlimit
N0, N1..Nlimit
N0..Nlimit by step
sequence
The for cycle first creates a control variable of the name specified by the identifier ctl_var. Values from the specified domain are successively assigned to this variable. For each assigned value, the body template is processed and its result is appended to the output text. The cycle body is thus evaluated as many times as many elements are there in the domain.

Domain

The domain is either a sequence of number (integer or real) or a value of the sequence data type. Besides of numbers, a domain of characters (the type Char) can be constructed. A numerical sequence is constructed as an interval specified by its first and last value (N0..Nlimit). In this case, the numbers are iterated one by one beginning with the N0 until Nlimit is reached (including the value Nlimit itself). If Nlimit is less than N0, the cycle runs down from Nlimit to N0. If the value N1 is specified in addition to N0¸ the step is determined from the difference N1–N0. If N1 is greater than Nlimit, neither value N1 nor Nlimit is used in cycle iteration. The step can also be specified using the clause by.
Domain Examples:
10..5 10, 9, 8, 7, 6, 5
0, 2..10 0, 2, 4, 6, 8, 10
0, 2..9 0, 2, 4, 6, 8
0, –1..10 empty domain; the cycle is not passed even once.
1, 1.1..2 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 2.0,
10..0 by –2 10, 8, 6, 4, 2, 0
'a'..'e' by 2 'a', 'c', 'e'
In the case of domain of the sequence data type, a reference to a sequence (or a table) within the document data, a constant of the sequence data type (e.g. {"January", "February", "March"}), or of course an arbitrary expression returning a sequence.
The values giving the interval limits and the sequence are specified as Enki expressions.

Control Variable

The Type expression specifies the type of the control variable. If the type can be inferred from the domain type, it is not necessary to specify it explicitly. This is especially useful when the cycle iterates through table rows, as the type of the row can be a complex structure.
The name of the control variable can be preceded by the symbol & (the syntax element flags) which makes the variable to iterate through the domain by reference rather than by value. That means that a reference to the element being iterated is assigned to the control variable, rather than the value of the element itself. This option can be used only for domains that are themselves specified by a reference to a data object (by a (l-value). The advantage of iteration by reference is twofold. First, the element values can be changed during the iteration (which is, however, not recommended in templates). Second, for complex tables, this method is more efficient, because it is not necessary to copy all the row data from the table into the control variable.

Using Filter

The cycle domain can be further modified by a filter. The filter is written immediately after the domain specification, separated by the & (ampersand) sign. The filter is a condition (an Enki expression of the Bool type), which determines whether the cycle body is to be processed for the element in question. For each domain element, the condition is evaluated first. If the result is FALSE, the body is not processed, and the execution proceeds to the next domain element, instead.
The advantage of using a filter as opposed to an if-condition inside the cycle body is in proper determination of the last pass by the operator is_last_pass.

Remarks

If a minus sign is appended to the endfor keyword (endfor-), the attribute “keep with previous paragraph” is set to the last paragraph resulting from the last pass of the cycle. This can be used in a case when the for cycle generates a list in order to prevent placing the last list item at a separate page.
Instead of endfor, it is also permitted to write end for.
It is possible to used the Enki functions is_first_pass, is_last_pass, and pass_count in relation to the Enkidu for cycle in the same way as they are used in relation to the Enki language for cycle.

See Also