Upstream

common/placeholders/build.gradle

@@ -0,0 +1,45 @@
+plugins {
+    id("java-library")
+    id("jacoco")
+}
+
+test {
+    useJUnitPlatform()
+}
+
+jacocoTestReport {
+    dependsOn test
+}
+
+dependencies {
+    api project(':api')
+
+    compileOnly 'org.checkerframework:checker-qual:3.49.3'
+    compileOnly 'org.jetbrains:annotations:26.0.2'
+
+    testImplementation 'org.junit.jupiter:junit-jupiter:5.13.0'
+    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
+
+    testImplementation 'org.testcontainers:testcontainers-junit-jupiter:2.0.2'
+    testImplementation 'org.mockito:mockito-core:5.18.0'
+    testImplementation 'org.mockito:mockito-junit-jupiter:5.18.0'
+}
+
+publishing {
+    //repositories {
+    //    maven {
+    //        url = 'https://nexus.lucko.me/repository/maven-snapshots/'
+    //        credentials {
+    //            username = luckoNexusUsername
+    //            password = luckoNexusPassword
+    //        }
+    //    }
+    //}
+    publications {
+        mavenJava(MavenPublication) {
+            from components.java
+            artifactId = 'common-placeholders'
+            version = "${project.ext.fullVersion}-SNAPSHOT"
+        }
+    }
+}

common/placeholders/src/main/java/me/lucko/luckperms/common/placeholders/Placeholder.java

@@ -0,0 +1,117 @@
+/*
+ * 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 me.lucko.luckperms.common.placeholders;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * A placeholder definition.
+ */
+public interface Placeholder {
+
+    /**
+     * Get the id of the placeholder.
+     *
+     * @return the id
+     */
+    @NonNull String id();
+
+    /**
+     * A placeholder function that uses the standard {@link PlaceholderContext}
+     */
+    interface BasicPlaceholderFunction {
+        /**
+         * Resolve the value of this placeholder with some given context.
+         *
+         * @param ctx the context
+         * @return the resolved value
+         */
+        @NonNull String resolve(@NonNull PlaceholderContext ctx);
+    }
+
+    /**
+     * A placeholder function that uses the extended {@link PlaceholderContext.WithArgument}
+     */
+    interface UsingArgumentPlaceholderFunction {
+        /**
+         * Resolve the value of this placeholder with some given context.
+         *
+         * @param ctx the context
+         * @return the resolved value
+         */
+        @NonNull String resolve(PlaceholderContext.@NonNull WithArgument ctx);
+    }
+
+    /** A basic placeholder */
+    interface Basic extends Placeholder, BasicPlaceholderFunction {}
+
+    /** A placeholder that uses an argument */
+    interface UsingArgument extends Placeholder, UsingArgumentPlaceholderFunction {}
+
+    /**
+     * Create a standard placeholder using the given resolver function.
+     *
+     * @param id the id
+     * @param resolver the resolver function
+     * @return the placeholder
+     */
+    static Basic basic(@NonNull String id, Placeholder.@NonNull BasicPlaceholderFunction resolver) {
+        return new Basic() {
+            @Override
+            public @NonNull String id() {
+                return id;
+            }
+
+            @Override
+            public @NotNull String resolve(@NotNull PlaceholderContext ctx) {
+                return resolver.resolve(ctx);
+            }
+        };
+    }
+
+    /**
+     * Create a dynamic placeholder using the given resolver function.
+     *
+     * @param id the id
+     * @param resolver the resolver function
+     * @return the placeholder
+     */
+    static UsingArgument usingArgument(@NonNull String id, Placeholder.@NonNull UsingArgumentPlaceholderFunction resolver) {
+        return new UsingArgument() {
+            @Override
+            public @NonNull String id() {
+                return id;
+            }
+
+            @Override
+            public @NotNull String resolve(PlaceholderContext.@NotNull WithArgument ctx) {
+                return resolver.resolve(ctx);
+            }
+        };
+    }
+
+}

common/placeholders/src/main/java/me/lucko/luckperms/common/placeholders/PlaceholderContext.java

