ant-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jgl...@apache.org
Subject svn commit: r832936 - in /ant/core/trunk/docs/manual: CoreTasks/fail.html CoreTasks/style.html CoreTypes/patternset.html CoreTypes/selectors.html OptionalTasks/junit.html OptionalTasks/junitreport.html properties.html using.html
Date Thu, 05 Nov 2009 00:45:05 GMT
Author: jglick
Date: Thu Nov  5 00:45:05 2009
New Revision: 832936

URL: http://svn.apache.org/viewvc?rev=832936&view=rev
Log:
Documenting new if/unless behavior.

Modified:
    ant/core/trunk/docs/manual/CoreTasks/fail.html
    ant/core/trunk/docs/manual/CoreTasks/style.html
    ant/core/trunk/docs/manual/CoreTypes/patternset.html
    ant/core/trunk/docs/manual/CoreTypes/selectors.html
    ant/core/trunk/docs/manual/OptionalTasks/junit.html
    ant/core/trunk/docs/manual/OptionalTasks/junitreport.html
    ant/core/trunk/docs/manual/properties.html
    ant/core/trunk/docs/manual/using.html

Modified: ant/core/trunk/docs/manual/CoreTasks/fail.html
URL: http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/CoreTasks/fail.html?rev=832936&r1=832935&r2=832936&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/CoreTasks/fail.html (original)
+++ ant/core/trunk/docs/manual/CoreTasks/fail.html Thu Nov  5 00:45:05 2009
@@ -44,14 +44,14 @@
   </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>

Modified: ant/core/trunk/docs/manual/CoreTasks/style.html
URL: http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/CoreTasks/style.html?rev=832936&r1=832935&r2=832936&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/CoreTasks/style.html (original)
+++ ant/core/trunk/docs/manual/CoreTasks/style.html Thu Nov  5 00:45:05 2009
@@ -301,12 +301,12 @@
   </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>
 

Modified: ant/core/trunk/docs/manual/CoreTypes/patternset.html
URL: http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/CoreTypes/patternset.html?rev=832936&r1=832935&r2=832936&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/CoreTypes/patternset.html (original)
+++ ant/core/trunk/docs/manual/CoreTypes/patternset.html Thu Nov  5 00:45:05 2009
@@ -82,13 +82,13 @@
   </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 @@
   </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>

Modified: ant/core/trunk/docs/manual/CoreTypes/selectors.html
URL: http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/CoreTypes/selectors.html?rev=832936&r1=832935&r2=832936&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/CoreTypes/selectors.html (original)
+++ ant/core/trunk/docs/manual/CoreTypes/selectors.html Thu Nov  5 00:45:05 2009
@@ -1380,15 +1380,15 @@
       </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>

Modified: ant/core/trunk/docs/manual/OptionalTasks/junit.html
URL: http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/OptionalTasks/junit.html?rev=832936&r1=832935&r2=832936&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/OptionalTasks/junit.html (original)
+++ ant/core/trunk/docs/manual/OptionalTasks/junit.html Thu Nov  5 00:45:05 2009
@@ -414,12 +414,12 @@
   </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 @@
   </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 @@
   </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>

Modified: ant/core/trunk/docs/manual/OptionalTasks/junitreport.html
URL: http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/OptionalTasks/junitreport.html?rev=832936&r1=832935&r2=832936&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/OptionalTasks/junitreport.html (original)
+++ ant/core/trunk/docs/manual/OptionalTasks/junitreport.html Thu Nov  5 00:45:05 2009
@@ -143,12 +143,12 @@
   </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>

Modified: ant/core/trunk/docs/manual/properties.html
URL: http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/properties.html?rev=832936&r1=832935&r2=832936&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/properties.html (original)
+++ ant/core/trunk/docs/manual/properties.html Thu Nov  5 00:45:05 2009
@@ -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 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 @@
   &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>

Modified: ant/core/trunk/docs/manual/using.html
URL: http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/using.html?rev=832936&r1=832935&r2=832936&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/using.html (original)
+++ ant/core/trunk/docs/manual/using.html Thu Nov  5 00:45:05 2009
@@ -188,13 +188,13 @@
   <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>



Mime
View raw message