foreach ';' MACRO (';' LIST)*

Summary

The foreach macro iterates over one or more lists and invokes a specified macro for each element, passing both the element value and its index (0-based) as arguments. The results are collected and returned as a comma-separated list.

Syntax

${foreach;<macro-name>[;<list>...]}

Parameters

• macro-name - Name of a macro to invoke for each element (without the ${} wrapper)
• list - One or more semicolon-separated lists to iterate over

Behavior

• Combines all provided lists into a single list
• Iterates through each element with a 0-based index
• For each element, invokes: ${<macro-name>;<element>;<index>}
• Collects all macro results
• Returns results as a comma-separated string

Examples

Transform each element:

# Define a macro to wrap elements
my-macro;$1-modified

# Use foreach
${foreach;my-macro;apple,banana,cherry}
# Invokes: ${my-macro;apple;0}, ${my-macro;banana;1}, ${my-macro;cherry;2}

Number items in a list:

# Define numbering macro
num;$2: $1

${foreach;num;first,second,third}
# Returns: "0: first,1: second,2: third"

Process file list:

# Define file processing macro
process-file;processed-$1

${foreach;process-file;${lsr;src;*.java}}

Generate indexed output:

# Define template macro
item-template;<item index="$2">$1</item>

${foreach;item-template;red,green,blue}
# Returns XML items with indices

Use Cases

• Transforming lists with complex logic
• Generating indexed output
• Applying templates to list elements
• Creating numbered or labeled items
• Building structured output from lists
• Mapping values with context (index)

Notes

• The invoked macro receives two arguments: the value and the index (0-based)
• The macro must be defined before use (either as a property or built-in macro)
• Results are joined with commas
• Index starts at 0 for the first element
• Empty lists produce empty results
• See also: ${map} for simpler transformations without index
• See also: ${apply} for passing entire lists to a macro

See test cases in MacroTestsForDocsExamples.java