Changeset 8654 in josm for trunk/src/org


Ignore:
Timestamp:
2015-08-09T23:22:36+02:00 (9 years ago)
Author:
Don-vip
Message:

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

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r8612 r8654  
    1616import org.openstreetmap.josm.data.osm.Node;
    1717import org.openstreetmap.josm.data.osm.OsmPrimitive;
     18import org.openstreetmap.josm.data.osm.OsmUtils;
    1819import org.openstreetmap.josm.data.osm.Relation;
    1920import org.openstreetmap.josm.data.osm.Tag;
    … …  
    8384    }
    8485
     86    /**
     87     * This is the operation that {@link KeyValueCondition} uses to match.
     88     */
    8589    public static enum Op {
    86         EQ, NEQ, GREATER_OR_EQUAL, GREATER, LESS_OR_EQUAL, LESS,
    87         REGEX, NREGEX, ONE_OF, BEGINS_WITH, ENDS_WITH, CONTAINS;
     90        /** The value equals the given reference. */
     91        EQ,
     92        /** The value does not equal the reference. */
     93        NEQ,
     94        /** The value is greater than or equal to the given reference value (as float). */
     95        GREATER_OR_EQUAL,
     96        /** The value is greater than the given reference value (as float). */
     97        GREATER,
     98        /** The value is less than or equal to the given reference value (as float). */
     99        LESS_OR_EQUAL,
     100        /** The value is less than the given reference value (as float). */
     101        LESS,
     102        /** The reference is treated as regular expression and the value needs to match it. */
     103        REGEX,
     104        /** The reference is treated as regular expression and the value needs to not match it. */
     105        NREGEX,
     106        /** The reference is treated as a list separated by ';'. Spaces around the ; are ignored.
     107         *  The value needs to be equal one of the list elements. */
     108        ONE_OF,
     109        /** The value needs to begin with the reference string. */
     110        BEGINS_WITH,
     111        /** The value needs to end with the reference string. */
     112        ENDS_WITH,
     113         /** The value needs to contain the reference string. */
     114        CONTAINS;
    88115
    89116        public static final Set<Op> NEGATED_OPS = EnumSet.of(NEQ, NREGEX);
    90117
     118        /**
     119         * Evaluates a value against a reference string.
     120         * @param testString The value. May be <code>null</code>
     121         * @param prototypeString The reference string-
     122         * @return <code>true</code> if and only if this operation matches for the given value/reference pair.
     123         */
    91124        public boolean eval(String testString, String prototypeString) {
    92125            if (testString == null && !NEGATED_OPS.contains(this))
    … …  
    150183
    151184    /**
    152      * Most common case of a KeyValueCondition.
     185     * Most common case of a KeyValueCondition, this is the basic key=value case.
    153186     *
    154187     * Extra class for performance reasons.
    155188     */
    156189    public static class SimpleKeyValueCondition extends Condition {
     190        /**
     191         * The key to search for.
     192         */
    157193        public final String k;
     194        /**
     195         * The value to search for.
     196         */
    158197        public final String v;
    159198
     199        /**
     200         * Create a new SimpleKeyValueCondition.
     201         * @param k The key
     202         * @param v The value.
     203         */
    160204        public SimpleKeyValueCondition(String k, String v) {
    161205            this.k = k;
    … …  
    184228     */
    185229    public static class KeyValueCondition extends Condition {
    186 
     230        /**
     231         * The key to search for.
     232         */
    187233        public final String k;
     234        /**
     235         * The value to search for.
     236         */
    188237        public final String v;
     238        /**
     239         * The key/value match operation.
     240         */
    189241        public final Op op;
     242        /**
     243         * If this flag is set, {@link #v} is treated as a key and the value is the value set for that key.
     244         */
    190245        public boolean considerValAsKey;
    191246
    … …  
    282337    }
    283338
     339    /**
     340     * This defines how {@link KeyCondition} matches a given key.
     341     */
    284342    public static enum KeyMatchType {
    285         EQ, TRUE, FALSE, REGEX
     343        /**
     344         * The key needs to be equal to the given label.
     345         */
     346        EQ,
     347        /**
     348         * The key needs to have a true value (yes, ...)
     349         * @see OsmUtils#isTrue(String)
     350         */
     351        TRUE,
     352        /**
     353         * The key needs to have a false value (no, ...)
     354         * @see OsmUtils#isFalse(String)
     355         */
     356        FALSE,
     357        /**
     358         * The key needs to match the given regular expression.
     359         */
     360        REGEX
    286361    }
    287362
    … …  
    307382    public static class KeyCondition extends Condition {
    308383
     384        /**
     385         * The key name.
     386         */
    309387        public final String label;
     388        /**
     389         * If we should negate the result of the match.
     390         */
    310391        public final boolean negateResult;
     392        /**
     393         * Describes how to match the label against the key.
     394         * @see KeyMatchType
     395         */
    311396        public final KeyMatchType matchType;
    312         public Predicate<String> containsPattern;
    313 
     397        /**
     398         * A predicate used to match a the regexp against the key. Only used if the match type is regexp.
     399         */
     400        public final Predicate<String> containsPattern;
     401
     402        /**
     403         * Creates a new KeyCondition
     404         * @param label The key name (or regexp) to use.
     405         * @param negateResult If we should negate the result.,
     406         * @param matchType The match type.
     407         */
    314408        public KeyCondition(String label, boolean negateResult, KeyMatchType matchType) {
    315409            this.label = label;
    316410            this.negateResult = negateResult;
    317             this.matchType = matchType;
     411            this.matchType = matchType == null ? KeyMatchType.EQ : matchType;
    318412            this.containsPattern = KeyMatchType.REGEX.equals(matchType)
    319413                    ? Predicates.stringContainsPattern(Pattern.compile(label))
    … …  
    325419            switch(e.getContext()) {
    326420            case PRIMITIVE:
    327                 if (KeyMatchType.TRUE.equals(matchType))
     421                switch (matchType) {
     422                case TRUE:
    328423                    return e.osm.isKeyTrue(label) ^ negateResult;
    329                 else if (KeyMatchType.FALSE.equals(matchType))
     424                case FALSE:
    330425                    return e.osm.isKeyFalse(label) ^ negateResult;
    331                 else if (KeyMatchType.REGEX.equals(matchType)) {
     426                case REGEX:
    332427                    return Utils.exists(e.osm.keySet(), containsPattern) ^ negateResult;
    333                 } else {
     428                default:
    334429                    return e.osm.hasKey(label) ^ negateResult;
    335430                }
    … …  
    341436        }
    342437
     438        /**
     439         * Get the matched key and the corresponding value.
     440         * <p>
     441         * WARNING: This ignores {@link #negateResult}.
     442         * <p>
     443         * WARNING: For regexp, the regular expression is returned instead of a key if the match failed.
     444         * @param p The primitive to get the value from.
     445         * @return The tag.
     446         */
    343447        public Tag asTag(OsmPrimitive p) {
    344448            String key = label;
Note: See TracChangeset for help on using the changeset viewer.