FORALL(4)

Table of Contents

• Name
• Synopsis
• Description
• Example
• See Also

Name

forall parse tree traversal construct
loopcounter local variable to a traversal

Synopsis

%forall name:TYPE
[ LEFT2RIGHT ] [ RIGHT2LEFT ] [ TOPDOWN ] [ BOTTOMUP ] [ in [ LIST ] C-expression ]
[ %depth integer-expression ]
[ %where C-expression ]
[ %separator template-stuff ]
%loop
template-stuff
%end-loop
INT loopcounter;

Description

The forall template construct provides a wide variety of powerful looping and parse tree traversal mechanisms for use in template and proc sections. The forall construct is a versatile construct that is well-suited for the needs of product generation.

The forall construct has many optional parts, but it typically takes the form:
%forall name:TYPE [ in C-expression ] %loop
template-stuff
%end-loop
The variable name, of type TYPE, is a local loop variable. It will iterate over all nodes of type TYPE found in the parse tree rooted at the node given by the C-expression. If there is no in clause then the entire parse tree (beginning at top) is traversed. During each iteration, the templatestuff that makes up the body of the loop is generated to the product. This means that any verbatim text in the body is copied once per iteration, and any template constructs in the body are processed once per iteration.

The default traversal order used in forall traversals is left-to-right and top-down; all nodes of type TYPE in the selected part of the parse tree are visited in that order. However, this behavior may be changed by using optional clauses. The keywords RIGHT2LEFT and BOTTOMUP may be used separately or together to change the traversal order (the keywords LEFT2RIGHT and TOPDOWN are also provided). The LIST keyword indicates a full list traversal. When this option is used, the C-expression in the in clause should be a member of a node list; that node, and all those that follow it in the list, are traversed.

In addition, the depth clause may be used to limit the depth of a traversal. A depth of one indicates that only the root of the selected part of the parse tree will be traversed (unless the LIST keyword is also used, in which case the nodes that follow the root node in a node list are also traversed). If the depth is two, then only those nodes at the root level and one level below the root level will be traversed. The where clause is used to provide a predicate that nodes must additionally meet before they can be visited. The C-expression in the where clause is evaluated for each node that would otherwise be visited. Only if the expression evaluates to TRUE will the node be visited.

The separator clause specifies the template-stuff that should separate the parts of the product that are generated by each iteration of the loop. Between each iteration, the template-stuff in this clause is generated to the product. This is particularly useful for generating lists that must be separated by punctuation.

A local C variable named loopcounter is automatically provided for each forall loop. This variable counts the loop iterations, beginning with one. This variable is often useful in expression and statement constructs found in the template-stuff.

Example

The following forall construct:
%forall f:FILENAME in filenames(top)
%separator;
%loop
%d(loopcounter) . %(tok(f))
%end-loop
would generate something like:
1. alpha;
2. beta;
3. ...

See Also

EXPRESSION(4)
FOR(4)
STATEMENT(4)
WHILE(4)
TRAVERSE(5)