manual/properties.html - ant - Git at Google

 <!--
    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
 -->
 <html>

 <head>
   <meta http-equiv="Content-Language" content="en-us"/>
   <link rel="stylesheet" type="text/css" href="stylesheets/style.css"/>
   <title>Properties and PropertyHelpers</title>
 </head>

 <body>
   <h1>Properties</h1>

   <p>Properties are key-value-pairs where Apache Ant tries to
     expand <code>${key}</code> to <code>value</code> at runtime.</p>

   <p>There are many tasks that can set properties, the most common one
     is the <a href="Tasks/property.html">property</a> task.  In
     addition properties can be defined
     via <a href="running.html">command line arguments</a> or similar
     mechanisms from outside of Ant.</p>

   <p>Normally property values can not be changed, once a property is
     set, most tasks will not allow its value to be modified.  In
     general properties are of global scope, i.e. once they have been
     defined they are available for any task or target invoked
     subsequently - it is not possible to set a property in a child
     build process created via
     the <a href="Tasks/ant.html">ant</a>, antcall or subant tasks
     and make it available to the calling build process, though.</p>

   <p>Starting with Ant 1.8.0
     the <a href="Tasks/local.html">local</a> task can be used to
     create properties that are locally scoped to a target or
     a <a href="Tasks/sequential.html">sequential</a> element like
     the one of the <a href="Tasks/macrodef.html">macrodef</a>
     task.</p>

   <h2><a name="built-in-props">Built-in Properties</a></h2>

   <p>Ant provides access to all system properties as if they had been
     defined using a <code>&lt;property&gt;</code> task.  For
     example, <code>${os.name}</code> expands to the name of the
     operating system.</p>
   <p>For a list of system properties see
     <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/System.html#getProperties%28%29">the Javadoc of System.getProperties</a>.
   </p>

   <p>In addition, Ant has some built-in properties:</p>
 <pre><!-- TODO 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.
 ant.version         the version of Ant
 ant.project.name    the name of the project that is currently executing;
                     it is set in the name attribute of &lt;project&gt;.
 ant.project.default-target
                     the name of the currently executing project's
                     default target;  it is set via the default
                     attribute of &lt;project&gt;.
 ant.project.invoked-targets
                     a comma separated list of the targets that have
                     been specified on the command line (the IDE,
                     an &lt;ant&gt; task ...) when invoking the current
                     project.
                     This property is set properly when the first target is executed.
                     If you use it in the implicit target (directly
                     under the &lt;project&gt; tag) the list will be
                     empty if no target has been specified while it
                     will contain the project's default target in this
                     case for tasks nested into targets..
 ant.java.version    the JVM version Ant detected; currently it can hold
                     the values &quot;9&quot;, &quot;1.8&quot;,
                     &quot;1.7&quot;, &quot;1.6&quot;, &quot;1.5&quot;,
                     &quot;1.4&quot;, &quot;1.3&quot; and
                     &quot;1.2&quot;.
 ant.core.lib        the absolute path of the <code>ant.jar</code> file.
 </pre>

   <p>There is also another property, but this is set by the launcher
     script and therefore maybe not set inside IDEs:</p>
 <pre>
 ant.home            home directory of Ant
 </pre>

   <p>The following property is only set if Ant is started via the
     Launcher class (which means it may not be set inside IDEs
     either):</p>
 <pre>
 ant.library.dir     the directory that has been used to load Ant's
                     jars from.  In most cases this is ANT_HOME/lib.
 </pre>

   <h1><a name="propertyHelper">PropertyHelpers</a></h1>

   <p>Ant's property handling is accomplished by an instance of
     <code>org.apache.tools.ant.PropertyHelper</code> associated with
     the current Project.  You can learn more about this class by
     examining Ant's Java API. In Ant 1.8 the PropertyHelper class was
     much reworked and now itself employs a number of helper classes
     (actually instances of
     the <code>org.apache.tools.ant.PropertyHelper$Delegate</code>
     marker interface) to take care of discrete tasks such as property
     setting, retrieval, parsing, etc. This makes Ant's property
     handling highly extensible; also of interest is the
     new <a href="Tasks/propertyhelper.html">propertyhelper</a>
     task used to manipulate the PropertyHelper and its delegates from
     the context of the Ant buildfile.

   <p>There are three sub-interfaces of <code>Delegate</code> that may be
     useful to implement.</p>

   <ul>
     <li><code>org.apache.tools.ant.property.PropertyExpander</code> is
       responsible for finding the property name inside a string in the
       first place (the default extracts <code>foo</code>
       from <code>${foo}</code>).

       <p>This is the interface you'd implement if you wanted to invent
         your own property syntax - or allow nested property expansions
         since the default implementation doesn't balance braces
         (see <a href="https://git-wip-us.apache.org/repos/asf?p=ant-antlibs-props.git;a=blob;f=src/main/org/apache/ant/props/NestedPropertyExpander.java;hb=HEAD"><code>NestedPropertyExpander</code>
         in the "props" Antlib</a> for an example).</p>
     </li>

     <li><code>org.apache.tools.ant.PropertyHelper$PropertyEvaluator</code>
       is used to expand <code>${some-string}</code> into
       an <code>Object</code>.

       <p>This is the interface you'd implement if you want to provide
         your own storage independent of Ant's project instance - the
         interface represents the reading end.  An example for this
         would
         be <code>org.apache.tools.ant.property.LocalProperties</code>
         which implements storage
         for <a href="Tasks/local.html">local properties</a>.</p>

       <p>Another reason to implement this interface is if you wanted
         to provide your own "property protocol" like
         expanding <code>toString:foo</code> by looking up the project
         reference foo and invoking <code>toString()</code> on it
         (which is already implemented in Ant, see below).</p>
     </li>

     <li><code>org.apache.tools.ant.PropertyHelper$PropertySetter</code>
       is responsible for setting properties.

       <p>This is the interface you'd implement if you want to provide
         your own storage independent of Ant's project instance - the
         interface represents the reading end.  An example for this
         would
         be <code>org.apache.tools.ant.property.LocalProperties</code>
         which implements storage
         for <a href="Tasks/local.html">local properties</a>.</p>
     </li>

   </ul>

   <p>The default <code>PropertyExpander</code> looks similar to:</p>

 <pre>
 public class DefaultExpander implements PropertyExpander {
     public String parsePropertyName(String s, ParsePosition pos,
                                     ParseNextProperty notUsed) {
         int index = pos.getIndex();
         if (s.indexOf("${", index) == index) {
             int end = s.indexOf('}', index);
             if (end < 0) {
                 throw new BuildException("Syntax error in property: " + s);
             }
             int start = index + 2;
             pos.setIndex(end + 1);
             return s.substring(start, end);
         }
         return null;
     }
 }
 </pre>

   <p>The logic that replaces <code>${toString:some-id}</code> with the
     stringified representation of the object with
     id <code>some-id</code> inside the current build is contained in a
     PropertyEvaluator similar to the following code:</p>

 <pre>
 public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator {
     private static final String prefix = "toString:";
     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()));
         }
         return o == null ? null : o.toString();
     }
 }
 </pre>


   <h1>Property Expansion</h1>

   <p>When Ant encounters a construct <code>${some-text}</code> the
     exact parsing semantics are subject to the configured property
     helper delegates.</p>

   <h2><code>$$</code> Expansion</h2>

   <p>In its default configuration Ant will expand the
     text <code>$$</code> to a single <code>$</code> and suppress the
     normal property expansion mechanism for the text immediately
     following it, i.e. <code>$${key}</code> expands
     to <code>${key}</code> and not <code>value</code> even though a
     property named <code>key</code> was defined and had the
     value <code>value</code>.  This can be used to escape
     literal <code>$</code> characters and is useful in constructs that
     only look like property expansions or when you want to provide
     diagnostic output like in</p>

 <pre>  &lt;echo&gt;$${builddir}=${builddir}&lt;/echo&gt;</pre>

     <p>which will echo this message:</p>

 <pre>  ${builddir}=build/classes</pre>

   <p>if the property <code>builddir</code> has the
     value <code>build/classes</code>.</p>

   <p>In order to maintain backward compatibility with older Ant
     releases, a single '$' character encountered apart from a
     property-like construct (including a matched pair of french
     braces) will be interpreted literally; that is, as '$'.  The
     "correct" way to specify this literal character, however, is by
     using the escaping mechanism unconditionally, so that "$$" is
     obtained by specifying "$$$$".  Mixing the two approaches yields
     unpredictable results, as "$$$" results in "$$".</p>

   <h2>Nesting of Braces</h2>

   <p>In its default configuration Ant will not try to balance braces
     in property expansions, it will only consume the text up to the
     first closing brace when creating a property name.  I.e. when
     expanding something like <code>${a${b}}</code> it will be
     translated into two parts:</p>

   <ol>
     <li>the expansion of property <code>a${b</code> - likely nothing
       useful.</li>
     <li>the literal text <code>}</code> resulting from the second
       closing brace</li>
   </ol>

   <p>This means you can't use easily expand properties whose names are
     given by properties, but there
     are <a href="http://ant.apache.org/faq.html#propertyvalue-as-name-for-property">some
     workarounds</a> for older versions of Ant.  With Ant 1.8.0 and the
     <a href="http://ant.apache.org/antlib/props/">the props Antlib</a>
     you can configure Ant to use
     the <code>NestedPropertyExpander</code> defined there if you need
     such a feature.</p>

   <h2>Expanding a "Property Name"</h2>

   <p>In its most simple form <code>${key}</code> is supposed to look
     up a property named <code>key</code> and expand to the value of
     the property.  Additional <code>PropertyEvaluator</code>s may
     result in a different interpretation of <code>key</code>,
     though.</p>

   <p>The <a href="http://ant.apache.org/antlibs/props/">props
       Antlib</a> provides a few interesting evaluators but there are
       also a few built-in ones.</p>

   <h3><a name="toString">Getting the value of a Reference with
       ${toString:}</a></h3>

   <p>Any Ant type which has been declared with a reference can also
     its string value extracted by using the <code>${toString:}</code>
     operation, with the name of the reference listed after
     the <code>toString:</code> text.  The <code>toString()</code>
     method of the Java class instance that is referenced is invoked
     -all built in types strive to produce useful and relevant output
     in such an instance.</p>

   <p>For example, here is how to get a listing of the files in a fileset,<p>

 <pre>
 &lt;fileset id=&quot;sourcefiles&quot; dir=&quot;src&quot; includes=&quot;**/*.java&quot; /&gt;
 &lt;echo&gt; sourcefiles = ${toString:sourcefiles} &lt;/echo&gt;
 </pre>

   <p>There is no guarantee that external types provide meaningful
     information in such a situation</p>

   <h3><a name="ant.refid">Getting the value of a Reference with
       ${ant.refid:}</a></h3>

   <p>Any Ant type which has been declared with a reference can also be
     used as a property by using the <code>${ant.refid:}</code>
     operation, with the name of the reference listed after
     the <code>ant.refid:</code> text.  The difference between this
     operation and <a href="#toString"><code>${toString:}</code></a> is
     that <code>${ant.refid:}</code> will expand to the referenced
     object itself.  In most circumstances the toString method will be
     invoked anyway, for example if the <code>${ant.refid:}</code> is
     surrounded by other text.</p>

   <p>This syntax is most useful when using a task with attribute
     setters that accept objects other than String.  For example if the
     setter accepts a Resource object as in</p>
 <pre>
 public void setAttr(Resource r) { ... }
 </pre>

   <p>then the syntax can be used to pass in resource subclasses
     previously defined as references like</p>
 <pre>
   &lt;url url="http://ant.apache.org/" id="anturl"/&gt;
   &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;fail></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>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->
	<html>

	<head>
	<meta http-equiv="Content-Language" content="en-us"/>
	<link rel="stylesheet" type="text/css" href="stylesheets/style.css"/>
	<title>Properties and PropertyHelpers</title>
	</head>

	<body>
	<h1>Properties</h1>

	<p>Properties are key-value-pairs where Apache Ant tries to
	expand <code>${key}</code> to <code>value</code> at runtime.</p>

	<p>There are many tasks that can set properties, the most common one
	is the <a href="Tasks/property.html">property</a> task. In
	addition properties can be defined
	via <a href="running.html">command line arguments</a> or similar
	mechanisms from outside of Ant.</p>

	<p>Normally property values can not be changed, once a property is
	set, most tasks will not allow its value to be modified. In
	general properties are of global scope, i.e. once they have been
	defined they are available for any task or target invoked
	subsequently - it is not possible to set a property in a child
	build process created via
	the <a href="Tasks/ant.html">ant</a>, antcall or subant tasks
	and make it available to the calling build process, though.</p>

	<p>Starting with Ant 1.8.0
	the <a href="Tasks/local.html">local</a> task can be used to
	create properties that are locally scoped to a target or
	a <a href="Tasks/sequential.html">sequential</a> element like
	the one of the <a href="Tasks/macrodef.html">macrodef</a>
	task.</p>

	<h2><a name="built-in-props">Built-in Properties</a></h2>

	<p>Ant provides access to all system properties as if they had been
	defined using a <code><property></code> task. For
	example, <code>${os.name}</code> expands to the name of the
	operating system.</p>
	<p>For a list of system properties see
	<a href="http://docs.oracle.com/javase/7/docs/api/java/lang/System.html#getProperties%28%29">the Javadoc of System.getProperties</a>.
	</p>

	<p>In addition, Ant has some built-in properties:</p>
	<pre><!-- TODO 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.
	ant.version the version of Ant
	ant.project.name the name of the project that is currently executing;
	it is set in the name attribute of <project>.
	ant.project.default-target
	the name of the currently executing project's
	default target; it is set via the default
	attribute of <project>.
	ant.project.invoked-targets
	a comma separated list of the targets that have
	been specified on the command line (the IDE,
	an <ant> task ...) when invoking the current
	project.
	This property is set properly when the first target is executed.
	If you use it in the implicit target (directly
	under the <project> tag) the list will be
	empty if no target has been specified while it
	will contain the project's default target in this
	case for tasks nested into targets..
	ant.java.version the JVM version Ant detected; currently it can hold
	the values "9", "1.8",
	"1.7", "1.6", "1.5",
	"1.4", "1.3" and
	"1.2".
	ant.core.lib the absolute path of the <code>ant.jar</code> file.
	</pre>

	<p>There is also another property, but this is set by the launcher
	script and therefore maybe not set inside IDEs:</p>
	<pre>
	ant.home home directory of Ant
	</pre>

	<p>The following property is only set if Ant is started via the
	Launcher class (which means it may not be set inside IDEs
	either):</p>
	<pre>
	ant.library.dir the directory that has been used to load Ant's
	jars from. In most cases this is ANT_HOME/lib.
	</pre>

	<h1><a name="propertyHelper">PropertyHelpers</a></h1>

	<p>Ant's property handling is accomplished by an instance of
	<code>org.apache.tools.ant.PropertyHelper</code> associated with
	the current Project. You can learn more about this class by
	examining Ant's Java API. In Ant 1.8 the PropertyHelper class was
	much reworked and now itself employs a number of helper classes
	(actually instances of
	the <code>org.apache.tools.ant.PropertyHelper$Delegate</code>
	marker interface) to take care of discrete tasks such as property
	setting, retrieval, parsing, etc. This makes Ant's property
	handling highly extensible; also of interest is the
	new <a href="Tasks/propertyhelper.html">propertyhelper</a>
	task used to manipulate the PropertyHelper and its delegates from
	the context of the Ant buildfile.

	<p>There are three sub-interfaces of <code>Delegate</code> that may be
	useful to implement.</p>

	<ul>
	<li><code>org.apache.tools.ant.property.PropertyExpander</code> is
	responsible for finding the property name inside a string in the
	first place (the default extracts <code>foo</code>
	from <code>${foo}</code>).

	<p>This is the interface you'd implement if you wanted to invent
	your own property syntax - or allow nested property expansions
	since the default implementation doesn't balance braces
	(see <a href="https://git-wip-us.apache.org/repos/asf?p=ant-antlibs-props.git;a=blob;f=src/main/org/apache/ant/props/NestedPropertyExpander.java;hb=HEAD"><code>NestedPropertyExpander</code>
	in the "props" Antlib</a> for an example).</p>
	</li>

	<li><code>org.apache.tools.ant.PropertyHelper$PropertyEvaluator</code>
	is used to expand <code>${some-string}</code> into
	an <code>Object</code>.

	<p>This is the interface you'd implement if you want to provide
	your own storage independent of Ant's project instance - the
	interface represents the reading end. An example for this
	would
	be <code>org.apache.tools.ant.property.LocalProperties</code>
	which implements storage
	for <a href="Tasks/local.html">local properties</a>.</p>

	<p>Another reason to implement this interface is if you wanted
	to provide your own "property protocol" like
	expanding <code>toString:foo</code> by looking up the project
	reference foo and invoking <code>toString()</code> on it
	(which is already implemented in Ant, see below).</p>
	</li>

	<li><code>org.apache.tools.ant.PropertyHelper$PropertySetter</code>
	is responsible for setting properties.

	<p>This is the interface you'd implement if you want to provide
	your own storage independent of Ant's project instance - the
	interface represents the reading end. An example for this
	would
	be <code>org.apache.tools.ant.property.LocalProperties</code>
	which implements storage
	for <a href="Tasks/local.html">local properties</a>.</p>
	</li>

	</ul>

	<p>The default <code>PropertyExpander</code> looks similar to:</p>

	<pre>
	public class DefaultExpander implements PropertyExpander {
	public String parsePropertyName(String s, ParsePosition pos,
	ParseNextProperty notUsed) {
	int index = pos.getIndex();
	if (s.indexOf("${", index) == index) {
	int end = s.indexOf('}', index);
	if (end < 0) {
	throw new BuildException("Syntax error in property: " + s);
	}
	int start = index + 2;
	pos.setIndex(end + 1);
	return s.substring(start, end);
	}
	return null;
	}
	}
	</pre>

	<p>The logic that replaces <code>${toString:some-id}</code> with the
	stringified representation of the object with
	id <code>some-id</code> inside the current build is contained in a
	PropertyEvaluator similar to the following code:</p>

	<pre>
	public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator {
	private static final String prefix = "toString:";
	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()));
	}
	return o == null ? null : o.toString();
	}
	}
	</pre>


	<h1>Property Expansion</h1>

	<p>When Ant encounters a construct <code>${some-text}</code> the
	exact parsing semantics are subject to the configured property
	helper delegates.</p>

	<h2><code>$$</code> Expansion</h2>

	<p>In its default configuration Ant will expand the
	text <code>$$</code> to a single <code>$</code> and suppress the
	normal property expansion mechanism for the text immediately
	following it, i.e. <code>$${key}</code> expands
	to <code>${key}</code> and not <code>value</code> even though a
	property named <code>key</code> was defined and had the
	value <code>value</code>. This can be used to escape
	literal <code>$</code> characters and is useful in constructs that
	only look like property expansions or when you want to provide
	diagnostic output like in</p>

	<pre> <echo>$${builddir}=${builddir}</echo></pre>

	<p>which will echo this message:</p>

	<pre> ${builddir}=build/classes</pre>

	<p>if the property <code>builddir</code> has the
	value <code>build/classes</code>.</p>

	<p>In order to maintain backward compatibility with older Ant
	releases, a single '$' character encountered apart from a
	property-like construct (including a matched pair of french
	braces) will be interpreted literally; that is, as '$'. The
	"correct" way to specify this literal character, however, is by
	using the escaping mechanism unconditionally, so that "$$" is
	obtained by specifying "$$$$". Mixing the two approaches yields
	unpredictable results, as "$$$" results in "$$".</p>

	<h2>Nesting of Braces</h2>

	<p>In its default configuration Ant will not try to balance braces
	in property expansions, it will only consume the text up to the
	first closing brace when creating a property name. I.e. when
	expanding something like <code>${a${b}}</code> it will be
	translated into two parts:</p>

	<ol>
	<li>the expansion of property <code>a${b</code> - likely nothing
	useful.</li>
	<li>the literal text <code>}</code> resulting from the second
	closing brace</li>
	</ol>

	<p>This means you can't use easily expand properties whose names are
	given by properties, but there
	are <a href="http://ant.apache.org/faq.html#propertyvalue-as-name-for-property">some
	workarounds</a> for older versions of Ant. With Ant 1.8.0 and the
	<a href="http://ant.apache.org/antlib/props/">the props Antlib</a>
	you can configure Ant to use
	the <code>NestedPropertyExpander</code> defined there if you need
	such a feature.</p>

	<h2>Expanding a "Property Name"</h2>

	<p>In its most simple form <code>${key}</code> is supposed to look
	up a property named <code>key</code> and expand to the value of
	the property. Additional <code>PropertyEvaluator</code>s may
	result in a different interpretation of <code>key</code>,
	though.</p>

	<p>The <a href="http://ant.apache.org/antlibs/props/">props
	Antlib</a> provides a few interesting evaluators but there are
	also a few built-in ones.</p>

	<h3><a name="toString">Getting the value of a Reference with
	${toString:}</a></h3>

	<p>Any Ant type which has been declared with a reference can also
	its string value extracted by using the <code>${toString:}</code>
	operation, with the name of the reference listed after
	the <code>toString:</code> text. The <code>toString()</code>
	method of the Java class instance that is referenced is invoked
	-all built in types strive to produce useful and relevant output
	in such an instance.</p>

	<p>For example, here is how to get a listing of the files in a fileset,<p>

	<pre>
	<fileset id="sourcefiles" dir="src" includes="*/.java" />
	<echo> sourcefiles = ${toString:sourcefiles} </echo>
	</pre>

	<p>There is no guarantee that external types provide meaningful
	information in such a situation</p>

	<h3><a name="ant.refid">Getting the value of a Reference with
	${ant.refid:}</a></h3>

	<p>Any Ant type which has been declared with a reference can also be
	used as a property by using the <code>${ant.refid:}</code>
	operation, with the name of the reference listed after
	the <code>ant.refid:</code> text. The difference between this
	operation and <a href="#toString"><code>${toString:}</code></a> is
	that <code>${ant.refid:}</code> will expand to the referenced
	object itself. In most circumstances the toString method will be
	invoked anyway, for example if the <code>${ant.refid:}</code> is
	surrounded by other text.</p>

	<p>This syntax is most useful when using a task with attribute
	setters that accept objects other than String. For example if the
	setter accepts a Resource object as in</p>
	<pre>
	public void setAttr(Resource r) { ... }
	</pre>

	<p>then the syntax can be used to pass in resource subclasses
	previously defined as references like</p>
	<pre>
	<url url="http://ant.apache.org/" id="anturl"/>
	<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><fail></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>