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