 |
 |
|
|
       |
|||
|
|||||||||
|
|
|||||||||
| Related Syntax | Related Concepts | ||||||||
| control structure | repeat over, #item, #last, #first | ||||||||
Syntax
repeat over shelf-name (& shelf-name)*
local-declaration*
action*
again
A special form of the repeat action used to process successive items on a given shelf. The actions are repeated once for each item on the shelf.
References to the shelf name are interpreted as though followed by item 1 during the first iteration, by item 2 in the second iteration, and so forth.
repeat over can process the items on several shelves in parallel. The first item on each shelf is processed before the loop moves to the second item, and so on, until all items on all shelves have been processed.
In a repeat over action, it is often useful to know whether the loop is at the first or last iteration. Two predefined switches provide this information. The switch named #first is active only on the first iteration. The #last switch is active only on the last iteration. They are both active on the only iteration over a set with one member. These two switches are read-only; they can be tested in a switch test, but they cannot be explicitly activated or deactivated. When repeat over loops nest, each instance has its own #first and #last switches.
You can also ask for the index of the current iteration by accessing the predefined integer #item. It can be used in numeric expressions or in format items that format integers. When repeat over loops nest, each instance has its own indices.
repeat over can also be used to process the following:
If a repeat over action iterates over a set of attributes or over the tokens of an attribute, or if an attribute or attribute token is identified by a using prefix, then all text written to the #markup-parser stream will be "buffered" in the same manner until the action completes.
Can you add an item to a shelf inside a repeat over loop? Yes, but only at a position greater that the size of the shelf when the loop began. The number of iterations in the loop is determined before the first iteration, and adding more items to the shelf from within the loop will not change the number of iterations being performed.
Can you remove items from a shelf within a repeat over loop? Yes, but only items that were added within the same loop.
You can use three tools within a repeat over loop:
#item
#item can be used in numeric expressions or in format items that format integers.
The #item integer always provides a value of 1 for its first iteration and the number of items, tokens, attributes or opened elements for its last iteration. This occurs even if the "reversed" option is used, because #item never counts back to 1.
As a predefined shelf, #item is "read-only" and may not be passed as a modifiable argument.
#first
The #first switch always provides a value of "true" for the first iteration of a "repeat over" loop and on subsequent iterations always provides a value of "false".
#last
The #last switch always provides a value of "true" for the last iteration of a "repeat over" loop; on previous iterations, #last always provides a value of "false".
Usage example:
process
local switch flags variable initial-size 4 initial {true with key "one",
true with key "two",
true with key "three",
true with key "four"}
set flags{"one"} to true
set flags{ "two"} to false
set flags{"three"} to true
set flags{"four"} to false
repeat over flags
do select #item
case 1
output "1st flag is "
case 2
output "2nd flag is "
case 3
output "3rd flag is "
case 4 to 20
output "%d(#item)th flag is "
else
output "Flag number %d(#item) is "
done
do when #first
output "{first loop) "
done
do when #last
output "(last loop) "
done
do when flags
output "on.%n"
else
output "off.%n"
done
again
; Output: "1st flag is {first loop) on.
; 2nd flag is off.
; 3rd flag is on.
; 4th flag is (last loop) off."
| ---- |
