Author: bodewig
Date: Thu Aug 27 10:59:40 2009
New Revision: 808366
URL: http://svn.apache.org/viewvc?rev=808366&view=rev
Log:
add some more documentation about property helpers
Modified:
ant/core/trunk/docs/manual/CoreTasks/propertyhelper.html
ant/core/trunk/docs/manual/using.html
ant/core/trunk/docs/manual/usinglist.html
Modified: ant/core/trunk/docs/manual/CoreTasks/propertyhelper.html
URL:
http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/CoreTasks/propertyhelper.html?rev=808366&r1=808365&r2=808366&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/CoreTasks/propertyhelper.html (original)
+++ ant/core/trunk/docs/manual/CoreTasks/propertyhelper.html Thu Aug 27
10:59:40 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="../using.html#propertyHelper">Property Helper</a> for more
information.
<b>Since Ant 1.8</b></p>
<h3>Parameters specified as nested elements</h3>
Modified: ant/core/trunk/docs/manual/using.html
URL:
http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/using.html?rev=808366&r1=808365&r2=808366&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/using.html (original)
+++ ant/core/trunk/docs/manual/using.html Thu Aug 27 10:59:40 2009
@@ -345,6 +345,62 @@
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.
<code>org.apache.tools.ant.PropertyHelper$PropertyEvaluator</code>
+ is used to expand <code>${some-string}</code> into
+ an <code>Object</code>
+ while <code>org.apache.tools.ant.PropertyHelper$PropertySetter</code>
+ is responsible for setting properties.
+ Finally <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>
+
+<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>An example of a <code>PropertySetter</code> can be found
+ in <code>org.apache.tools.ant.property.LocalProperties</code> which
+ implements storage for <a href="CoreTasks/local.html">local
+ properties</a>.</p>
+
+<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>
+
<a name="example"><h3>Example Buildfile</h3></a>
<pre>
<project name="MyProject" default="dist"
basedir=".">
Modified: ant/core/trunk/docs/manual/usinglist.html
URL:
http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/usinglist.html?rev=808366&r1=808365&r2=808366&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/usinglist.html (original)
+++ ant/core/trunk/docs/manual/usinglist.html Thu Aug 27 10:59:40 2009
@@ -35,7 +35,7 @@
<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="using.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/>
