Merge pull request #330 from gastaldi/range

Introduce `VersionRange`

version/pom.xml

@@ -1,5 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
 
     <parent>
@@ -39,6 +40,12 @@
             <artifactId>junit-jupiter</artifactId>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+
         <!-- so we can compare our version comparison algorithm against Maven's -->
         <dependency>
             <groupId>org.apache.maven.resolver</groupId>

version/src/main/java/io/smallrye/common/version/Messages.java

@@ -44,4 +44,26 @@ interface Messages {
 
     @Message(id = 3010, value = "Build string may not be empty")
     VersionSyntaxException emptyBuild();
+
+    @Message(id = 3011, value = "Unbounded range: %s")
+    IllegalArgumentException unboundedRange(String pattern);
+
+    // 3012
+
+    // 3013
+
+    @Message(id = 3014, value = "Single version must be surrounded by []: %s")
+    IllegalArgumentException singleVersionMustBeSurroundedByBrackets(String version);
+
+    @Message(id = 3015, value = "Range defies version ordering: %s")
+    IllegalArgumentException rangeDefiesVersionOrdering(String version);
+
+    @Message(id = 3016, value = "Unexpected version range character: %s")
+    IllegalArgumentException rangeUnexpected(String version);
+
+    @Message(id = 3017, value = "Standalone version cannot have an upper bound")
+    IllegalArgumentException standaloneVersionCannotBeBound();
+
+    @Message(id = 3018, value = "Inclusive versions cannot be empty")
+    IllegalArgumentException inclusiveVersionCannotBeEmpty();
 }

version/src/main/java/io/smallrye/common/version/VersionScheme.java

@@ -1,6 +1,8 @@
 package io.smallrye.common.version;
 
 import java.util.Comparator;
+import java.util.Objects;
+import java.util.function.Predicate;
 
 /**
  * A versioning scheme, which has distinct sorting, iteration, and canonicalization rules.
@@ -17,6 +19,181 @@ public interface VersionScheme extends Comparator<String> {
      */
     int compare(String v1, String v2);
 
