Documenting new if/unless behavior.

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@832936 13f79535-47bb-0310-9956-ffa450edef68

docs/manual/CoreTasks/fail.html

@@ -44,14 +44,14 @@ or character data nested into the element.</p>
   </tr>
   <tr>
     <td valign="top">if</td>
-    <td valign="top">Only fail if a property of the given name exists
+    <td valign="top">Only fail <a href="../properties.html#if+unless">if a property of the given name exists</a>
       in the current project</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">unless</td>
-    <td valign="top">Only fail if a property of the given name doesn't
-      exist in the current project</td>
+    <td valign="top">Only fail <a href="../properties.html#if+unless">if a property of the given name doesn't
+      exist</a> in the current project</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>

docs/manual/CoreTasks/style.html

@@ -301,12 +301,12 @@ element is used to perform Entity and URI resolution.</p>
   </tr>
   <tr>
     <td valign="top">if</td>
-    <td valign="top">The param will only passed if this property is set.</td>
+    <td valign="top">The param will only be passed <a href="../properties.html#if+unless">if this property is set</a>.</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">unless</td>
-    <td valign="top">The param will only passed unless this property is set.</td>
+    <td valign="top">The param will not be passed <a href="../properties.html#if+unless">if this property is set</a>.</td>
     <td align="center" valign="top">No</td>
   </tr>
 

docs/manual/CoreTypes/patternset.html

@@ -82,13 +82,13 @@ exclude.</p>
   </tr>
   <tr>
     <td valign="top">if</td>
-    <td valign="top">Only use this pattern if the named property is set.</td>
+    <td valign="top">Only use this pattern <a href="../properties.html#if+unless">if the named property is set</a>.</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">unless</td>
-    <td valign="top">Only use this pattern if the named property is
-       <b>not</b> set.</td>
+    <td valign="top">Only use this pattern <a href="../properties.html#if+unless">if the named property is
+       <b>not</b> set</a>.</td>
     <td align="center" valign="top">No</td>
   </tr>
 </table>
@@ -113,13 +113,13 @@ you can use to test the existance of a property.</p>
   </tr>
   <tr>
     <td valign="top">if</td>
-    <td valign="top">Only read this file if the named property is set.</td>
+    <td valign="top">Only read this file <a href="../properties.html#if+unless">if the named property is set</a>.</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">unless</td>
-    <td valign="top">Only read this file if the named property is
-      <b>not</b> set.</td>
+    <td valign="top">Only read this file <a href="../properties.html#if+unless">if the named property is
+      <b>not</b> set</a>.</td>
     <td align="center" valign="top">No</td>
   </tr>
 </table>

docs/manual/CoreTypes/selectors.html

@@ -1380,15 +1380,15 @@ Select files whose filename length is even.
       </tr>
       <tr>
         <td valign="top">if</td>
-        <td valign="top">Allow files to be selected only if the named
-          property is set.
+        <td valign="top">Allow files to be selected only <a href="../properties.html#if+unless">if the named
+          property is set</a>.
         </td>
         <td valign="top" align="center">No</td>
       </tr>
       <tr>
         <td valign="top">unless</td>
-        <td valign="top">Allow files to be selected only if the named
-          property is <b>not</b> set.
+        <td valign="top">Allow files to be selected only <a href="../properties.html#if+unless">if the named
+          property is <b>not</b> set</a>.
         </td>
         <td valign="top" align="center">No</td>
       </tr>

docs/manual/OptionalTasks/junit.html

@@ -414,12 +414,12 @@ time.</p>
   </tr>
   <tr>
     <td valign="top">if</td>
-    <td valign="top">Only use formatter if the named property is set.</td>
+    <td valign="top">Only use formatter <a href="../properties.html#if+unless">if the named property is set</a>.</td>
     <td align="center">No; default is <code>true</code>.</td>
   </tr>
   <tr>
     <td valign="top">unless</td>
-    <td valign="top">Only use formatter if the named property is <b>not</b> set.</td>
+    <td valign="top">Only use formatter <a href="../properties.html#if+unless">if the named property is <b>not</b> set</a>.</td>
     <td align="center">No; default is <code>true</code>.</td>
   </tr>  
 </table>
@@ -493,12 +493,12 @@ time.</p>
   </tr>
   <tr>
     <td valign="top">if</td>
-    <td valign="top">Only run test if the named property is set.</td>
+    <td valign="top">Only run test <a href="../properties.html#if+unless">if the named property is set</a>.</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">unless</td>
-    <td valign="top">Only run test if the named property is <b>not</b> set.</td>
+    <td valign="top">Only run test <a href="../properties.html#if+unless">if the named property is <b>not</b> set</a>.</td>
     <td align="center" valign="top">No</td>
   </tr>
 </table>
@@ -571,12 +571,12 @@ supported.</p>
   </tr>
   <tr>
     <td valign="top">if</td>
-    <td valign="top">Only run tests if the named property is set.</td>
+    <td valign="top">Only run tests <a href="../properties.html#if+unless">if the named property is set</a>.</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">unless</td>
-    <td valign="top">Only run tests if the named property is <strong>not</strong> set.</td>
+    <td valign="top">Only run tests <a href="../properties.html#if+unless">if the named property is <strong>not</strong> set</a>.</td>
     <td align="center" valign="top">No</td>
   </tr>
 </table>

