repeat over current elements

control structure

Syntax
repeat over reversed? current elements (of element-expression)? as alias
   local-scope
again
    


Purpose

repeat over current elements is a form of the repeat over loop used to iterate over opened elements and access information about them. The default behavior of a repeat over current elements loop is to start with the element that was opened first and iterate towards the most recently opened element, processing each open element in turn. Specifying reverse reverses the direction of the loop: the loop therefore starts with the most recently opened element, and ends with the outermost element.

Within a repeat over current elements loop, the alias provides a way to access the element selected in the current iteration. A reference to the alias must be prefixed by the herald current element.

If element-expression is specified and identifies an open element, the loop is restricted to the range beginning with the outermost element, and ending with the element identified by element-expression; specifying reverse will reverse the direction of the loop, but the set of iterated elements remains restricted to the same range as if reverse had not been specified.

If there are no open elements, or element-expression is specified and identifies an element that is not open, the loop is not executed: it effectively identifies an empty set of opened elements.

#item is always 1 on the first iteration, and equal to the number of opened elements on the last iteration, even when reversed is specified. #item never decrements.

All text written to a markup parser within a repeat over current elements loop is buffered: none of the text is actually passed to the markup parser until after the end of the repeat over current elements loop.

The %q format item, references to attributes, and element tests are not affected by a repeat over current elements loop. These apply to the same element within the loop as they would outside the loop. In other words, the use of %q in a repeat over current elements loop does not give the name of the element selected by the current iteration, but rather that of the most recently opened element.

current element alias can be used in several contexts within the repeat over current elements loop:

  • to identify a specific opened element,
  • to test the identity of the currently selected element,
  • to get the name of the currently selected element, and
  • to get the number of opened elements, down to and including the currently selected element.

It is possible to use a name as both an alias and a real, unquoted element name. If such a name is used in any context other than immediately following the herald current element, it refers to the element with that name and not to the alias. However, the use of unquoted element names in OmniMark programs is discouraged.

This code sample will close all of the elements which are currently open. Note, however, that because input to the parser is buffered while the loop is running, the elements will not actually be closed until the repeat over current elements loop is complete.

  repeat over reversed current elements as e
     output "</"
     output name of current element e
     output ">"
  again
          

Elements of

The functionality of current elements is limited. Users are encouraged to use elements of instead.