From 2f1a9d25bf1a2e65940d93c247e6dae2def24513 Mon Sep 17 00:00:00 2001 From: Stefan Bodewig Date: Wed, 21 Oct 2009 20:39:57 +0000 Subject: [PATCH] extract and expand property documentation git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@828198 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/CoreTasks/property.html | 2 +- docs/manual/CoreTasks/propertyhelper.html | 2 +- docs/manual/conceptstypeslist.html | 1 + docs/manual/properties.html | 326 ++++++++++++++++++ .../tutorial-tasks-filesets-properties.html | 4 +- docs/manual/tutorial-writing-tasks.html | 4 +- docs/manual/using.html | 229 ++---------- docs/manual/usinglist.html | 4 +- 8 files changed, 355 insertions(+), 217 deletions(-) create mode 100644 docs/manual/properties.html diff --git a/docs/manual/CoreTasks/property.html b/docs/manual/CoreTasks/property.html index 70841a6b3..83772a581 100644 --- a/docs/manual/CoreTasks/property.html +++ b/docs/manual/CoreTasks/property.html @@ -57,7 +57,7 @@ instance.

properties. These references are resolved at the time these properties are set. This also holds for properties loaded from a property file.

A list of predefined properties can be found here.

+href="../properties.html#built-in-props">here.

Since Ant 1.7.1 it is possible to load properties defined in xml according to Suns DTD, if Java5+ is present. For this the name of the file, resource or url has diff --git a/docs/manual/CoreTasks/propertyhelper.html b/docs/manual/CoreTasks/propertyhelper.html index 141b34c6f..99d3fb882 100644 --- a/docs/manual/CoreTasks/propertyhelper.html +++ b/docs/manual/CoreTasks/propertyhelper.html @@ -31,7 +31,7 @@ (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 -Property Helper for more information. +Property Helper for more information. Since Ant 1.8.0

Parameters specified as nested elements

diff --git a/docs/manual/conceptstypeslist.html b/docs/manual/conceptstypeslist.html index 6e09a8467..cdb23f878 100644 --- a/docs/manual/conceptstypeslist.html +++ b/docs/manual/conceptstypeslist.html @@ -28,6 +28,7 @@

Table of Contents

Concepts

+Properties and PropertyHelpers ant.build.clonevm
build.sysclasspath
Ant properties controlling javac
diff --git a/docs/manual/properties.html b/docs/manual/properties.html new file mode 100644 index 000000000..480b26c60 --- /dev/null +++ b/docs/manual/properties.html @@ -0,0 +1,326 @@ + + + + + + + Properties and PropertyHelpers + + + +

Properties

+ +

Properties are key-value-pairs where Ant tries to + expand ${key} to value at runtime.

+ +

There are many tasks that can set properties, the most common one + is the property task. In + addition properties can be defined + via command line arguments or similar + mechanisms from outside of Ant.

+ +

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 ant, antcall or subant tasks + and make it available to the calling build process, though.

+ +

Starting with Ant 1.8.0 + the local task can be used to + create properties that are locally scoped to a target or + a sequential element like + the one of the macrodef + task.

+ +

Built-in Properties

 + +

Ant provides access to all system properties as if they had been + defined using a <property> task. For + example, ${os.name} expands to the name of the + operating system.

+

For a list of system properties see + the Javadoc of System.getProperties. +

+ +

In addition, Ant has some built-in properties:

+
+basedir             the absolute path of the project's basedir (as set
+                    with the basedir attribute of <project>).
+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 ant.jar file.
+
+ +

There is also another property, but this is set by the launcher + script and therefore maybe not set inside IDEs:

+
+ant.home            home directory of Ant
+
+ +

The following property is only set if Ant is started via the + Launcher class (which means it may not be set inside IDEs + either):

+
+ant.library.dir     the directory that has been used to load Ant's
+                    jars from.  In most cases this is ANT_HOME/lib.
+
+ +

PropertyHelpers

 + +