docs/manual/OptionalTasks/junitreport.html

@@ -143,12 +143,12 @@ These tags can pass XSL parameters to the stylesheet.
   </tr>
   <tr>
     <td valign="top">if</td>
-    <td valign="top">The param will only passed if this property is set.</td>
+    <td valign="top">The param will only be passed <a href="../properties.html#if+unless">if this property is set</a>.</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">unless</td>
-    <td valign="top">The param will only passed unless this property is set.</td>
+    <td valign="top">The param will not be passed <a href="../properties.html#if+unless">if this property is set</a>.</td>
     <td align="center" valign="top">No</td>
   </tr>
 </table>

docs/manual/properties.html

@@ -61,7 +61,7 @@
   </p>
 
   <p>In addition, Ant has some built-in properties:</p>
-<pre>
+<pre><!-- XXX use <dl><dt><code>...</code></dt><dd>...</dd></dl> instead -->
 basedir             the absolute path of the project's basedir (as set
                     with the basedir attribute of <a href="using.html#projects">&lt;project&gt;</a>).
 ant.file            the absolute path of the buildfile.
@@ -194,7 +194,8 @@ public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator {
     public Object evaluate(String property, PropertyHelper propertyHelper) {
         Object o = null;
         if (property.startsWith(prefix) && propertyHelper.getProject() != null) {
-            o = propertyHelper.getProject().getReference(property.substring(prefix.length()));
+            o = propertyHelper.getProject().getReference(
+                    property.substring(prefix.length()));
         }
         return o == null ? null : o.toString();
     }
@@ -323,4 +324,73 @@ public void setAttr(Resource r) { ... }
   &lt;my:task attr="${ant.refid:anturl}"/&gt;
 </pre>
 
+  <h2><a name="if+unless">If/Unless Attributes</a></h2>
+  <p>
+      The <code>&lt;target></code> element and various tasks (such as
+      <code>&lt;exit></code>) and task elements (such as <code>&lt;test></code>
+      in <code>&lt;junit></code>) support <code>if</code> and <code>unless</code>
+      attributes which can be used to control whether the item is run or otherwise
+      takes effect.
+  </p>
+  <p>
+      In Ant 1.7.1 and earlier, these attributes could only be property names.
+      The item was enabled if a property with that name was defined - even to be
+      the empty string or <tt>false</tt> - and disabled if the property was not
+      defined. For example, the following works but there is no way to override
+      the file existence check negatively (only positively):
+  </p>
+  <pre>
+&lt;target name="-check-use-file">
+    &lt;available property="file.exists" file="some-file"/>
+&lt;/target>
+&lt;target name="use-file" depends="-check-use-file" <b>if="file.exists"</b>>
+    &lt;!-- do something requiring that file... -->
+&lt;/target>
+&lt;target name="lots-of-stuff" depends="use-file,other-unconditional-stuff"/>
+  </pre>
+  <p>
+      As of Ant 1.8.0, you may instead use property expansion; a value of
+      <tt>true</tt> (or <tt>on</tt> or <tt>yes</tt>) will enable the
+      item, while <tt>false</tt> (or <tt>off</tt> or <tt>no</tt>) will
+      disable it. Other values are still assumed to be property
+      names and so the item is enabled only if the named property is defined.
+  </p>
+  <p>
+      Compared to the older style, this gives you additional flexibility, because
+      you can override the condition from the command line or parent scripts:
+  </p>
+  <pre>
+&lt;target name="-check-use-file" <b>unless="file.exists"</b>>
+    &lt;available property="file.exists" file="some-file"/>
+&lt;/target>
+&lt;target name="use-file" depends="-check-use-file" <b>if="${file.exists}"</b>>
+    &lt;!-- do something requiring that file... -->
+&lt;/target>
+&lt;target name="lots-of-stuff" depends="use-file,other-unconditional-stuff"/>
+  </pre>
+  <p>
+      Now <code>ant -Dfile.exists=false lots-of-stuff</code> will run
+      <code>other-unconditional-stuff</code> but not <code>use-file</code>,
+      as you might expect, and you can disable the condition from another script
+      too:
+  </p>
+  <pre>
+&lt;antcall target="lots-of-stuff">
+    &lt;param name="file.exists" value="false"/>
+&lt;/antcall>
+  </pre>
+  <p>
+      Similarly, an <code>unless</code> attribute disables the item if it is
+      either the name of property which is defined, or if it evaluates to a
+      <tt>true</tt>-like value. For example, the following allows you to define
+      <tt>skip.printing.message=true</tt> in <tt>my-prefs.properties</tt> with
+      the results you might expect:
+  </p>
+  <pre>
+&lt;property file="my-prefs.properties"/>
+&lt;target name="print-message" <b>unless="${skip.printing.message}"</b>>
+    &lt;echo>hello!&lt;/echo>
+&lt;/target>
+  </pre>
+
 </body>

docs/manual/using.html

@@ -188,13 +188,13 @@ executed first.</p>
   <tr>
     <td valign="top">if</td>
     <td valign="top">the name of the property that must be set in order for this
-      target to execute.</td>
+      target to execute, or <a href="properties.html#if+unless">something evaluating to true</a>.</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">unless</td>
     <td valign="top">the name of the property that must not be set in order
-      for this target to execute.</td>
+      for this target to execute, or <a href="properties.html#if+unless">something evaluating to false</a>.</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>