Author: bodewig
Date: Wed Oct 21 20:39:57 2009
New Revision: 828198
URL: http://svn.apache.org/viewvc?rev=828198&view=rev
Log:
extract and expand property documentation
Added:
ant/core/trunk/docs/manual/properties.html (with props)
Modified:
ant/core/trunk/docs/manual/CoreTasks/property.html
ant/core/trunk/docs/manual/CoreTasks/propertyhelper.html
ant/core/trunk/docs/manual/conceptstypeslist.html
ant/core/trunk/docs/manual/tutorial-tasks-filesets-properties.html
ant/core/trunk/docs/manual/tutorial-writing-tasks.html
ant/core/trunk/docs/manual/using.html
ant/core/trunk/docs/manual/usinglist.html
Modified: ant/core/trunk/docs/manual/CoreTasks/property.html
URL:
http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/CoreTasks/property.html?rev=828198&r1=828197&r2=828198&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/CoreTasks/property.html (original)
+++ ant/core/trunk/docs/manual/CoreTasks/property.html Wed Oct 21 20:39:57 2009
@@ -57,7 +57,7 @@
properties. These references are resolved at the time these properties are set.
This also holds for properties loaded from a property file.</p>
<p>A list of predefined properties can be found <a
-href="../using.html#built-in-props">here</a>.</p>
+href="../properties.html#built-in-props">here</a>.</p>
<p>Since Ant 1.7.1 it is possible to load properties defined in xml
according to <a href="http://java.sun.com/dtd/properties.dtd";>Suns DTD</a>,
if Java5+ is present. For this the name of the file, resource or url has
Modified: ant/core/trunk/docs/manual/CoreTasks/propertyhelper.html
URL:
http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/CoreTasks/propertyhelper.html?rev=828198&r1=828197&r2=828198&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/CoreTasks/propertyhelper.html (original)
+++ ant/core/trunk/docs/manual/CoreTasks/propertyhelper.html Wed Oct 21
20:39:57 2009
@@ -31,7 +31,7 @@
<b>(b)</b> (hopefully more often) install one or more PropertyHelper Delegates
into the
PropertyHelper active on the current Project. This is somewhat advanced Ant
usage and
assumes a working familiarity with the modern Ant APIs. See the description of
Ant's
-<a href="../using.html#propertyHelper">Property Helper</a> for more
information.
+<a href="../properties.html#propertyHelper">Property Helper</a> for more
information.
<b>Since Ant 1.8.0</b></p>
<h3>Parameters specified as nested elements</h3>
Modified: ant/core/trunk/docs/manual/conceptstypeslist.html
URL:
http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/conceptstypeslist.html?rev=828198&r1=828197&r2=828198&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/conceptstypeslist.html (original)
+++ ant/core/trunk/docs/manual/conceptstypeslist.html Wed Oct 21 20:39:57 2009
@@ -28,6 +28,7 @@
<h2><a href="toc.html" target="navFrame">Table of Contents</a></h2>
<h3>Concepts</h3>
+<a href="properties.html">Properties and PropertyHelpers</a>
<a href="clonevm.html">ant.build.clonevm</a><br/>
<a href="sysclasspath.html">build.sysclasspath</a><br/>
<a href="javacprops.html">Ant properties controlling javac</a><br/>
Added: ant/core/trunk/docs/manual/properties.html
URL:
http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/properties.html?rev=828198&view=auto
==============================================================================
--- ant/core/trunk/docs/manual/properties.html (added)
+++ ant/core/trunk/docs/manual/properties.html Wed Oct 21 20:39:57 2009
@@ -0,0 +1,326 @@
+<!--
+ 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 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="CoreTasks/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="CoreTasks/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="CoreTasks/local.html">local</a> task can be used to
+ create properties that are locally scoped to a target or
+ a <a href="CoreTasks/sequential.html">sequential</a> element like
+ the one of the <a href="CoreTasks/macrodef.html">macrodef</a>
+ task.</p>
+
+ <a name="built-in-props"><h2>Built-in Properties</h2></a>
+
+ <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://java.sun.com/j2se/1.3/docs/api/java/lang/System.html#getProperties()">the
Javadoc of System.getProperties</a>.
+ </p>
+
+ <p>In addition, Ant has some built-in properties:</p>
+<pre>
+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.
+ant.java.version the JVM version Ant detected; currently it can hold
+ the values "1.2", "1.3",
+ "1.4", "1.5" and "1.6".
+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>
+
+ <a name="propertyHelper"><h1>PropertyHelpers</h1></a>
+
+ <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="CoreTasks/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="http://svn.apache.org/viewvc/ant/antlibs/props/trunk/src/main/org/apache/ant/props/NestedPropertyExpander.java?view=log";><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="CoreTasks/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="CoreTasks/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 ballance 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>
+
+ <a name="toString"><h3>Getting the value of a Reference with
+ ${toString:}</h3></a>
+
+ <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
+ preciously defined as references like</p>
+<pre>
+ <url url="http://ant.apache.org/"; id="anturl"/>
+ <my:task attr="${ant.refid:anturl}"/>
+</pre>
+
+</body>
Propchange: ant/core/trunk/docs/manual/properties.html
------------------------------------------------------------------------------
svn:eol-style = native
Modified: ant/core/trunk/docs/manual/tutorial-tasks-filesets-properties.html
URL:
http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/tutorial-tasks-filesets-properties.html?rev=828198&r1=828197&r2=828198&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/tutorial-tasks-filesets-properties.html
(original)
+++ ant/core/trunk/docs/manual/tutorial-tasks-filesets-properties.html Wed Oct
21 20:39:57 2009
@@ -317,7 +317,7 @@
<p>The test case uses the ant property <i>ant.home</i> as reference. This
property is set by the
<tt>Launcher</tt> class which starts ant. We can use that property in our
buildfiles as a
-<a href="using.html#built-in-props">build-in property [3]</a>. But if we
create a new ant
+<a href="properties.html#built-in-props">build-in property [3]</a>. But if we
create a new ant
environment we have to set that value for our own. And we use the
<code><junit></code> task in fork-mode.
Therefore we have do modify our buildfile:
<pre class="code">
@@ -952,7 +952,7 @@
<h2><a name="resources">Resources</a></h2>
[1] <a
href="tutorial-writing-tasks.html">tutorial-writing-tasks.html</a><br>
[2] <a
href="tutorial-tasks-filesets-properties.zip">tutorial-tasks-filesets-properties.zip</a><br>
- [3] <a
href="using.html#built-in-props">using.html#built-in-props</a><br>
+ [3] <a
href="properties.html#built-in-props">properties.html#built-in-props</a><br>
[4] <a
href="http://ant-contrib.sourceforge.net/";>http://ant-contrib.sourceforge.net/</a><br>
[5] <a href="CoreTasks/java.html">CoreTasks/java.html</a><br>
[6] <a
href="http://ant.apache.org/ant_task_guidelines.html";>http://ant.apache.org/ant_task_guidelines.html</a><br>
Modified: ant/core/trunk/docs/manual/tutorial-writing-tasks.html
URL:
http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/tutorial-writing-tasks.html?rev=828198&r1=828197&r2=828198&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/tutorial-writing-tasks.html (original)
+++ ant/core/trunk/docs/manual/tutorial-writing-tasks.html Wed Oct 21 20:39:57
2009
@@ -102,7 +102,7 @@
</project>
</pre>
<i>ant.project.name</i> is one of the
-<a href="http://ant.apache.org/manual/using.html#built-in-props";
target="_blank">
+<a href="http://ant.apache.org/manual/properties.html#built-in-props";
target="_blank">
build-in properties [1]</a> of Ant.
@@ -755,7 +755,7 @@
Used Links:<br>
- [1] <a
href="http://ant.apache.org/manual/using.html#built-in-props";>http://ant.apache.org/manual/using.html#built-in-props</a><br>
+ [1] <a
href="http://ant.apache.org/manual/properties.html#built-in-props";>http://ant.apache.org/manual/properties.html#built-in-props</a><br>
[2] <a
href="http://ant.apache.org/manual/CoreTasks/taskdef.html";>http://ant.apache.org/manual/CoreTasks/taskdef.html</a><br>
[3] <a
href="http://ant.apache.org/manual/develop.html#set-magic";>http://ant.apache.org/manual/develop.html#set-magic</a><br>
[4] <a
href="http://ant.apache.org/manual/develop.html#nested-elements";>http://ant.apache.org/manual/develop.html#nested-elements</a><br>
Modified: ant/core/trunk/docs/manual/using.html
URL:
http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/using.html?rev=828198&r1=828197&r2=828198&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/using.html (original)
+++ ant/core/trunk/docs/manual/using.html Wed Oct 21 20:39:57 2009
@@ -267,170 +267,27 @@
</p>
<h3><a name="properties">Properties</a></h3>
-<p>A project can have a set of properties. These might be set in the buildfile
-by the <a href="CoreTasks/property.html">property</a> task, or might be set
outside Ant. A
-property has a name and a value; the name is case-sensitive. Properties may be
used in the value of
-task attributes. This is done by placing the property name between
-"<code>${</code>" and "<code>}</code>" in the
-attribute value. For example,
-if there is a "builddir" property with the value
-"build", then this could be used in an attribute like this:
-<code>${builddir}/classes</code>.
-This is resolved at run-time as <code>build/classes</code>.</p>
-<p>In the event you should need to include this construct literally
-(i.e. without property substitutions), simply "escape" the '$' character
-by doubling it. To continue the previous example:
-<pre> <echo>$${builddir}=${builddir}</echo></pre>
-will echo this message:
-<pre> ${builddir}=build/classes</pre></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>
-
-<h3><a name="built-in-props">Built-in Properties</a></h3>
-<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://java.sun.com/j2se/1.3/docs/api/java/lang/System.html#getProperties()">the
Javadoc of System.getProperties</a>.
-</p>
-<p>In addition, Ant has some built-in properties:</p>
-<pre>
-basedir the absolute path of the project's basedir (as set
- with the basedir attribute of <a
href="#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.
-ant.java.version the JVM version Ant detected; currently it can hold
- the values "1.2", "1.3",
- "1.4", "1.5" and "1.6".
-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>
-
-<a name="propertyHelper"><h3>Property Helpers</h3></a>
-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="CoreTasks/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="http://svn.apache.org/viewvc/ant/sandbox/antlibs/props/trunk/src/main/org/apache/ant/props/NestedPropertyExpander.java?view=log";><code>NestedPropertyExpander</code>
- in the "props" Antlib in Ant's sandbox</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="CoreTasks/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="CoreTasks/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>
+<p>Properties are an important way to customize a build process or
+ to just provide shortcuts for strings that are used repeatedly
+ inside a build file.</p>
+
+<p>In its most simple form properties are defined in the build file
+ (for example by the <a href="CoreTasks/property.html">property</a>
+ task) or might be set outside Ant. A property has a name and a
+ value; the name is case-sensitive. Properties may be used in the
+ value of task attributes or in the nested text of tasks that support
+ them. This is done by placing the property name between
+ "<code>${</code>" and "<code>}</code>" in the
+ attribute value. For example, if there is a "builddir"
+ property with the value "build", then this could be used
+ in an attribute like this: <code>${builddir}/classes</code>. This
+ is resolved at run-time as <code>build/classes</code>.</p>
+
+<p>With Ant 1.8.0 property expansion has become much more powerful
+ than simple key value pairs, more details can be
+ found <a href="properties.html">in the concepts section</a> of this
+ manual.</p>
<a name="example"><h3>Example Buildfile</h3></a>
<pre>
@@ -784,52 +641,6 @@
deliberately assign a different meaning to <code>refid</code>.</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
- preciously defined as references like</p>
-<pre>
- <url url="http://ant.apache.org/"; id="anturl"/>
- <my:task attr="${ant.refid:anturl}"/>
-</pre>
-
<h3><a name="external-tasks">Use of external tasks</a></h3>
Ant supports a plugin mechanism for using third party tasks. For using them
you
have to do two steps:
Modified: ant/core/trunk/docs/manual/usinglist.html
URL:
http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/usinglist.html?rev=828198&r1=828197&r2=828198&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/usinglist.html (original)
+++ ant/core/trunk/docs/manual/usinglist.html Wed Oct 21 20:39:57 2009
@@ -34,8 +34,8 @@
<a href="using.html#targets">Targets</a><br/>
<a href="using.html#tasks">Tasks</a><br/>
<a href="using.html#properties">Properties</a><br/>
- <a href="using.html#built-in-props">Built-in Properties</a><br/>
- <a href="using.html#propertyHelper">Property Helpers</a><br />
+ <a href="properties.html#built-in-props">Built-in Properties</a><br/>
+ <a href="properties.html#propertyHelper">Property Helpers</a><br />
<a href="using.html#example">Example Buildfile</a><br/>
<a href="using.html#filters">Token Filters</a><br/>
<a href="using.html#path">Path-like Structures</a><br/>