Ant's property handling is accomplished by an instance of + org.apache.tools.ant.PropertyHelper 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 org.apache.tools.ant.PropertyHelper$Delegate + 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 propertyhelper + task used to manipulate the PropertyHelper and its delegates from + the context of the Ant buildfile. + +

There are three sub-interfaces of Delegate that may be + useful to implement.

+ + + +

The default PropertyExpander looks similar to:

+ +
+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;
+    }
+}
+
+ +

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

+ +
+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();
+    }
+}
+
+ + +

Property Expansion

+ +

When Ant encounters a construct ${some-text} the + exact parsing semantics are subject to the configured property + helper delegates.

+ +

$$ Expansion

+ +

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

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

which will echo this message:

+ +
  ${builddir}=build/classes
+ +

if the property builddir has the + value build/classes.

+ +

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 "$$".

+ +

Nesting of Braces

+ +

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 ${a${b}} it will be + translated into two parts:

+ +
    +
  1. the expansion of property a${b - likely nothing + useful.
    2. +
  2. the literal text } resulting from the second + closing brace
    3. +
+ +

This means you can't use easily expand properties whose names are + given by properties, but there + are some + workarounds for older versions of Ant. With Ant 1.8.0 and the + the props Antlib + you can configure Ant to use + the NestedPropertyExpander defined there if you need + such a feature.

+ +

Expanding a "Property Name"

+ +

In its most simple form ${key} is supposed to look + up a property named key and expand to the value of + the property. Additional PropertyEvaluators may + result in a different interpretation of key, + though.

+ +

The props + Antlib provides a few interesting evaluators but there are + also a few built-in ones.

+ +

Getting the value of a Reference with + ${toString:}

 + +

Any Ant type which has been declared with a reference can also + its string value extracted by using the ${toString:} + operation, with the name of the reference listed after + the toString: text. The toString() + 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.

+ +

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

+ +

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

There is no guarantee that external types provide meaningful + information in such a situation

+ +

Getting the value of a Reference with + ${ant.refid:}

+ +

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

+ +

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

+
+public void setAttr(Resource r) { ... }
+
+ +

then the syntax can be used to pass in resource subclasses + preciously defined as references like

+
+  <url url="http://ant.apache.org/" id="anturl"/>
+  <my:task attr="${ant.refid:anturl}"/>
+
+ + diff --git a/docs/manual/tutorial-tasks-filesets-properties.html b/docs/manual/tutorial-tasks-filesets-properties.html index 7bde1fe87..8bd40cbba 100644 --- a/docs/manual/tutorial-tasks-filesets-properties.html +++ b/docs/manual/tutorial-tasks-filesets-properties.html @@ -317,7 +317,7 @@ whithout being complex :-)

The test case uses the ant property ant.home as reference. This property is set by the Launcher class which starts ant. We can use that property in our buildfiles as a -build-in property [3]. But if we create a new ant +build-in property [3]. But if we create a new ant environment we have to set that value for our own. And we use the <junit> task in fork-mode. Therefore we have do modify our buildfile: 

@@ -952,7 +952,7 @@ Now the new task is uploaded into the bug database.
 
Resources

   [1] tutorial-writing-tasks.html

   [2] tutorial-tasks-filesets-properties.zip

-  [3] using.html#built-in-props

+  [3] properties.html#built-in-props

   [4] http://ant-contrib.sourceforge.net/

   [5] CoreTasks/java.html

   [6] http://ant.apache.org/ant_task_guidelines.html

diff --git a/docs/manual/tutorial-writing-tasks.html b/docs/manual/tutorial-writing-tasks.html
index 6e5a9b881..7b79a5658 100644
--- a/docs/manual/tutorial-writing-tasks.html
+++ b/docs/manual/tutorial-writing-tasks.html
@@ -102,7 +102,7 @@ the execution of some steps bofore. So the refactored code is:
 </project>
