Changeset 13003 in josm for trunk/src/org/openstreetmap/josm


Ignore:
Timestamp:
2017-10-16T13:26:41+02:00 (7 years ago)
Author:
bastiK
Message:

see #14794 - add missing top level javadoc; minor refactoring for Condition

Location:
trunk/src/org/openstreetmap/josm/tools/template_engine
Files:
10 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/org/openstreetmap/josm/tools/template_engine/CompoundTemplateEntry.java

    r12798 r13003  
    22package org.openstreetmap.josm.tools.template_engine;
    33
     4/**
     5 * {@link TemplateEntry} that concatenates several templates.
     6 */
    47public final class CompoundTemplateEntry implements TemplateEntry {
    58
    6     public static TemplateEntry fromArray(TemplateEntry... entry) {
    7         if (entry.length == 0)
     9    /**
     10     * Factory method to concatenate several {@code TemplateEntry}s.
     11     *
     12     * If the number of entries is 0 or 1, the result may not be a {@code CompoundTemplateEntry},
     13     * but optimized to a static text or the single entry itself.
     14     * @param entries the {@code TemplateEntry}s to concatenate
     15     * @return a {@link TemplateEntry} that concatenates all the entries
     16     */
     17    public static TemplateEntry fromArray(TemplateEntry... entries) {
     18        if (entries.length == 0)
    819            return new StaticText("");
    9         else if (entry.length == 1)
    10             return entry[0];
     20        else if (entries.length == 1)
     21            return entries[0];
    1122        else
    12             return new CompoundTemplateEntry(entry);
     23            return new CompoundTemplateEntry(entries);
    1324    }
    1425

  • trunk/src/org/openstreetmap/josm/tools/template_engine/Condition.java

    r11057 r13003  
    33
    44import java.util.ArrayList;
     5import java.util.Collection;
    56import java.util.List;
    67
     8/**
     9 * {@link TemplateEntry} that applies other templates based on conditions.
     10 * <p>
     11 * It goes through a number of template entries and executes the first one that is valid.
     12 */
    713public class Condition implements TemplateEntry {
    814
    9     private final List<TemplateEntry> entries = new ArrayList<>();
     15    private final List<TemplateEntry> entries;
    1016
     17    public Condition(Collection<TemplateEntry> entries) {
     18        this.entries = new ArrayList<>(entries);
     19    }
     20
     21    public Condition() {
     22        this.entries = new ArrayList<>();
     23    }
     24
     25    /**
     26     * @deprecated (since 13003) use constructor {@link #Condition(java.util.Collection)} to set the entries
     27     */
     28    @Deprecated
    1129    public List<TemplateEntry> getEntries() {
    1230        return entries;

  • trunk/src/org/openstreetmap/josm/tools/template_engine/ParseError.java

    r12656 r13003  
    88import org.openstreetmap.josm.tools.template_engine.Tokenizer.TokenType;
    99
     10/**
     11 * Exception thrown in case of an error during template parsing.
     12 *
     13 * Usually caused by invalid user input.
     14 */
    1015public class ParseError extends Exception {
    1116

  • trunk/src/org/openstreetmap/josm/tools/template_engine/SearchExpressionCondition.java

    r12656 r13003  
    44import org.openstreetmap.josm.data.osm.search.SearchCompiler.Match;
    55
     6/**
     7 * Conditional {@link TemplateEntry} that executes another template in case a search expression applies
     8 * to the given data provider.
     9 */
    610public class SearchExpressionCondition implements TemplateEntry {
    711
    … …  
    913    private final TemplateEntry text;
    1014
     15    /**
     16     * Creates a new {@link SearchExpressionCondition}.
     17     * @param condition the match condition that is checked before applying the child template
     18     * @param text the child template to execute in case the condition is fulfilled
     19     */
    1120    public SearchExpressionCondition(Match condition, TemplateEntry text) {
    1221        this.condition = condition;

  • trunk/src/org/openstreetmap/josm/tools/template_engine/StaticText.java

    r7937 r13003  
    22package org.openstreetmap.josm.tools.template_engine;
    33
     4/**
     5 * {@link TemplateEntry} representing a static string.
     6 * <p>
     7 * When compiling the template result, the given string will simply be inserted at the current position.
     8 */
    49public class StaticText implements TemplateEntry {
    510
    611    private final String staticText;
    712
     13    /**
     14     * Create a new {@code StaticText}.
     15     * @param staticText the text to insert verbatim
     16     */
    817    public StaticText(String staticText) {
    918        this.staticText = staticText;

  • trunk/src/org/openstreetmap/josm/tools/template_engine/TemplateEngineDataProvider.java

    r12656 r13003  
    66import org.openstreetmap.josm.data.osm.search.SearchCompiler.Match;
    77
     8/**
     9 * Interface for objects that can be used with a template to generate a string.
     10 * <p>
     11 * Provides the necessary information for the template to be applied.
     12 */
    813public interface TemplateEngineDataProvider {
     14    /**
     15     * Get the collection of all keys that can be mapped to values.
     16     * @return all keys that can be mapped to values
     17     */
    918    Collection<String> getTemplateKeys();
    1019
    11     Object getTemplateValue(String name, boolean special);
     20    /**
     21     * Map a key to a value given the properties of the object.
     22     * @param key the key to map
     23     * @param special if the key is a "special:*" keyword that is used
     24     * to get certain information or automated behavior
     25     * @return a value that the key is mapped to or "special" information in case {@code special} is true
     26     */
     27    Object getTemplateValue(String key, boolean special);
    1228
     29    /**
     30     * Check if a condition holds for the object represented by this {@link TemplateEngineDataProvider}.
     31     * @param condition the condition to check (which is a search expression)
     32     * @return true if the condition holds
     33     */
    1334    boolean evaluateCondition(Match condition);
    1435}

  • trunk/src/org/openstreetmap/josm/tools/template_engine/TemplateEntry.java

    r8510 r13003  
    22package org.openstreetmap.josm.tools.template_engine;
    33
     4/**
     5 * Interface for one node in the abstract syntax tree that is the result of parsing a template
     6 * string with {@link TemplateParser}.
     7 *
     8 * The node can either be branching (condition, context switch) or a leaf node (variable, static text).
     9 * The root node, representing the entire template is also a {@code TemplateEntry}.
     10 */
    411public interface TemplateEntry {
     12    /**
     13     * Execute this template by generating text for a given data provider.
     14     * @param result the {@link StringBuilder} to append the text to
     15     * @param dataProvider the data provider from which information should be compiled to a string
     16     */
    517    void appendText(StringBuilder result, TemplateEngineDataProvider dataProvider);
    618
     19    /**
     20     * Check if this template is applicable to the given data provider.
     21     *
     22     * @param dataProvider the data provider to check
     23     * @return true if all conditions are fulfilled to apply the template (for instance all
     24     * required key=value mappings are present), false otherwise
     25     */
    726    boolean isValid(TemplateEngineDataProvider dataProvider);
    827}

  • trunk/src/org/openstreetmap/josm/tools/template_engine/TemplateParser.java

    r12656 r13003  
    2626    /**
    2727     * Constructs a new {@code TemplateParser}.
    28      * @param template template to parse
     28     * @param template template string to parse
    2929     */
    3030    public TemplateParser(String template) {
    … …  
    8888    private TemplateEntry parseCondition() throws ParseError {
    8989        check(TokenType.CONDITION_START);
    90         Condition result = new Condition();
     90        Collection<TemplateEntry> conditionEntries = new ArrayList<>();
    9191        while (true) {
    9292
    … …  
    9898            String searchText = searchExpression.getText().trim();
    9999            if (searchText.isEmpty()) {
    100                 result.getEntries().add(condition);
     100                conditionEntries.add(condition);
    101101            } else {
    102102                try {
    103                     result.getEntries().add(new SearchExpressionCondition(
     103                    conditionEntries.add(new SearchExpressionCondition(
    104104                            SearchCompiler.compile(searchText), condition));
    105105                } catch (SearchParseError e) {
    … …  
    112112            if (token.getType() == TokenType.END) {
    113113                tokenizer.nextToken();
    114                 return result;
     114                return new Condition(conditionEntries);
    115115            } else {
    116116                check(TokenType.PIPE);

  • trunk/src/org/openstreetmap/josm/tools/template_engine/Tokenizer.java

    r12279 r13003  
    66import java.util.Set;
    77
     8/**
     9 * This class converts a template string (stream of characters) into a stream of tokens.
     10 *
     11 * The result of the tokenization (also called lexical analysis) serves as input for the
     12 * parser {@link TemplateParser}.
     13 */
    814public class Tokenizer {
    915
    … …  
    5258    private final StringBuilder text = new StringBuilder();
    5359
     60    /**
     61     * Creates a new {@link Tokenizer}
     62     * @param template the template as a user input string
     63     */
    5464    public Tokenizer(String template) {
    5565        this.template = template;

  • trunk/src/org/openstreetmap/josm/tools/template_engine/Variable.java

    r11057 r13003  
    55import java.util.Locale;
    66
     7/**
     8 * {@link TemplateEntry} that inserts the value of a variable.
     9 * <p>
     10 * Variables starting with "special:" form a separate namespace and
     11 * provide actions other than simple key-value lookup.
     12 * <p>
     13 * A variable with no mapping for a given data provider will be considered not "valid"
     14 * (see {@link TemplateEntry#isValid(TemplateEngineDataProvider)}).
     15 */
    716public class Variable implements TemplateEntry {
    817
    … …  
    1019    private static final String SPECIAL_VALUE_EVERYTHING = "everything";
    1120
    12 
    1321    private final String variableName;
    1422    private final boolean special;
    1523
     24    /**
     25     * Constructs a new {@code Variable}.
     26     * @param variableName the variable name (i.e. the key in the data provider key-value mapping);
     27     * will be considered "special" if the variable name starts with {@link SPECIAL_VARIABLE_PREFIX}
     28     */
    1629    public Variable(String variableName) {
    1730        if (variableName.toLowerCase(Locale.ENGLISH).startsWith(SPECIAL_VARIABLE_PREFIX)) {
    … …  
    5972    }
    6073
     74    /**
     75     * Check if this variable is special.
     76     *
     77     * @return true if this variable is special
     78     */
    6179    public boolean isSpecial() {
    6280        return special;
Note: See TracChangeset for help on using the changeset viewer.