<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <title>Ant-contrib Tasks: For</title> </head> <body> <h1>For</h1> <p>The for task iterates over a list, a list of paths, or any type that has a public iterator() method. The list will be evaluated first. Nested paths are evaluated in the order they appear in the task. Nested types will then be evalulated. </p> <p> This task is the same as the <foreach> task, except that <ul> <li>it uses a nested sequential for each iteration; and <li>it implements an additional "keepgoing" attribute. </ul> <for> makes use of ant's macrodef task, so the @{} notation is used for parameter substition. </p> <p><em> This task only works for ant version greater than or equal to ant 1.6.0. </em> </p> <h2>Parameters</h2> <table border="1" cellpadding="2" cellspacing="0"> <tr> <th>Attribute</th> <th>Description</th> <th>Required</th> </tr> <tr> <td valign="top">list</td> <td valign="top">The list of values to process, with the delimiter character, indicated by the "delimiter" attribute, separating each value.</td> <td align="center" valign="top">Yes, unless a nested path has been specified.</td> </tr> <tr> <td valign="top">param</td> <td valign="top">Name of the parameter to pass the tokens or files in as to the sequential.</td> <td align="center" valign="top">Yes</td> </tr> <tr> <td valign="top">delimiter</td> <td valign="top">The delimiter characters that separates the values in the "list" attribute. Each character in the supplied string can act as a delimiter. This follows the semantics of the StringTokenizer class.</td> <td align="center" valign="top">No, defaults to ",".</td> </tr> <tr> <td valign="top">parallel</td> <td valign="top">If <code>true</code>, all iterations of the nested <sequential> will execute in parallel. Defaults to <code>false</code>, which forces sequential execution of the iterations. It is up to the caller to ensure that parallel execution is safe. <td align="center" valign="top">No</td> </tr> <tr> <td valign="top">keepgoing</td> <td valign="top">If <code>true</code>, all iterations of the called <sequential> will be executed, even if a task in one or more of them fails. Defaults to <code>false</code>, which forces execution to stop as soon as a task fails. At the end, if any iterator has failed, the <for> task will fail, otherwise <for> will succeed. <p> Note that execution does not proceed keepgoing from one task to the next within the <sequential>, but rather from one iteration to the next. </p> <p>It is up to the caller to ensure that keepgoing execution is safe.</p> </td> <td align="center" valign="top">No</td> </tr> <tr> <td valign="top">threadCount</td> <td valign="top">The maximum number of allowable threads when executing in parallel. <td align="center" valign="top">No. Defaults to 5.</td> </tr> <tr> <td valign="top">trim</td> <td valign="top">If <code>true</code>, any leading or trailing whitespace will be removed from the list item before it is passed to the sequential. </td> <td align="center" valign="top">No. Defaults to false.</td> </tr> </table> <h2>Parameters specified as nested elements</h2> <a name="path"><h3>path</h3></a> <p><a href="http://ant.apache.org/manual/using.html#path">Path</a>s are used to select sets of files or directories to iterate over.</p> <p>Using a path allows you to determine the order by which files are considered by using <a href="http://ant.apache.org/manual/CoreTypes/filelist.html">filelist</a>s or explicit <code>pathelements</code>. You also can specify whether you want to iterate over files or directories by chosing either filesets or <a href="http://ant.apache.org/manual/CoreTypes/dirset.html">dirset</a>s.</p> <a name="fileset"><h3>fileset</h3></a> <p><a href="http://ant.apache.org/manual/CoreTypes/fileset.html">FileSet</a>s are used to select sets of files to iterate over. </p> <a name="fileset"><h3>dirset</h3></a> <p><a href="http://ant.apache.org/manual/CoreTypes/dirset.html">DirSet</a>s are used to select sets of directories to iterate over. </p> <a name="seqential"><h3>sequential</h3></a> This is the list of tasks to be run for each iteration of the list. <h3>Example</h3> <p> To print out the first five letters of the latin alphabet: </p> <blockquote> <pre> <echo message="The first five letters of the alphabet are:"/> <for list="a,b,c,d,e" param="letter"> <sequential> <echo>Letter @{letter}</echo> </sequential> </for> </pre> </blockquote> <p> A more complicated example to to iterate over a set of c++ source files and invoke the <cc> task on them: </p> <blockquote> <pre> <for param="file"> <path> <fileset dir="${test.dir}/mains" includes="*.cpp"/> </path> <sequential> <propertyregex override="yes" property="program" input="@{file}" regexp=".*/([^\.]*)\.cpp" replace="\1"/> <mkdir dir="${obj.dir}/${program}"/> <mkdir dir="${build.bin.dir}"/> <cc link="executable" objdir="${obj.dir}/${program}" outfile="${build.bin.dir}/${program}"> <compiler refid="compiler.options"/> <fileset file="@{file}"/> <linker refid="linker-libs"/> </cc> </sequential> </for> </pre> </blockquote> The preceding example will stop as soon as one of the <cc> tasks fails. If you change the first line of the example to <pre> <for param="file" keepgoing="true"></pre> All iterations will be executed, and then <for> will fail if any one or more of the <cc> tasks failed. <p> The following example embeds an outofdate type and iterates over the sources that are newer than their corresponding targets. </p> <pre> <ac:for param="xmlfile" xmlns:ac="antlib:net.sf.antcontrib"> <ac:outofdate> <ac:sourcefiles> <ac:fileset dir="${basedir}/xdocs" includes="**/*.xml"/> </ac:sourcefiles> <ac:mapper dir="${basedir}/xdocs" type="glob" from="*.xml" to="${basedir}/docs/*.html"/> </ac:outofdate> <ac:sequential> <echo>Need to generate a target html file from source file @{xmlfile}</echo> </ac:sequential> </ac:for> </pre> <hr> <p align="center">Copyright © 2003-2005 Ant-Contrib Project. All rights Reserved.</p> </body> </html>