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:

N₀..N_limit

N₀, N₁..N_limit

N₀..N_limit 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 (N₀..N_limit). In this case, the numbers are iterated one by one beginning with the N₀ until N_limit is reached (including the value N_limit itself). If N_limit is less than N₀, the cycle runs down from N_limit to N₀. If the value N₁ is specified in addition to N₀¸ the step is determined from the difference N₁–N₀. If N₁ is greater than N_limit, neither value N₁ nor N_limit 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.