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"><project></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 @@
<my:task attr="${ant.refid:anturl}"/>
</pre>
+ <h2><a name="if+unless">If/Unless Attributes</a></h2>
+ <p>
+ The <code><target></code> element and various tasks (such as
+ <code><exit></code>) and task elements (such as <code><test></code>
+ in <code><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>
+<target name="-check-use-file">
+ <available property="file.exists" file="some-file"/>
+</target>
+<target name="use-file" depends="-check-use-file" <b>if="file.exists"</b>>
+ <!-- do something requiring that file... -->
+</target>
+<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>
+<target name="-check-use-file" <b>unless="file.exists"</b>>
+ <available property="file.exists" file="some-file"/>
+</target>
+<target name="use-file" depends="-check-use-file"
<b>if="${file.exists}"</b>>
+ <!-- do something requiring that file... -->
+</target>
+<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>
+<antcall target="lots-of-stuff">
+ <param name="file.exists" value="false"/>
+</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>
+<property file="my-prefs.properties"/>
+<target name="print-message" <b>unless="${skip.printing.message}"</b>>
+ <echo>hello!</echo>
+</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>
