Change ContextSet 'satisfy' behaviour (#2300)

api/src/main/java/net/luckperms/api/context/ContextSatisfyMode.java

@@ -0,0 +1,63 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package net.luckperms.api.context;
+
+import net.luckperms.api.query.OptionKey;
+
+/**
+ * Mode for determining whether a {@link ContextSet} satisfies another.
+ *
+ * @since 5.2
+ * @see ContextSet#isSatisfiedBy(ContextSet, ContextSatisfyMode)
+ */
+public enum ContextSatisfyMode {
+
+    /**
+     * Mode where a {@link ContextSet} A will be satisfied by another set B, if at least one of the
+     * key-value entries per key in A are also in B.
+     *
+     * <p>For example, given <code>A = {server=survival, world=overworld, world=nether}</code>,
+     * another set {@code X} will satisfy {@code A} if {@code X} contains
+     * <code>server=survival AND (world=overworld OR world=nether)</code>.</p>
+     */
+    AT_LEAST_ONE_VALUE_PER_KEY,
+
+    /**
+     * Mode where a {@link ContextSet} A will be satisfied by another set B, if all key-value
+     * entries in A are also in B.
+     *
+     * <p>For example, given <code>A = {server=survival, world=overworld, world=nether}</code>,
+     * another set {@code X} will satisfy {@code A} if {@code X} contains
+     * <code>server=survival AND world=overworld AND world=nether</code>.</p>
+     */
+    ALL_VALUES_PER_KEY;
+
+    /**
+     * The {@link OptionKey} for {@link ContextSatisfyMode}.
+     */
+    public static final OptionKey<ContextSatisfyMode> KEY = OptionKey.of("contextsatisfymode", ContextSatisfyMode.class);
+
+}

api/src/main/java/net/luckperms/api/context/ContextSet.java

@@ -197,17 +197,47 @@ public interface ContextSet extends Iterable<Context> {
     }
 
     /**
-     * Returns if this {@link ContextSet} is fully "satisfied" by another set.
+     * Returns if the {@link ContextSet} contains any of the given context pairings.
      *
-     * <p>For a context set to "satisfy" another, it must itself contain all of
-     * the context pairings in the other set.</p>
-     *
-     * <p>Mathematically, this method returns true if this set is a <b>subset</b> of the other.</p>
-     *
-     * @param other the other set to check
-     * @return true if all entries in this set are also in the other set
+     * @param key the key to look for
+     * @param values the values to look for
+     * @return true if the set contains any of the pairs
+     * @since 5.2
      */
-    boolean isSatisfiedBy(@NonNull ContextSet other);
+    default boolean containsAny(@NonNull String key, @NonNull Iterable<String> values) {
+        Objects.requireNonNull(key, "key");
+        Objects.requireNonNull(values, "values");
+
+        for (String value : values) {
+            if (contains(key, value)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Returns if this {@link ContextSet} is "satisfied" by another set.
+     *
+     * <p>{@link ContextSatisfyMode#AT_LEAST_ONE_VALUE_PER_KEY} is the mode used by this method.</p>
+     *
+     * @param other the other set
+     * @return true if this context set is satisfied by the other
+     */
+    default boolean isSatisfiedBy(@NonNull ContextSet other) {
+        return isSatisfiedBy(other, ContextSatisfyMode.AT_LEAST_ONE_VALUE_PER_KEY);
+    }
+
+    /**
+     * Returns if this {@link ContextSet} is "satisfied" by another set, according to the given
+     * {@code mode}.
+     *
+     * @param other the other set
+     * @param mode the mode to use
+     * @return true if this context set is satisfied by the other
+     * @since 5.2
+     */
+    boolean isSatisfiedBy(@NonNull ContextSet other, @NonNull ContextSatisfyMode mode);
 
     /**
      * Returns if the {@link ContextSet} is empty.

api/src/main/java/net/luckperms/api/query/QueryOptions.java

@@ -26,6 +26,7 @@
 package net.luckperms.api.query;
 
 import net.luckperms.api.LuckPermsProvider;
+import net.luckperms.api.context.ContextSatisfyMode;
 import net.luckperms.api.context.ContextSet;
 import net.luckperms.api.context.ImmutableContextSet;
 
@@ -166,10 +167,29 @@ public interface QueryOptions {
      * Gets whether this {@link QueryOptions} satisfies the given required
      * {@link ContextSet context}.
      *
+     * <p>{@link ContextSatisfyMode#AT_LEAST_ONE_VALUE_PER_KEY} is used if this {@link QueryOptions}
+     * instance doesn't have the {@link ContextSatisfyMode#KEY option key} set.</p>
+     *
      * @param contextSet the contexts
      * @return the result
      */
-    boolean satisfies(@NonNull ContextSet contextSet);
+    default boolean satisfies(@NonNull ContextSet contextSet) {
+        return satisfies(contextSet, ContextSatisfyMode.AT_LEAST_ONE_VALUE_PER_KEY);
+    }
+
+    /**
+     * Gets whether this {@link QueryOptions} satisfies the given required
+     * {@link ContextSet context}.
+     *
+     * <p>The {@code defaultContextSatisfyMode} parameter is used if this {@link QueryOptions}
+     * instance doesn't have the {@link ContextSatisfyMode#KEY option key} set.</p>
+     *
+     * @param contextSet the contexts
+     * @param defaultContextSatisfyMode the default context satisfy mode to use
+     * @return the result
+     * @since 5.2
+     */
+    boolean satisfies(@NonNull ContextSet contextSet, @NonNull ContextSatisfyMode defaultContextSatisfyMode);
 
     /**
      * Converts this {@link QueryOptions} to a mutable builder.