<!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" rowspan="2">Yes, one of these need to
be set, unless a nested path
has been specified.</td>
</tr>
<tr>
<td valign="top">end</td>
<td valign="top">
Sets the ending index value. If this attribute is
set, the <for> task will loop from "start" (default 1)
to "end", using "step" (default 1) increments.
</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>
<tr>
<td valign="top">begin</td>
<td valign="top">
Sets the starting index value. This in only used
if the "end" attribute is set.
</td>
<td align="center" valign="top">No. Defaults to "1".</td>
</tr>
<tr>
<td valign="top">step</td>
<td valign="top">
Sets the index increment step.
This in only used if the "end" attribute is set.
</td>
<td align="center" valign="top">No. Defaults to "1".</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>
<p>
The following example loops from one to ten.
</p>
<pre>
<ac:for param="i" end="10">
<sequential>
<echo>i is @{i}</echo>
</sequential>
</ac:for>
</pre>
<p>
The following example counts down from 10 to 0 in steps of -2.
</p>
<pre>
<ac:for param="i" begin="10" step="-2" end="0">
<sequential>
<echo>i is @{i}</echo>
</sequential>
</ac:for>
</pre>
<hr>
<p align="center">Copyright © 2003-2006 Ant-Contrib Project. All
rights Reserved.</p>
</body>
</html>
distrib
>
Mageia
>
5
>
x86_64
>
media
>
core-release
>
by-pkgid
>
19826efc07ba2a4745cb9bf8f6723e88
>
files
>
10