+    /**
+     * Determine if the first version is less than the second version according to this version scheme.
+     *
+     * @param base the base version
+     * @param other the other version
+     * @return {@code true} if the first version is less than the second version, or {@code false} otherwise
+     */
+    default boolean lt(String base, String other) {
+        return compare(base, other) < 0;
+    }
+
+    /**
+     * Determine if the first version is less than or equal to the second version according to this version scheme.
+     *
+     * @param base the base version
+     * @param other the other version
+     * @return {@code true} if the first version is less than or equal to the second version, or {@code false} otherwise
+     */
+    default boolean le(String base, String other) {
+        return compare(base, other) <= 0;
+    }
+
+    /**
+     * Determine if the first version is greater than or equal to the second version according to this version scheme.
+     *
+     * @param base the base version
+     * @param other the other version
+     * @return {@code true} if the first version is greater than or equal to the second version, or {@code false} otherwise
+     */
+    default boolean gt(String base, String other) {
+        return compare(base, other) > 0;
+    }
+
+    /**
+     * Determine if the first version is greater than the second version according to this version scheme.
+     *
+     * @param base the base version
+     * @param other the other version
+     * @return {@code true} if the first version is greater than the second version, or {@code false} otherwise
+     */
+    default boolean ge(String base, String other) {
+        return compare(base, other) >= 0;
+    }
+
+    /**
+     * {@return the lesser (earlier) of the two versions}
+     *
+     * @param a the first version (must not be {@code null})
+     * @param b the second version (must not be {@code null})
+     */
+    default String min(String a, String b) {
+        return le(a, b) ? a : b;
+    }
+
+    /**
+     * {@return the greater (later) of the two versions}
+     *
+     * @param a the first version (must not be {@code null})
+     * @param b the second version (must not be {@code null})
+     */
+    default String max(String a, String b) {
+        return ge(a, b) ? a : b;
+    }
+
+    /**
+     * Returns a predicate that tests if the version is equal to the base version.
+     *
+     * @param other the other version
+     * @return {@code true} if the first version is equal to the second version, or {@code false} otherwise
+     */
+    default Predicate<String> whenEquals(String other) {
+        return base -> equals(base, other);
+    }
+
+    /**
+     * Returns a predicate that tests if the version is greater than or equal to the base version.
+     *
+     * @param other the other version
+     * @return {@code true} if the first version is less than the second version, or {@code false} otherwise
+     */
+    default Predicate<String> whenGt(String other) {
+        return base -> gt(base, other);
+    }
+
+    /**
+     * Returns a predicate that tests if the version is greater than or equal to the base version.
+     *
+     * @param other the other version
+     * @return a predicate that tests if the version is greater than or equal to the base version
+     */
+    default Predicate<String> whenGe(String other) {
+        return base -> ge(base, other);
+    }
+
+    /**
+     * Returns a predicate that tests if the version is less than or equal to the base version.
+     *
+     * @param other the other version
+     * @return a predicate that tests if the version is less than or equal to the base version
+     */
+    default Predicate<String> whenLe(String other) {
+        return base -> le(base, other);
+    }
+
+    /**
+     * Returns a predicate that tests if the version is less than the base version.
+     *
+     * @param other the other version
+     * @return a predicate that tests if the version is less than the base version
+     */
+    default Predicate<String> whenLt(String other) {
+        return base -> lt(base, other);
+    }
+
+    /**
+     * Parse a range specification and return it as a predicate.
+     * This method behaves as a call to {@link #fromRangeString(String, int, int) fromRangeString(range, 0, range.length())}.
+     *
+     * @param range the range string to parse (must not be {@code null})
+     * @return the parsed range (not {@code null})
+     * @throws IllegalArgumentException if there is a syntax error in the range or the range cannot match any version
+     */
+    default Predicate<String> fromRangeString(String range) {
+        return fromRangeString(range, 0, range.length());
+    }
+
+    // @formatter:off
+    /**
+     * Parse a range specification and return it as a predicate.
+     * Version ranges are governed by the following general syntax:
+     * <code><pre>
+range ::= range-spec ',' range
+        | range-spec
+
+range-spec ::= '[' version ']
+             | min-version ',' max-version
+
+min-version ::= '[' version
+              | '(' version
+              | '('
+
+max-version ::= version ']'
+              | version ')'
+              | ')'
+</pre></code>
+     * This is aligned with the syntax used by Maven, however it can be applied to any
+     * supported version scheme.
+     * <p>
+     * It is important to note that within a range specification, the {@code ,} separator
+     * indicates a logical "and" or "intersection" operation, whereas the {@code ,} separator
+     * found in between range specifications acts as a logical "or" or "union" operation.
+     * <p>
+     * Here are some examples of valid version range specifications:
+     * <ul>
+     * <li><code>1.0</code> Version 1.0 as a recommended version (like {@code whenEquals("1.0")})</li>
+     * <li><code>[1.0]</code> Version 1.0 explicitly only (like {@code whenEquals("1.0")})</li>
+     * <li><code>[1.0,2.0)</code> Versions 1.0 (included) to 2.0 (not included) (like {@code whenGe("1.0").and(whenLt("2.0"))})</li>
+     * <li><code>[1.0,2.0]</code> Versions 1.0 to 2.0 (both included) (like {@code whenGe("1.0").and(whenLe("2.0"))})</li>
+     * <li><code>[1.5,)</code> Versions 1.5 and higher (like {@code whenGe("1.5")})</li>
+     * <li><code>(,1.0],[1.2,)</code> Versions up to 1.0 (included) and 1.2 or higher (like {@code whenLe("1.0").or(whenGe("1.2"))})</li>
+     * </ul>
+     *
+     * @param range the range string to parse (must not be {@code null})
+     * @param start the start of the range within the string (inclusive)
+     * @param end the end of the range within the string (exclusive)
+     * @return the parsed range (not {@code null})
+     * @throws IllegalArgumentException if there is a syntax error in the range or the range cannot match any version
+     * @throws IndexOutOfBoundsException if the values for {@code start} or {@code end} are not valid
+     */
+    // @formatter:on
+    default Predicate<String> fromRangeString(String range, int start, int end) {
+        Objects.checkFromToIndex(start, end, range.length());
+        return parseRange(range, start, end);
+    }
+
     /**
      * Determine if two versions are equal according to this version scheme.
      *
@@ -131,4 +308,156 @@ default void validate(String version) throws VersionSyntaxException {
      * This versioning scheme is based approximately on semantic versioning but with a few differences.
      */
     VersionScheme JPMS = new JpmsVersionScheme();
