Author: bodewig Date: Fri Sep 4 08:02:49 2009 New Revision: 811240 URL: http://svn.apache.org/viewvc?rev=811240&view=rev Log: document PropertyExpander and helpers, some minor optimizations in ParseProperties
Modified: ant/core/trunk/src/main/org/apache/tools/ant/property/ParseNextProperty.java ant/core/trunk/src/main/org/apache/tools/ant/property/ParseProperties.java ant/core/trunk/src/main/org/apache/tools/ant/property/PropertyExpander.java Modified: ant/core/trunk/src/main/org/apache/tools/ant/property/ParseNextProperty.java URL: http://svn.apache.org/viewvc/ant/core/trunk/src/main/org/apache/tools/ant/property/ParseNextProperty.java?rev=811240&r1=811239&r2=811240&view=diff ============================================================================== --- ant/core/trunk/src/main/org/apache/tools/ant/property/ParseNextProperty.java (original) +++ ant/core/trunk/src/main/org/apache/tools/ant/property/ParseNextProperty.java Fri Sep 4 08:02:49 2009 @@ -22,7 +22,8 @@ import org.apache.tools.ant.Project; /** - * Interface to parse a property. + * Helper for {...@link PropertyExpander PropertyExpander} that can be + * used to expand property references to values. * @since Ant 1.8.0 */ public interface ParseNextProperty { Modified: ant/core/trunk/src/main/org/apache/tools/ant/property/ParseProperties.java URL: http://svn.apache.org/viewvc/ant/core/trunk/src/main/org/apache/tools/ant/property/ParseProperties.java?rev=811240&r1=811239&r2=811240&view=diff ============================================================================== --- ant/core/trunk/src/main/org/apache/tools/ant/property/ParseProperties.java (original) +++ ant/core/trunk/src/main/org/apache/tools/ant/property/ParseProperties.java Fri Sep 4 08:02:49 2009 @@ -24,6 +24,7 @@ /** * Parse properties using a collection of expanders. + * * @since Ant 1.8.0 */ public class ParseProperties implements ParseNextProperty { @@ -53,9 +54,33 @@ } /** - * Decode properties from a String representation. If the entire - * contents of the String resolve to a single property, that value - * is returned. Otherwise a String is returned. + * Decode properties from a String representation. + * + * <ul> + * + * <li>This implementation starts parsing the <code>value</code> + * parameter (unsurprisingly) at the beginning and asks each + * {...@link org.apache.tools.ant.PropertyHelper.PropertyExpander + * PropertyExpander} whether there is a property reference at + * that point. PropertyExpanders return the name of a property + * they may find and may advance the parse position.</li> + * + * <li>If the PropertyExpander returns <code>null</code> the + * method continues with the next PropertyExpander, otherwise it + * tries to look up the property's value using the configured + * {...@link GetProperty GetProperty} instance.</li> + * + * <li>Once all PropertyExpanders have been consulted, the parse + * position is advanced by one character and the process repeated + * until <code>value</code> is exhausted.</li> + * + * </ul> + * + * <p>If the entire contents of <code>value</code> resolves to a + * single property, the looked up property value is returned. + * Otherwise a String is returned that concatenates the + * non-property parts of <code>value</code> and the expanded + * values of the properties that have been found.</p> * * @param value The string to be scanned for property references. * May be <code>null</code>, in which case this @@ -68,19 +93,20 @@ if (value == null || "".equals(value)) { return value; } + final int len = value.length(); ParsePosition pos = new ParsePosition(0); Object o = parseNextProperty(value, pos); - if (o != null && pos.getIndex() == value.length()) { + if (o != null && pos.getIndex() >= len) { return o; } - StringBuffer sb = new StringBuffer(value.length() * 2); + StringBuffer sb = new StringBuffer(len * 2); if (o == null) { sb.append(value.charAt(pos.getIndex())); pos.setIndex(pos.getIndex() + 1); } else { sb.append(o); } - while (pos.getIndex() < value.length()) { + while (pos.getIndex() < len) { o = parseNextProperty(value, pos); if (o == null) { sb.append(value.charAt(pos.getIndex())); @@ -94,6 +120,12 @@ /** * Learn whether a String contains replaceable properties. + * + * <p>Uses the configured {...@link + * org.apache.tools.ant.PropertyHelper.PropertyExpander + * PropertyExpanders} and scans through the string. Returns true + * as soon as any expander finds a property.</p> + * * @param value the String to check. * @return <code>true</code> if <code>value</code> contains property notation. */ @@ -101,7 +133,8 @@ if (value == null) { return false; } - for (ParsePosition pos = new ParsePosition(0); pos.getIndex() < value.length();) { + final int len = value.length(); + for (ParsePosition pos = new ParsePosition(0); pos.getIndex() < len;) { if (parsePropertyName(value, pos) != null) { return true; } @@ -113,12 +146,28 @@ /** * Return any property that can be parsed from the specified position * in the specified String. + * + * <p>Uses the configured {...@link + * org.apache.tools.ant.PropertyHelper.PropertyExpander + * PropertyExpanders} and {...@link GetProperty GetProperty} + * instance .</p> + * * @param value String to parse * @param pos ParsePosition - * @return Object or null if no property is at the current location. + * @return Object or null if no property is at the current + * location. If a property reference has been found but the + * property doesn't expand to a value, the property's name is + * returned. */ public Object parseNextProperty(String value, ParsePosition pos) { - int start = pos.getIndex(); + final int start = pos.getIndex(); + + if (start > value.length()) { + // early exit, can't find any property here, no need to + // consult all the delegates. + return null; + } + String propertyName = parsePropertyName(value, pos); if (propertyName != null) { Object result = getProperty(propertyName); Modified: ant/core/trunk/src/main/org/apache/tools/ant/property/PropertyExpander.java URL: http://svn.apache.org/viewvc/ant/core/trunk/src/main/org/apache/tools/ant/property/PropertyExpander.java?rev=811240&r1=811239&r2=811240&view=diff ============================================================================== --- ant/core/trunk/src/main/org/apache/tools/ant/property/PropertyExpander.java (original) +++ ant/core/trunk/src/main/org/apache/tools/ant/property/PropertyExpander.java Fri Sep 4 08:02:49 2009 @@ -22,17 +22,30 @@ import java.text.ParsePosition; /** - * Interface to a class (normally PropertyHelper) to get a property. + * Responsible for locating a property reference inside a String. * @since Ant 1.8.0 */ public interface PropertyExpander extends PropertyHelper.Delegate { + /** - * Parse the next property name. + * Determine whether there is a property reference at the current + * ParsePosition and return its name (or null if there is none). + * + * <p>Implementations should advance the ParsePosition to the last + * character that makes up the property reference. E.g. the + * default implementation would return <code>"foo"</code> for + * <code>${foo}</code> and advance the ParsePosition to the + * <code>}</code> character.</p> + * * @param s the String to parse. - * @param pos the ParsePosition in use. - * @param parseNextProperty parse next property - * @return parsed String if any, else <code>null</code>. + * @param pos the ParsePosition in use, the location is expected + * to be modified if a property reference has been found (and may + * even be modified if no reference has been found). + * @param parseNextProperty provides access to the Project and may + * be used to look up property values. + * @return property name if any, else <code>null</code>. */ - String parsePropertyName(String s, ParsePosition pos, ParseNextProperty parseNextProperty); + String parsePropertyName(String s, ParsePosition pos, + ParseNextProperty parseNextProperty); }