From d8f18f1b903f8f7344a3c679504098d185c75ea7 Mon Sep 17 00:00:00 2001
From: Stefan Bodewig <bodewig@apache.org>
Date: Thu, 27 Aug 2009 10:59:40 +0000
Subject: [PATCH] add some more documentation about property helpers

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@808366 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/CoreTasks/propertyhelper.html |  2 +-
 docs/manual/using.html                    | 56 +++++++++++++++++++++++
 docs/manual/usinglist.html                |  2 +-
 3 files changed, 58 insertions(+), 2 deletions(-)

diff --git a/docs/manual/CoreTasks/propertyhelper.html b/docs/manual/CoreTasks/propertyhelper.html
index 47f1a5046..f6c1800fa 100644
--- a/docs/manual/CoreTasks/propertyhelper.html
+++ b/docs/manual/CoreTasks/propertyhelper.html
@@ -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>
diff --git a/docs/manual/using.html b/docs/manual/using.html
index df2c444f8..de8ae3c2e 100644
--- a/docs/manual/using.html
+++ b/docs/manual/using.html
@@ -345,6 +345,62 @@ parsing, etc. This makes Ant's property handling highly extensible; also of inte
 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>
 &lt;project name=&quot;MyProject&quot; default=&quot;dist&quot; basedir=&quot;.&quot;&gt;
diff --git a/docs/manual/usinglist.html b/docs/manual/usinglist.html
index 014c0b34d..8a1cbf4c8 100644
--- a/docs/manual/usinglist.html
+++ b/docs/manual/usinglist.html
@@ -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/>