ant-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bode...@apache.org
Subject svn commit: r828198 - in /ant/core/trunk/docs/manual: CoreTasks/property.html CoreTasks/propertyhelper.html conceptstypeslist.html properties.html tutorial-tasks-filesets-properties.html tutorial-writing-tasks.html using.html usinglist.html
Date Wed, 21 Oct 2009 20:39:58 GMT
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>&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://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">&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.
+ant.java.version    the JVM version Ant detected; currently it can hold
+                    the values &quot;1.2&quot;, &quot;1.3&quot;,
+                    &quot;1.4&quot;,  &quot;1.5&quot; and &quot;1.6&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>
+
+  <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>  &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 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>
+&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
+    preciously 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>
+
+</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>&lt;junit&gt;</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>
 &nbsp;&nbsp;[1] <a href="tutorial-writing-tasks.html">tutorial-writing-tasks.html</a><br>
 &nbsp;&nbsp;[2] <a href="tutorial-tasks-filesets-properties.zip">tutorial-tasks-filesets-properties.zip</a><br>
-&nbsp;&nbsp;[3] <a href="using.html#built-in-props">using.html#built-in-props</a><br>
+&nbsp;&nbsp;[3] <a href="properties.html#built-in-props">properties.html#built-in-props</a><br>
 &nbsp;&nbsp;[4] <a href="http://ant-contrib.sourceforge.net/">http://ant-contrib.sourceforge.net/</a><br>
 &nbsp;&nbsp;[5] <a href="CoreTasks/java.html">CoreTasks/java.html</a><br>
 &nbsp;&nbsp;[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 @@
 &lt;/project&gt;
 </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>
-&nbsp;&nbsp;[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>
+&nbsp;&nbsp;[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>
 &nbsp;&nbsp;[2] <a href="http://ant.apache.org/manual/CoreTasks/taskdef.html">http://ant.apache.org/manual/CoreTasks/taskdef.html</a><br>
 &nbsp;&nbsp;[3] <a href="http://ant.apache.org/manual/develop.html#set-magic">http://ant.apache.org/manual/develop.html#set-magic</a><br>
 &nbsp;&nbsp;[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
-&quot;<code>${</code>&quot; and &quot;<code>}</code>&quot;
in the
-attribute value. For example,
-if there is a &quot;builddir&quot; property with the value
-&quot;build&quot;, 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>  &lt;echo&gt;$${builddir}=${builddir}&lt;/echo&gt;</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>&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://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">&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.
-ant.java.version    the JVM version Ant detected; currently it can hold
-                    the values &quot;1.2&quot;, &quot;1.3&quot;,
-                    &quot;1.4&quot;,  &quot;1.5&quot; and &quot;1.6&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>
-
-<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
+  &quot;<code>${</code>&quot; and &quot;<code>}</code>&quot;
in the
+  attribute value. For example, if there is a &quot;builddir&quot;
+  property with the value &quot;build&quot;, 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>
-&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
-  preciously 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>
-
 <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/>



Mime
View raw message