@@ -0,0 +1,110 @@
+/*
+ * 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 me.lucko.luckperms.common.placeholders;
+
+import net.luckperms.api.LuckPerms;
+import net.luckperms.api.cacheddata.CachedDataManager;
+import net.luckperms.api.cacheddata.CachedMetaData;
+import net.luckperms.api.cacheddata.CachedPermissionData;
+import net.luckperms.api.model.user.User;
+import net.luckperms.api.query.QueryOptions;
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * The context passed to a {@link Placeholder} resolve request.
+ */
+public class PlaceholderContext {
+
+    /** The LuckPerms API instance */
+    private final @NonNull LuckPerms api;
+    /** The user for the player the placeholder is being resolved for */
+    private final @NonNull User user;
+    /** The query options for the player the placeholder is being resolved for */
+    private final @NonNull QueryOptions queryOptions;
+
+    public PlaceholderContext(@NonNull LuckPerms api, @NonNull User user, @NonNull QueryOptions queryOptions) {
+        this.api = api;
+        this.user = user;
+        this.queryOptions = queryOptions;
+    }
+
+    public @NonNull LuckPerms api() {
+        return this.api;
+    }
+
+    public @NonNull User user() {
+        return this.user;
+    }
+
+    public @NonNull QueryOptions queryOptions() {
+        return this.queryOptions;
+    }
+
+    public @NonNull CachedDataManager userData() {
+        return this.user.getCachedData();
+    }
+
+    public @NonNull CachedPermissionData permissionData() {
+        return this.user.getCachedData().getPermissionData(this.queryOptions);
+    }
+
+    public @NonNull CachedMetaData metaData() {
+        return this.user.getCachedData().getMetaData(this.queryOptions);
+    }
+
+    /**
+     * Create a copy of this placeholder context, additionally including an argument.
+     *
+     * @param argument the argument
+     * @return the new context
+     */
+    public WithArgument withArgument(@NonNull String argument) {
+        return new WithArgument(this.api, this.user, this.queryOptions, argument);
+    }
+
+    /**
+     * Extension of {@link PlaceholderContext} with an extra dynamic argument provided by the requester.
+     */
+    public static class WithArgument extends PlaceholderContext {
+
+        /** An additional argument passed to the placeholder resolve request */
+        private final @NonNull String argument;
+
+        public WithArgument(@NonNull LuckPerms api, @NonNull User user, @NonNull QueryOptions queryOptions, @NonNull String argument) {
+            super(api, user, queryOptions);
+            this.argument = argument;
+        }
+
+        /**
+         * Gets the argument.
+         *
+         * @return the argument
+         */
+        public @NonNull String argument() {
+            return this.argument;
+        }
+    }
+}

common/placeholders/src/main/java/me/lucko/luckperms/common/placeholders/PlaceholderRegistry.java

@@ -0,0 +1,100 @@
+/*
+ * 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 me.lucko.luckperms.common.placeholders;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.function.Function;
+import java.util.stream.Collectors;
+
+/**
+ * A registry of standard/built-in {@link Placeholder}s.
+ */
+public class PlaceholderRegistry {
+
+    private static final List<Placeholder> PLACEHOLDERS = Collections.unmodifiableList(Arrays.asList(
+            Placeholders.PREFIX,
+            Placeholders.SUFFIX,
+            Placeholders.ALL_META,
+            Placeholders.META,
+            Placeholders.PREFIX_ELEMENT,
+            Placeholders.SUFFIX_ELEMENT,
+            Placeholders.ALL_CONTEXT,
+            Placeholders.CONTEXT,
+            Placeholders.GROUPS,
+            Placeholders.INHERITED_GROUPS,
+            Placeholders.PRIMARY_GROUP_NAME,
+            Placeholders.HAS_PERMISSION,
+            Placeholders.INHERITS_PERMISSION,
+            Placeholders.CHECK_PERMISSION,
+            Placeholders.IN_GROUP,
+            Placeholders.INHERITS_GROUP,
+            Placeholders.ON_TRACK,
+            Placeholders.HAS_GROUPS_ON_TRACK,
+            Placeholders.HIGHEST_GROUP_BY_WEIGHT,
+            Placeholders.LOWEST_GROUP_BY_WEIGHT,
+            Placeholders.HIGHEST_INHERITED_GROUP_BY_WEIGHT,
+            Placeholders.LOWEST_INHERITED_GROUP_BY_WEIGHT,
+            Placeholders.HIGHEST_GROUP_WEIGHT,
+            Placeholders.CURRENT_GROUP_ON_TRACK,
+            Placeholders.NEXT_GROUP_ON_TRACK,
+            Placeholders.PREVIOUS_GROUP_ON_TRACK,
+            Placeholders.FIRST_GROUP_ON_TRACKS,
+            Placeholders.LAST_GROUP_ON_TRACKS,
+            Placeholders.EXPIRY_TIME,
+            Placeholders.INHERITED_EXPIRY_TIME,
+            Placeholders.GROUP_EXPIRY_TIME,
+            Placeholders.INHERITED_GROUP_EXPIRY_TIME
+    ));
+
+    private static final Map<String, Placeholder> PLACEHOLDER_MAP = PLACEHOLDERS.stream()
+            .collect(Collectors.toMap(Placeholder::id, Function.identity()));
+
+    /**
+     * Get a list of all placeholders.
+     *
+     * @return a list of placeholders
+     */
+    public static @NonNull List<Placeholder> getAll() {
+        return PLACEHOLDERS;
+    }
+
+    /**
+     * Lookup a placeholder by id.
+     *
+     * @param id the id to lookup
+     * @return the placeholder, if found
+     */
+    public static @Nullable Placeholder lookup(@NonNull String id) {
+        return PLACEHOLDER_MAP.get(id);
+    }
+
+}