| 1 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 5. If Task</title><meta name="generator" content="DocBook XSL Stylesheets V1.68.1"><link rel="start" href="index.html" title="Antelope Users Guide"><link rel="up" href="bk03.html" title="Additional Ant Tasks"><link rel="prev" href="bk03ch04.html" title="Chapter 4. Assert Task"><link rel="next" href="bk03ch05s02.html" title="More Conditions"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 5. If Task</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk03ch04.html">Prev</a> </td><th width="60%" align="center">Additional Ant Tasks</th><td width="20%" align="right"> <a accesskey="n" href="bk03ch05s02.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="IfTask"></a>Chapter 5. If Task</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="bk03ch05.html#id2519100">If</a></span></dt><dt><span class="section"><a href="bk03ch05s02.html">More Conditions</a></span></dt></dl></div>
|
|---|
| 2 | <STYLE TYPE="text/css"> <!-- @import url(./style.css); --> </STYLE>
|
|---|
| 3 | <div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2519100"></a>If</h2></div></div></div><p>
|
|---|
| 4 | The If task provides a greatly improved "if" capability to Ant projects. This task works in a manner very similar to the Java <code class="computeroutput">if</code> keyword. This is useful for performing certain tasks only if a property has a specific value or certain conditions are met.
|
|---|
| 5 | </p><p>
|
|---|
| 6 | This task can hold other tasks including the If task. In particular, it can also have a single "else", which gives Ant a Java-like if/else construct, and a single "bool", which can be used for the "if" boolean expression.
|
|---|
| 7 | </p><p>
|
|---|
| 8 | To use this task in your build files, include a task definition like this:
|
|---|
| 9 | </p><p>
|
|---|
| 10 | </p><pre class="programlisting">
|
|---|
| 11 |
|
|---|
| 12 | <taskdef name="if" classname="ise.antelope.tasks.IfTask"/>
|
|---|
| 13 |
|
|---|
| 14 | </pre><p>
|
|---|
| 15 | </p><p>
|
|---|
| 16 | An If task may contain only one 'bool' and one 'else' and may contain a 'break'. The 'bool' element is identical to the ConditionTask, but unlike the ConditionTask, is actually a Task. The 'bool' element can contain all the conditions permitted by the ConditionTask, plus the <a href="bk03ch05s02.html" title="More Conditions">IsPropertyTrue</a>, <a href="bk03ch05s02.html" title="More Conditions">IsPropertyFalse</a>,
|
|---|
| 17 | <a href="bk03ch05s02.html" title="More Conditions">StartsWith</a>,
|
|---|
| 18 | <a href="bk03ch05s02.html" title="More Conditions">EndsWith</a>,
|
|---|
| 19 | <a href="bk03ch05s02.html" title="More Conditions">IsGreaterThan</a>,
|
|---|
| 20 | <a href="bk03ch05s02.html" title="More Conditions">IsLessThan</a> and conditions.
|
|---|
| 21 | </p><p>
|
|---|
| 22 | Here is a general outline of the If task:
|
|---|
| 23 | </p><pre class="programlisting">
|
|---|
| 24 |
|
|---|
| 25 | <if>
|
|---|
| 26 | <bool>
|
|---|
| 27 | <some condition(s)/>
|
|---|
| 28 | </bool>
|
|---|
| 29 |
|
|---|
| 30 | some tasks...
|
|---|
| 31 |
|
|---|
| 32 | <!-- a break is allowed
|
|---|
| 33 | <break/>
|
|---|
| 34 | -->
|
|---|
| 35 |
|
|---|
| 36 | <else>
|
|---|
| 37 | some other tasks...
|
|---|
| 38 |
|
|---|
| 39 | <!-- a break is allowed
|
|---|
| 40 | <break/>
|
|---|
| 41 | -->
|
|---|
| 42 | </else>
|
|---|
| 43 | </if>
|
|---|
| 44 |
|
|---|
| 45 | </pre><p>
|
|---|
| 46 | </p><p>
|
|---|
| 47 |
|
|---|
| 48 | </p><div class="table"><a name="id2519204"></a><p class="title"><b>Table 5.1. If Task Attributes</b></p><table summary="If Task Attributes" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>Attribute</th><th>Description</th><th>Default</th><th>Required</th></tr></thead><tbody><tr><td>name</td><td>The name of the property to test for.</td><td>none</td><td>Yes, unless nested bool is used.</td></tr><tr><td>exists</td><td>Test for existence or non-existence of the property.</td><td>True</td><td>No</td></tr><tr><td>value</td><td>The value to test for, implies 'exists=true'. If the value for the property in the project is the same as this value, embedded tasks will be executed.</td><td>none</td><td>No</td></tr></tbody></table></div><p>
|
|---|
| 49 |
|
|---|
| 50 | </p><p>
|
|---|
| 51 | The If task can hold any number of Ant tasks. If the property value is correct or the "bool" element evaluates to true, these tasks will be executed.
|
|---|
| 52 | </p><p>
|
|---|
| 53 | In addition, the If task supports three special nested elements:
|
|---|
| 54 | </p><div class="itemizedlist"><ul type="disc"><li><p>
|
|---|
| 55 | <span class="bold"><strong>bool</strong></span> This is very similar to the standard Ant Condition task. All conditions supported by the Condition task are supported by the bool element. This is an optional element and if used, is used to decide if the "if" tasks or the "else" tasks should be executed. If the bool element is not used, then the "name" attribute must be used.
|
|---|
| 56 | </p></li><li><p>
|
|---|
| 57 | <span class="bold"><strong>else</strong></span> This is very similar to the standard Ant Sequential task. The "else" can hold any number of Ant tasks. These tasks are executed if the "bool" element evaluates to false.
|
|---|
| 58 | </p></li><li><p>
|
|---|
| 59 | <span class="bold"><strong>break</strong></span> This is very similar to the Java "break" keyword. This is only useful if the If task is nested in another task that understands "break", such as the <a href="bk03ch06.html" title="Chapter 6. SwitchTask">Switch</a> task. Like the Java "break", when this element is encountered, no subsequent tasks will be executed and control passes outside the If.
|
|---|
| 60 | </p></li></ul></div><p>
|
|---|
| 61 | In the following example, the <code class="computeroutput">antcall</code> task will execute only if the project has a property named <code class="computeroutput">test</code> with a value of <code class="computeroutput">true</code>.
|
|---|
| 62 | </p><p>
|
|---|
| 63 | </p><pre class="programlisting">
|
|---|
| 64 |
|
|---|
| 65 | <if name="test" value="true">
|
|---|
| 66 | <antcall target="doUnitTests"/>
|
|---|
| 67 | </if>
|
|---|
| 68 |
|
|---|
| 69 | </pre><p>
|
|---|
| 70 | </p><p>
|
|---|
| 71 | In the next example, the <code class="computeroutput">antcall</code> task will execute only if the project has a property named <code class="computeroutput">test</code>. In this example, it does not matter what value is assigned to the <code class="computeroutput">test</code> property.
|
|---|
| 72 | </p><p>
|
|---|
| 73 | </p><pre class="programlisting">
|
|---|
| 74 |
|
|---|
| 75 | <if name="test">
|
|---|
| 76 | <antcall target="doUnitTests"/>
|
|---|
| 77 | </if>
|
|---|
| 78 |
|
|---|
| 79 | </pre><p>
|
|---|
| 80 | </p><p>
|
|---|
| 81 | Of course, the same thing could have been done as follows, but the "if" is generally much cleaner.
|
|---|
| 82 | </p><pre class="programlisting">
|
|---|
| 83 |
|
|---|
| 84 | <antcall target="doUnitTests"/>
|
|---|
| 85 | <target name="doUnitTests" if="test">
|
|---|
| 86 | ...
|
|---|
| 87 | </target>
|
|---|
| 88 |
|
|---|
| 89 | </pre><p>
|
|---|
| 90 | </p><p>
|
|---|
| 91 | In the next example, the <code class="computeroutput">antcall</code> task will execute only if the project does not have a property named <code class="computeroutput">test</code>. This is the opposite situation of the previous example.
|
|---|
| 92 | </p><p>
|
|---|
| 93 | </p><pre class="programlisting">
|
|---|
| 94 |
|
|---|
| 95 | <if name="test" exists="false">
|
|---|
| 96 | <antcall target="doUnitTests"/>
|
|---|
| 97 | </if>
|
|---|
| 98 |
|
|---|
| 99 | </pre><p>
|
|---|
| 100 | </p><p>
|
|---|
| 101 | The next example demonstrates nested 'if' tasks. This example will run the unit tests, and if it is Monday, will publish the accumulated test results.
|
|---|
| 102 | </p><p>
|
|---|
| 103 | </p><pre class="programlisting">
|
|---|
| 104 |
|
|---|
| 105 | <tstamp>
|
|---|
| 106 | <format property="day" pattern="E" />
|
|---|
| 107 | </tstamp>
|
|---|
| 108 | <if name="test" value="true">
|
|---|
| 109 | <antcall target="doUnitTests"/>
|
|---|
| 110 | <if name="day" value="Mon">
|
|---|
| 111 | <antcall target="publishTestResults"/>
|
|---|
| 112 | </if>
|
|---|
| 113 | </if>
|
|---|
| 114 |
|
|---|
| 115 | </pre><p>
|
|---|
| 116 | </p><p>
|
|---|
| 117 | The next example shows how to use If with Else. Notice that it doesn't matter where the Else is placed inside the If. All tasks in the If that are not in the Else will execute if the property value is correct, otherwise, only those tasks inside the else will execute. The "var" task is discussed <a href="bk03ch09.html" title="Chapter 9. Variable Task">here</a>.
|
|---|
| 118 | </p><p>
|
|---|
| 119 | </p><pre class="programlisting">
|
|---|
| 120 |
|
|---|
| 121 | <var name="foo" value="bar"/>
|
|---|
| 122 | <if name="foo" value="bar">
|
|---|
| 123 | <echo>this will happen</echo>
|
|---|
| 124 | <else>
|
|---|
| 125 | <echo>this won't happen</echo>
|
|---|
| 126 | </else>
|
|---|
| 127 | <echo>this will happen also</echo>
|
|---|
| 128 | </if>
|
|---|
| 129 |
|
|---|
| 130 | <if name="foo" value="snarf">
|
|---|
| 131 | <echo>this won't happen</echo>
|
|---|
| 132 | <else>
|
|---|
| 133 | <echo>this 'else' will happen</echo>
|
|---|
| 134 | <echo>and so will this</echo>
|
|---|
| 135 | </else>
|
|---|
| 136 | <echo>this won't happen either</echo>
|
|---|
| 137 | </if>
|
|---|
| 138 |
|
|---|
| 139 | </pre><p>
|
|---|
| 140 | </p><p>
|
|---|
| 141 | The next example shows the "if" and "assert" tasks working together to validate a property before use, and also shows an example of where the "assert" 'failonerror' attribute might be useful. In this example, if the e-mail address is invalid, the e-mail won't be sent and the build won't fail. The "try" task is discussed <a href="bk03ch07.html" title="Chapter 7. Try Task">here</a>.
|
|---|
| 142 | </p><p>
|
|---|
| 143 | </p><pre class="programlisting">
|
|---|
| 144 |
|
|---|
| 145 | <if name="email_from" value="[email protected]">
|
|---|
| 146 | <property name="valid_email" value="true"/>
|
|---|
| 147 | </if>
|
|---|
| 148 | <if name="email_from" value="[email protected]">
|
|---|
| 149 | <property name="valid_email" value="true"/>
|
|---|
| 150 | </if>
|
|---|
| 151 | <assert name="valid_email" value="true" failonerror="false">
|
|---|
| 152 | <try>
|
|---|
| 153 | <mail from="${email_from}" tolist="${email_to}"
|
|---|
| 154 | message="New release available"/>
|
|---|
| 155 | </try>
|
|---|
| 156 | </assert>
|
|---|
| 157 |
|
|---|
| 158 | </pre><p>
|
|---|
| 159 | </p><p>
|
|---|
| 160 | Here is the same thing, but using only If and Else:
|
|---|
| 161 | </p><p>
|
|---|
| 162 | </p><pre class="programlisting">
|
|---|
| 163 |
|
|---|
| 164 | <try>
|
|---|
| 165 | <if name="email_from" value="[email protected]">
|
|---|
| 166 | <mail from="${email_from}" tolist="${email_to}"
|
|---|
| 167 | message="New release available"/>
|
|---|
| 168 | <else>
|
|---|
| 169 | <if name="email_from" value="[email protected]">
|
|---|
| 170 | <mail from="${email_from}" tolist="${email_to}"
|
|---|
| 171 | message="New release available"/>
|
|---|
| 172 | </if>
|
|---|
| 173 | </else>
|
|---|
| 174 | </if>
|
|---|
| 175 | </try>
|
|---|
| 176 |
|
|---|
| 177 | </pre><p>
|
|---|
| 178 | </p><p>
|
|---|
| 179 | The next example shows how to use the "bool" element:
|
|---|
| 180 | </p><p>
|
|---|
| 181 | </p><pre class="programlisting">
|
|---|
| 182 |
|
|---|
| 183 | <if>
|
|---|
| 184 | <!-- "if" evaluates this element -->
|
|---|
| 185 | <bool>
|
|---|
| 186 | <and>
|
|---|
| 187 | <available file="build.xml"/>
|
|---|
| 188 | <available file="run.xml"/>
|
|---|
| 189 | </and>
|
|---|
| 190 | </bool>
|
|---|
| 191 |
|
|---|
| 192 | <!-- if true, then tasks listed here will execute -->
|
|---|
| 193 | <echo>build.xml and run.xml are available</echo>
|
|---|
| 194 |
|
|---|
| 195 | <!-- if false, then tasks inside the "else" will execute -->
|
|---|
| 196 | <else>
|
|---|
| 197 | <echo>didn't find one or both of build.xml and run.xml</echo>
|
|---|
| 198 | </else>
|
|---|
| 199 | </if>
|
|---|
| 200 |
|
|---|
| 201 | </pre><p>
|
|---|
| 202 | </p><p>
|
|---|
| 203 | The following example shows the "bool" element again:
|
|---|
| 204 | </p><p>
|
|---|
| 205 | </p><pre class="programlisting">
|
|---|
| 206 |
|
|---|
| 207 | <if>
|
|---|
| 208 | <bool>
|
|---|
| 209 | <equals arg1="${download.dir}" arg2="test.dir"/>
|
|---|
| 210 | </bool>
|
|---|
| 211 |
|
|---|
| 212 | <fail message="Download and test directories cannot be
|
|---|
| 213 | the same! You need to reset to use the production
|
|---|
| 214 | property set."/>
|
|---|
| 215 |
|
|---|
| 216 | <else>
|
|---|
| 217 | <copy file="installer.zip" todir="${download.dir}"/>
|
|---|
| 218 | </else>
|
|---|
| 219 | </if>
|
|---|
| 220 |
|
|---|
| 221 | </pre><p>
|
|---|
| 222 | </p><p>
|
|---|
| 223 | The following example is from the unit test for the "Limit" task. It shows the Stopwatch task, the Limit task, and the If task with boolean conditions:
|
|---|
| 224 | </p><p>
|
|---|
| 225 | </p><pre class="programlisting">
|
|---|
| 226 |
|
|---|
| 227 | <target name="test2">
|
|---|
| 228 | <!-- should not stop 'sleep' task, should print out '_passed_' -->
|
|---|
| 229 | <stopwatch name="timer"/>
|
|---|
| 230 | <limit maxwait="5">
|
|---|
| 231 | <sleep seconds="1"/>
|
|---|
| 232 | <echo>_passed_</echo>
|
|---|
| 233 | </limit>
|
|---|
| 234 | <stopwatch name="timer" action="total"/>
|
|---|
| 235 | <if>
|
|---|
| 236 | <bool>
|
|---|
| 237 | <isgreaterthan arg1="${timer}" arg2="2"/>
|
|---|
| 238 | </bool>
|
|---|
| 239 | <fail message="Too much time"/>
|
|---|
| 240 | </if>
|
|---|
| 241 | </target>
|
|---|
| 242 |
|
|---|
| 243 | </pre><p>
|
|---|
| 244 | </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk03ch04.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk03.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk03ch05s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 4. Assert Task </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> More Conditions</td></tr></table></div></body></html>
|
|---|
