Index: trunk/src/org/openstreetmap/josm/tools/template_engine/CompoundTemplateEntry.java =================================================================== --- trunk/src/org/openstreetmap/josm/tools/template_engine/CompoundTemplateEntry.java (revision 13002) +++ trunk/src/org/openstreetmap/josm/tools/template_engine/CompoundTemplateEntry.java (revision 13003) @@ -2,13 +2,24 @@ package org.openstreetmap.josm.tools.template_engine; +/** + * {@link TemplateEntry} that concatenates several templates. + */ public final class CompoundTemplateEntry implements TemplateEntry { - public static TemplateEntry fromArray(TemplateEntry... entry) { - if (entry.length == 0) + /** + * Factory method to concatenate several {@code TemplateEntry}s. + * + * If the number of entries is 0 or 1, the result may not be a {@code CompoundTemplateEntry}, + * but optimized to a static text or the single entry itself. + * @param entries the {@code TemplateEntry}s to concatenate + * @return a {@link TemplateEntry} that concatenates all the entries + */ + public static TemplateEntry fromArray(TemplateEntry... entries) { + if (entries.length == 0) return new StaticText(""); - else if (entry.length == 1) - return entry[0]; + else if (entries.length == 1) + return entries[0]; else - return new CompoundTemplateEntry(entry); + return new CompoundTemplateEntry(entries); } Index: trunk/src/org/openstreetmap/josm/tools/template_engine/Condition.java =================================================================== --- trunk/src/org/openstreetmap/josm/tools/template_engine/Condition.java (revision 13002) +++ trunk/src/org/openstreetmap/josm/tools/template_engine/Condition.java (revision 13003) @@ -3,10 +3,28 @@ import java.util.ArrayList; +import java.util.Collection; import java.util.List; +/** + * {@link TemplateEntry} that applies other templates based on conditions. + *

+ * It goes through a number of template entries and executes the first one that is valid. + */ public class Condition implements TemplateEntry { - private final List entries = new ArrayList<>(); + private final List entries; + public Condition(Collection entries) { + this.entries = new ArrayList<>(entries); + } + + public Condition() { + this.entries = new ArrayList<>(); + } + + /** + * @deprecated (since 13003) use constructor {@link #Condition(java.util.Collection)} to set the entries + */ + @Deprecated public List getEntries() { return entries; Index: trunk/src/org/openstreetmap/josm/tools/template_engine/ParseError.java =================================================================== --- trunk/src/org/openstreetmap/josm/tools/template_engine/ParseError.java (revision 13002) +++ trunk/src/org/openstreetmap/josm/tools/template_engine/ParseError.java (revision 13003) @@ -8,4 +8,9 @@ import org.openstreetmap.josm.tools.template_engine.Tokenizer.TokenType; +/** + * Exception thrown in case of an error during template parsing. + * + * Usually caused by invalid user input. + */ public class ParseError extends Exception { Index: trunk/src/org/openstreetmap/josm/tools/template_engine/SearchExpressionCondition.java =================================================================== --- trunk/src/org/openstreetmap/josm/tools/template_engine/SearchExpressionCondition.java (revision 13002) +++ trunk/src/org/openstreetmap/josm/tools/template_engine/SearchExpressionCondition.java (revision 13003) @@ -4,4 +4,8 @@ import org.openstreetmap.josm.data.osm.search.SearchCompiler.Match; +/** + * Conditional {@link TemplateEntry} that executes another template in case a search expression applies + * to the given data provider. + */ public class SearchExpressionCondition implements TemplateEntry { @@ -9,4 +13,9 @@ private final TemplateEntry text; + /** + * Creates a new {@link SearchExpressionCondition}. + * @param condition the match condition that is checked before applying the child template + * @param text the child template to execute in case the condition is fulfilled + */ public SearchExpressionCondition(Match condition, TemplateEntry text) { this.condition = condition; Index: trunk/src/org/openstreetmap/josm/tools/template_engine/StaticText.java =================================================================== --- trunk/src/org/openstreetmap/josm/tools/template_engine/StaticText.java (revision 13002) +++ trunk/src/org/openstreetmap/josm/tools/template_engine/StaticText.java (revision 13003) @@ -2,8 +2,17 @@ package org.openstreetmap.josm.tools.template_engine; +/** + * {@link TemplateEntry} representing a static string. + *

+ * When compiling the template result, the given string will simply be inserted at the current position. + */ public class StaticText implements TemplateEntry { private final String staticText; + /** + * Create a new {@code StaticText}. + * @param staticText the text to insert verbatim + */ public StaticText(String staticText) { this.staticText = staticText; Index: trunk/src/org/openstreetmap/josm/tools/template_engine/TemplateEngineDataProvider.java =================================================================== --- trunk/src/org/openstreetmap/josm/tools/template_engine/TemplateEngineDataProvider.java (revision 13002) +++ trunk/src/org/openstreetmap/josm/tools/template_engine/TemplateEngineDataProvider.java (revision 13003) @@ -6,9 +6,30 @@ import org.openstreetmap.josm.data.osm.search.SearchCompiler.Match; +/** + * Interface for objects that can be used with a template to generate a string. + *

+ * Provides the necessary information for the template to be applied. + */ public interface TemplateEngineDataProvider { + /** + * Get the collection of all keys that can be mapped to values. + * @return all keys that can be mapped to values + */ Collection getTemplateKeys(); - Object getTemplateValue(String name, boolean special); + /** + * Map a key to a value given the properties of the object. + * @param key the key to map + * @param special if the key is a "special:*" keyword that is used + * to get certain information or automated behavior + * @return a value that the key is mapped to or "special" information in case {@code special} is true + */ + Object getTemplateValue(String key, boolean special); + /** + * Check if a condition holds for the object represented by this {@link TemplateEngineDataProvider}. + * @param condition the condition to check (which is a search expression) + * @return true if the condition holds + */ boolean evaluateCondition(Match condition); } Index: trunk/src/org/openstreetmap/josm/tools/template_engine/TemplateEntry.java =================================================================== --- trunk/src/org/openstreetmap/josm/tools/template_engine/TemplateEntry.java (revision 13002) +++ trunk/src/org/openstreetmap/josm/tools/template_engine/TemplateEntry.java (revision 13003) @@ -2,7 +2,26 @@ package org.openstreetmap.josm.tools.template_engine; +/** + * Interface for one node in the abstract syntax tree that is the result of parsing a template + * string with {@link TemplateParser}. + * + * The node can either be branching (condition, context switch) or a leaf node (variable, static text). + * The root node, representing the entire template is also a {@code TemplateEntry}. + */ public interface TemplateEntry { + /** + * Execute this template by generating text for a given data provider. + * @param result the {@link StringBuilder} to append the text to + * @param dataProvider the data provider from which information should be compiled to a string + */ void appendText(StringBuilder result, TemplateEngineDataProvider dataProvider); + /** + * Check if this template is applicable to the given data provider. + * + * @param dataProvider the data provider to check + * @return true if all conditions are fulfilled to apply the template (for instance all + * required key=value mappings are present), false otherwise + */ boolean isValid(TemplateEngineDataProvider dataProvider); } Index: trunk/src/org/openstreetmap/josm/tools/template_engine/TemplateParser.java =================================================================== --- trunk/src/org/openstreetmap/josm/tools/template_engine/TemplateParser.java (revision 13002) +++ trunk/src/org/openstreetmap/josm/tools/template_engine/TemplateParser.java (revision 13003) @@ -26,5 +26,5 @@ /** * Constructs a new {@code TemplateParser}. - * @param template template to parse + * @param template template string to parse */ public TemplateParser(String template) { @@ -88,5 +88,5 @@ private TemplateEntry parseCondition() throws ParseError { check(TokenType.CONDITION_START); - Condition result = new Condition(); + Collection conditionEntries = new ArrayList<>(); while (true) { @@ -98,8 +98,8 @@ String searchText = searchExpression.getText().trim(); if (searchText.isEmpty()) { - result.getEntries().add(condition); + conditionEntries.add(condition); } else { try { - result.getEntries().add(new SearchExpressionCondition( + conditionEntries.add(new SearchExpressionCondition( SearchCompiler.compile(searchText), condition)); } catch (SearchParseError e) { @@ -112,5 +112,5 @@ if (token.getType() == TokenType.END) { tokenizer.nextToken(); - return result; + return new Condition(conditionEntries); } else { check(TokenType.PIPE); Index: trunk/src/org/openstreetmap/josm/tools/template_engine/Tokenizer.java =================================================================== --- trunk/src/org/openstreetmap/josm/tools/template_engine/Tokenizer.java (revision 13002) +++ trunk/src/org/openstreetmap/josm/tools/template_engine/Tokenizer.java (revision 13003) @@ -6,4 +6,10 @@ import java.util.Set; +/** + * This class converts a template string (stream of characters) into a stream of tokens. + * + * The result of the tokenization (also called lexical analysis) serves as input for the + * parser {@link TemplateParser}. + */ public class Tokenizer { @@ -52,4 +58,8 @@ private final StringBuilder text = new StringBuilder(); + /** + * Creates a new {@link Tokenizer} + * @param template the template as a user input string + */ public Tokenizer(String template) { this.template = template; Index: trunk/src/org/openstreetmap/josm/tools/template_engine/Variable.java =================================================================== --- trunk/src/org/openstreetmap/josm/tools/template_engine/Variable.java (revision 13002) +++ trunk/src/org/openstreetmap/josm/tools/template_engine/Variable.java (revision 13003) @@ -5,4 +5,13 @@ import java.util.Locale; +/** + * {@link TemplateEntry} that inserts the value of a variable. + *

+ * Variables starting with "special:" form a separate namespace and + * provide actions other than simple key-value lookup. + *

+ * A variable with no mapping for a given data provider will be considered not "valid" + * (see {@link TemplateEntry#isValid(TemplateEngineDataProvider)}). + */ public class Variable implements TemplateEntry { @@ -10,8 +19,12 @@ private static final String SPECIAL_VALUE_EVERYTHING = "everything"; - private final String variableName; private final boolean special; + /** + * Constructs a new {@code Variable}. + * @param variableName the variable name (i.e. the key in the data provider key-value mapping); + * will be considered "special" if the variable name starts with {@link SPECIAL_VARIABLE_PREFIX} + */ public Variable(String variableName) { if (variableName.toLowerCase(Locale.ENGLISH).startsWith(SPECIAL_VARIABLE_PREFIX)) { @@ -59,4 +72,9 @@ } + /** + * Check if this variable is special. + * + * @return true if this variable is special + */ public boolean isSpecial() { return special;