Changeset 8654 in josm

Timestamp:

2015-08-09T23:22:36+02:00 (9 years ago)

Author:

Don-vip

Message:

fix #11769 - Documentation for KeyCondition (patch by michael2402)

File:

• trunk/src/org/openstreetmap/josm/gui/mappaint/mapcss/Condition.java (modified) (8 diffs)

trunk/src/org/openstreetmap/josm/gui/mappaint/mapcss/Condition.java

@@ -16 +16 @@
 import org.openstreetmap.josm.data.osm.Node;
 import org.openstreetmap.josm.data.osm.OsmPrimitive;
+import org.openstreetmap.josm.data.osm.OsmUtils;
 import org.openstreetmap.josm.data.osm.Relation;
 import org.openstreetmap.josm.data.osm.Tag;
@@ -83 +84 @@
     }
 
+    /**
+     * This is the operation that {@link KeyValueCondition} uses to match.
+     */
     public static enum Op {
-        EQ, NEQ, GREATER_OR_EQUAL, GREATER, LESS_OR_EQUAL, LESS,
-        REGEX, NREGEX, ONE_OF, BEGINS_WITH, ENDS_WITH, CONTAINS;
+        /** The value equals the given reference. */
+        EQ,
+        /** The value does not equal the reference. */
+        NEQ,
+        /** The value is greater than or equal to the given reference value (as float). */
+        GREATER_OR_EQUAL,
+        /** The value is greater than the given reference value (as float). */
+        GREATER,
+        /** The value is less than or equal to the given reference value (as float). */
+        LESS_OR_EQUAL,
+        /** The value is less than the given reference value (as float). */
+        LESS,
+        /** The reference is treated as regular expression and the value needs to match it. */
+        REGEX,
+        /** The reference is treated as regular expression and the value needs to not match it. */
+        NREGEX,
+        /** The reference is treated as a list separated by ';'. Spaces around the ; are ignored.
+         *  The value needs to be equal one of the list elements. */
+        ONE_OF,
+        /** The value needs to begin with the reference string. */
+        BEGINS_WITH,
+        /** The value needs to end with the reference string. */
+        ENDS_WITH,
+         /** The value needs to contain the reference string. */
+        CONTAINS;
 
         public static final Set<Op> NEGATED_OPS = EnumSet.of(NEQ, NREGEX);
 
+        /**
+         * Evaluates a value against a reference string.
+         * @param testString The value. May be <code>null</code>
+         * @param prototypeString The reference string-
+         * @return <code>true</code> if and only if this operation matches for the given value/reference pair.
+         */
         public boolean eval(String testString, String prototypeString) {
             if (testString == null && !NEGATED_OPS.contains(this))
@@ -150 +183 @@
 
     /**
-     * Most common case of a KeyValueCondition.
+     * Most common case of a KeyValueCondition, this is the basic key=value case.
      *
      * Extra class for performance reasons.
      */
     public static class SimpleKeyValueCondition extends Condition {
+        /**
+         * The key to search for.
+         */
         public final String k;
+        /**
+         * The value to search for.
+         */
         public final String v;
 
+        /**
+         * Create a new SimpleKeyValueCondition.
+         * @param k The key
+         * @param v The value.
+         */
         public SimpleKeyValueCondition(String k, String v) {
             this.k = k;
@@ -184 +228 @@
      */
     public static class KeyValueCondition extends Condition {
-
+        /**
+         * The key to search for.
+         */
         public final String k;
+        /**
+         * The value to search for.
+         */
         public final String v;
+        /**
+         * The key/value match operation.
+         */
         public final Op op;
+        /**
+         * If this flag is set, {@link #v} is treated as a key and the value is the value set for that key.
+         */
         public boolean considerValAsKey;
 
@@ -282 +337 @@
     }
 
+    /**
+     * This defines how {@link KeyCondition} matches a given key.
+     */
     public static enum KeyMatchType {
-        EQ, TRUE, FALSE, REGEX
+        /**
+         * The key needs to be equal to the given label.
+         */
+        EQ,
+        /**
+         * The key needs to have a true value (yes, ...)
+         * @see OsmUtils#isTrue(String)
+         */
+        TRUE,
+        /**
+         * The key needs to have a false value (no, ...)
+         * @see OsmUtils#isFalse(String)
+         */
+        FALSE,
+        /**
+         * The key needs to match the given regular expression.
+         */
+        REGEX
     }
 
@@ -307 +382 @@
     public static class KeyCondition extends Condition {
 
+        /**
+         * The key name.
+         */
         public final String label;
+        /**
+         * If we should negate the result of the match.
+         */
         public final boolean negateResult;
+        /**
+         * Describes how to match the label against the key.
+         * @see KeyMatchType
+         */
         public final KeyMatchType matchType;
-        public Predicate<String> containsPattern;
-
+        /**
+         * A predicate used to match a the regexp against the key. Only used if the match type is regexp.
+         */
+        public final Predicate<String> containsPattern;
+
+        /**
+         * Creates a new KeyCondition
+         * @param label The key name (or regexp) to use.
+         * @param negateResult If we should negate the result.,
+         * @param matchType The match type.
+         */
         public KeyCondition(String label, boolean negateResult, KeyMatchType matchType) {
             this.label = label;
             this.negateResult = negateResult;
-            this.matchType = matchType;
+            this.matchType = matchType == null ? KeyMatchType.EQ : matchType;
             this.containsPattern = KeyMatchType.REGEX.equals(matchType)
                     ? Predicates.stringContainsPattern(Pattern.compile(label))
@@ -325 +419 @@
             switch(e.getContext()) {
             case PRIMITIVE:
-                if (KeyMatchType.TRUE.equals(matchType))
+                switch (matchType) {
+                case TRUE:
                     return e.osm.isKeyTrue(label) ^ negateResult;
-                else if (KeyMatchType.FALSE.equals(matchType))
+                case FALSE:
                     return e.osm.isKeyFalse(label) ^ negateResult;
-                else if (KeyMatchType.REGEX.equals(matchType)) {
+                case REGEX:
                     return Utils.exists(e.osm.keySet(), containsPattern) ^ negateResult;
-                } else {
+                default:
                     return e.osm.hasKey(label) ^ negateResult;
                 }
@@ -341 +436 @@
         }
 
+        /**
+         * Get the matched key and the corresponding value.
+         * <p>
+         * WARNING: This ignores {@link #negateResult}.
+         * <p>
+         * WARNING: For regexp, the regular expression is returned instead of a key if the match failed.
+         * @param p The primitive to get the value from.
+         * @return The tag.
+         */
         public Tag asTag(OsmPrimitive p) {
             String key = label;