ant.project.name is one of the - + build-in properties [1] of Ant. @@ -755,7 +755,7 @@ The last sources and the buildfile are also available Used Links:
-  [1] http://ant.apache.org/manual/using.html#built-in-props
+  [1] http://ant.apache.org/manual/properties.html#built-in-props
  [2] http://ant.apache.org/manual/CoreTasks/taskdef.html
  [3] http://ant.apache.org/manual/develop.html#set-magic
  [4] http://ant.apache.org/manual/develop.html#nested-elements
diff --git a/docs/manual/using.html b/docs/manual/using.html index a8f87e785..77687b4ac 100644 --- a/docs/manual/using.html +++ b/docs/manual/using.html @@ -267,170 +267,27 @@ task instances at all, only proxies.

Properties

-

A project can have a set of properties. These might be set in the buildfile -by the property 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 -"${" and "}" 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: -${builddir}/classes. -This is resolved at run-time as build/classes.

-

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: -

  <echo>$${builddir}=${builddir}</echo>
-will echo this message: -
  ${builddir}=build/classes

-

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 "$$".

- -

Built-in Properties

-

Ant provides access to all system properties as if they had been -defined using a <property> task. -For example, ${os.name} expands to the -name of the operating system.

-

For a list of system properties see -the Javadoc of System.getProperties. -

-

In addition, Ant has some built-in properties:

-
-basedir             the absolute path of the project's basedir (as set
-                    with the basedir attribute of <project>).
-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 ant.jar file.
-
-

There is also another property, but this is set by the launcher script and therefore -maybe not set inside IDEs:

-
-ant.home            home directory of Ant
-
-

The following property is only set if Ant is started via the - Launcher class (which means it may not be set inside IDEs - either):

-
-ant.library.dir     the directory that has been used to load Ant's
-                    jars from.  In most cases this is ANT_HOME/lib.
-
- -

Property Helpers

 -Ant's property handling is accomplished by an instance of -org.apache.tools.ant.PropertyHelper 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 org.apache.tools.ant.PropertyHelper$Delegate -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 propertyhelper task used to manipulate the -PropertyHelper and its delegates from the context of the Ant buildfile. - -

There are three sub-interfaces of Delegate that may be - useful to implement.

- - -

The default PropertyExpander looks similar to:

- -
-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;
-    }
-}
-
- -

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

- -
-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();
-    }
-}
-
+

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.

+ +

In its most simple form properties are defined in the build file + (for example by the property + 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 + "${" and "}" 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: ${builddir}/classes. This + is resolved at run-time as build/classes.

+ +

With Ant 1.8.0 property expansion has become much more powerful + than simple key value pairs, more details can be + found in the concepts section of this + manual.

Example Buildfile

 
@@ -784,52 +641,6 @@ implementation of the element upon which it is specified. Some tasks (the
 deliberately assign a different meaning to refid.

 
 
-
Getting the value of a Reference with ${toString:}

-

-Any Ant type which has been declared with a reference can also its string
-value extracted by using the ${toString:} operation,
-with the name of the reference listed after the  toString: text. 
-The  toString() 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.
-

-

-For example, here is how to get a listing of the files in a fileset, 
-

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

-

-There is no guarantee that external types provide meaningful information in such
-a situation

-
-
Getting the value of a Reference with
-    ${ant.refid:}

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

-
-
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

-
-public void setAttr(Resource r) { ... }
-

-
then the syntax can be used to pass in resource subclasses
-  preciously defined as references like

-
-  <url url="http://ant.apache.org/" id="anturl"/>
-  <my:task attr="${ant.refid:anturl}"/>
-

-
 
Use of external tasks
 
 Ant supports a plugin mechanism for using third party tasks. For using them you 
 have to do two steps: 
diff --git a/docs/manual/usinglist.html b/docs/manual/usinglist.html
index 8a1cbf4c8..abe2c0c95 100644
--- a/docs/manual/usinglist.html
+++ b/docs/manual/usinglist.html
@@ -34,8 +34,8 @@
   Targets

   Tasks

   Properties

-  Built-in Properties

-  Property Helpers

+  Built-in Properties

+  Property Helpers

   Example Buildfile

   Token Filters

   Path-like Structures