diff options
Diffstat (limited to 'docs/manual/tasks/for.html')
| -rw-r--r-- | docs/manual/tasks/for.html | 198 |
1 files changed, 198 insertions, 0 deletions
diff --git a/docs/manual/tasks/for.html b/docs/manual/tasks/for.html new file mode 100644 index 0000000..ecf23fe --- /dev/null +++ b/docs/manual/tasks/for.html @@ -0,0 +1,198 @@ +<!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> |