+
+    private Predicate<String> parseRange(final String range, int start, final int end) {
+        if (start == end) {
+            return whenEquals("");
+        }
+        int cp = range.codePointAt(start);
+        int cnt = Character.charCount(cp);
+        switch (cp) {
+            case '[': {
+                return parseMinIncl(range, start + cnt, end);
+            }
+            case '(': {
+                return parseMinExcl(range, start + cnt, end);
+            }
+            case ',': {
+                return parseMore(whenEquals(""), range, start + cnt, end);
+            }
+            default: {
+                return parseSingle(range, start + cnt, end);
+            }
+        }
+    }
+
+    private Predicate<String> parseSingle(String range, int start, int end) {
+        int i = start;
+        int cp, cnt;
+        do {
+            cp = range.codePointAt(i);
+            cnt = Character.charCount(cp);
+            switch (cp) {
+                case ',': {
+                    return parseMore(whenEquals(range.substring(start, i)), range, i + cnt, end);
+                }
+                case ']':
+                case ')': {
+                    throw Messages.msg.standaloneVersionCannotBeBound();
+                }
+            }
+            i += cnt;
+        } while (i < end);
+        // just a single version
+        return whenEquals(range.substring(start, end));
+    }
+
+    private Predicate<String> parseMinIncl(String range, int start, int end) {
+        int i = start;
+        int cp;
+        do {
+            cp = range.codePointAt(i);
+            int cnt = Character.charCount(cp);
+            switch (cp) {
+                case ',': {
+                    if (i == start) {
+                        throw Messages.msg.inclusiveVersionCannotBeEmpty();
+                    }
+                    return parseRangeMax(whenGe(range.substring(start, i)), range, i + cnt, end);
+                }
+                case ']': {
+                    return parseMore(whenEquals(range.substring(start, i)), range, i + cnt, end);
+                }
+                case ')': {
+                    throw Messages.msg.singleVersionMustBeSurroundedByBrackets(range.substring(start, i + cnt));
+                }
+            }
+            i += cnt;
+        } while (i < end);
+        // ended short, so treat it as open-ended
+        return whenGe(range.substring(start, end));
+    }
+
+    private Predicate<String> parseMinExcl(String range, int start, int end) {
+        int i = start;
+        int cp;
+        do {
+            cp = range.codePointAt(i);
+            int cnt = Character.charCount(cp);
+            switch (cp) {
+                case ',': {
+                    if (i == start) {
+                        // include all
+                        return parseRangeMax(null, range, i + cnt, end);
+                    } else {
+                        return parseRangeMax(whenGt(range.substring(start, i)), range, i + cnt, end);
+                    }
+                }
+                case ']':
+                case ')': {
+                    throw Messages.msg.singleVersionMustBeSurroundedByBrackets(range.substring(start, i + cnt));
+                }
+            }
+            i += cnt;
+        } while (i < end);
+        // ended short, so treat it as open-ended
+        return whenGt(range.substring(start, end));
+    }
+
+    private Predicate<String> parseRangeMax(Predicate<String> min, String range, int start, int end) {
+        int i = start;
+        int cp;
+        do {
+            cp = range.codePointAt(i);
+            int cnt = Character.charCount(cp);
+            switch (cp) {
+                case ')': {
+                    if (i == start) {
+                        // empty upper range; only consider the minimum range
+                        return parseMore(min, range, i + cnt, end);
+                    }
+                    // fall through
+                }
+                case ']': {
+                    String high = range.substring(start, i);
+                    if (min != null && !min.test(high)) {
+                        // low end must be higher than high end
+                        throw Messages.msg.rangeDefiesVersionOrdering(range.substring(start, i + cnt));
+                    }
+                    Predicate<String> max = cp == ']' ? whenLe(high) : whenLt(high);
+                    return parseMore(min == null ? max : min.and(max), range, i + cnt, end);
+                }
+                case ',': {
+                    throw Messages.msg.rangeUnexpected(range.substring(start, i + cnt));
+                }
+            }
+            i += cnt;
+        } while (i < end);
+        // ended short
+        throw Messages.msg.unboundedRange(range.substring(start, end));
+    }
+
+    /**
+     * Parse the end context (make sure there is no trailing garbage, combine subsequent predicates).
+     *
+     * @param predicate the predicate to return
+     * @param range the range string
+     * @param start the remaining start
+     * @param end the end
+     * @return the predicate
+     */
+    private Predicate<String> parseMore(Predicate<String> predicate, final String range, int start, int end) {
+        if (start < end) {
+            int cp = range.codePointAt(start);
+            int cnt = Character.charCount(cp);
+            if (cp == ',') {
+                // composed version ranges
+                Predicate<String> nextRange = parseRange(range, start + cnt, end);
+                return predicate == null ? nextRange : predicate.or(nextRange);
+            }
+            throw Messages.msg.rangeUnexpected(range.substring(start, start + cnt));
+        } else {
+            return predicate;
+        }
+    }
 }