api: Add the ability to query an Audience for a value based on a Poin…

…ter key

.checkstyle/suppressions.xml

@@ -1,6 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE suppressions PUBLIC "-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN" "http://checkstyle.org/dtds/suppressions_1_2.dtd">
 <suppressions>
+  <!-- let me be excited, checkstyle! -->
+  <suppress files="api[\\/]src[\\/]main[\\/]java[\\/]net[\\/]kyori[\\/]adventure[\\/]Adventure.java" checks="SummaryJavadoc"/>
+
   <!-- no javadoc on test classes -->
   <suppress files="src[\\/]test[\\/]java[\\/].*" checks="FilteringWriteTag"/>
   <suppress files="src[\\/]test[\\/]java[\\/].*" checks="MissingJavadoc.*"/>

api/src/main/java/net/kyori/adventure/Adventure.java

@@ -0,0 +1,44 @@
+/*
+ * This file is part of adventure, licensed under the MIT License.
+ *
+ * Copyright (c) 2017-2021 KyoriPowered
+ *
+ * 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.kyori.adventure;
+
+import net.kyori.adventure.key.Key;
+
+/**
+ * We're going on an Adventure!
+ *
+ * @since 4.8.0
+ */
+public final class Adventure {
+  /**
+   * The namespace.
+   *
+   * @see Key
+   * @since 4.8.0
+   */
+  public static final String NAMESPACE = "adventure";
+
+  private Adventure() {
+  }
+}

api/src/main/java/net/kyori/adventure/audience/Audience.java

@@ -26,14 +26,15 @@
 import java.util.Arrays;
 import java.util.stream.Collector;
 import net.kyori.adventure.bossbar.BossBar;
+import net.kyori.adventure.identity.Identified;
 import net.kyori.adventure.identity.Identity;
 import net.kyori.adventure.inventory.Book;
+import net.kyori.adventure.pointer.Pointered;
 import net.kyori.adventure.sound.Sound;
 import net.kyori.adventure.sound.SoundStop;
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.text.ComponentLike;
 import net.kyori.adventure.title.Title;
-import net.kyori.adventure.identity.Identified;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
@@ -77,7 +78,7 @@
  * @see ForwardingAudience
  * @since 4.0.0
  */
-public interface Audience {
+public interface Audience extends Pointered {
   /**
    * Gets an audience that does nothing.
    *

api/src/main/java/net/kyori/adventure/audience/EmptyAudience.java

@@ -23,15 +23,34 @@
  */
 package net.kyori.adventure.audience;
 
+import java.util.Optional;
+import java.util.function.Supplier;
 import net.kyori.adventure.identity.Identity;
 import net.kyori.adventure.inventory.Book;
+import net.kyori.adventure.pointer.Pointer;
 import net.kyori.adventure.text.ComponentLike;
 import net.kyori.adventure.identity.Identified;
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.PolyNull;
 
 final class EmptyAudience implements Audience {
   static final EmptyAudience INSTANCE = new EmptyAudience();
 
+  @Override
+  public @NonNull <T> Optional<T> get(final @NonNull Pointer<T> pointer) {
+    return Optional.empty();
+  }
+
+  @Override
+  public <T> @PolyNull T getOrDefault(final @NonNull Pointer<T> pointer, final @PolyNull T defaultValue) {
+    return defaultValue;
+  }
+
+  @Override
+  public <T> @PolyNull T getOrDefaultFrom(final @NonNull Pointer<T> pointer, final @NonNull Supplier<? extends T> defaultValue) {
+    return defaultValue.get();
+  }
+
   @Override
   public void sendMessage(final @NonNull ComponentLike message) {
   }

api/src/main/java/net/kyori/adventure/audience/ForwardingAudience.java

@@ -24,6 +24,9 @@
 package net.kyori.adventure.audience;
 
 import java.util.Collections;
+import java.util.Optional;
+import java.util.function.Supplier;
+import net.kyori.adventure.pointer.Pointer;
 import net.kyori.adventure.bossbar.BossBar;
 import net.kyori.adventure.identity.Identified;
 import net.kyori.adventure.identity.Identity;
@@ -33,6 +36,7 @@
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.title.Title;
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.PolyNull;
 import org.jetbrains.annotations.ApiStatus;
 
 /**
@@ -55,6 +59,21 @@ public interface ForwardingAudience extends Audience {
   @ApiStatus.OverrideOnly
   @NonNull Iterable<? extends Audience> audiences();
 
+  @Override
+  default <T> @NonNull Optional<T> get(final @NonNull Pointer<T> pointer) {
+    return Optional.empty(); // unsupported
+  }
+
+  @Override
+  default <T> @PolyNull T getOrDefault(final @NonNull Pointer<T> pointer, final @PolyNull T defaultValue) {
+    return defaultValue; // unsupported
+  }
+
+  @Override
+  default <T> @PolyNull T getOrDefaultFrom(final @NonNull Pointer<T> pointer, final @NonNull Supplier<? extends T> defaultValue) {
+    return defaultValue.get(); // unsupported
+  }
+
   @Override
   default void sendMessage(final @NonNull Identified source, final @NonNull Component message, final @NonNull MessageType type) {
     for(final Audience audience : this.audiences()) audience.sendMessage(source, message, type);
@@ -157,6 +176,11 @@ interface Single extends ForwardingAudience {
       return Collections.singleton(this.audience());
     }
 
+    @Override
+    default <T> @NonNull Optional<T> get(final @NonNull Pointer<T> pointer) {
+      return this.audience().get(pointer);
+    }
+
     @Override
     default void sendMessage(final @NonNull Identified source, final @NonNull Component message, final @NonNull MessageType type) {
       this.audience().sendMessage(source, message, type);

api/src/main/java/net/kyori/adventure/identity/Identity.java

@@ -25,6 +25,10 @@
 
 import java.util.UUID;
 import java.util.stream.Stream;
+import net.kyori.adventure.Adventure;
+import net.kyori.adventure.key.Key;
+import net.kyori.adventure.pointer.Pointer;
+import net.kyori.adventure.text.Component;
 import net.kyori.examination.Examinable;
 import net.kyori.examination.ExaminableProperty;
 import org.checkerframework.checker.nullness.qual.NonNull;
@@ -37,6 +41,25 @@
  * @sinceMinecraft 1.16
  */
 public interface Identity extends Examinable {
+  /**
+   * A pointer to a name.
+   *
+   * @since 4.8.0
+   */
+  Pointer<String> NAME = Pointer.pointer(String.class, Key.key(Adventure.NAMESPACE, "name"));
+  /**
+   * A pointer to a {@link UUID}.
+   *
+   * @since 4.8.0
+   */
+  Pointer<UUID> UUID = Pointer.pointer(UUID.class, Key.key(Adventure.NAMESPACE, "uuid"));
+  /**
+   * A pointer to a display name.
+   *
+   * @since 4.8.0
+   */
+  Pointer<Component> DISPLAY_NAME = Pointer.pointer(Component.class, Key.key(Adventure.NAMESPACE, "display_name"));
+
   /**
    * Gets the {@code null} identity.
    *

api/src/main/java/net/kyori/adventure/permission/PermissionChecker.java

@@ -0,0 +1,72 @@
+/*
+ * This file is part of adventure, licensed under the MIT License.
+ *
+ * Copyright (c) 2017-2021 KyoriPowered
+ *
+ * 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.kyori.adventure.permission;
+
+import java.util.function.Predicate;
+import net.kyori.adventure.Adventure;
+import net.kyori.adventure.key.Key;
+import net.kyori.adventure.pointer.Pointer;
+import net.kyori.adventure.util.TriState;
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Something that has permissions.
+ *
+ * @since 4.8.0
+ */
+public interface PermissionChecker extends Predicate<String> {
+  /**
+   * A pointer to a permission predicate.
+   *
+   * @since 4.8.0
+   */
+  Pointer<PermissionChecker> POINTER = Pointer.pointer(PermissionChecker.class, Key.key(Adventure.NAMESPACE, "permission"));
+
+  /**
+   * Creates a {@link PermissionChecker} that always returns {@code state}.
+   *
+   * @param state the state
+   * @return a {@link PermissionChecker}
+   * @since 4.8.0
+   */
+  static @NonNull PermissionChecker always(final TriState state) {
+    if(state == TriState.TRUE) return PermissionCheckers.TRUE;
+    if(state == TriState.FALSE) return PermissionCheckers.FALSE;
+    return PermissionCheckers.NOT_SET;
+  }
+
+  /**
+   * Checks if something has a permission.
+   *
+   * @param permission the permission
+   * @return a tri-state result
+   * @since 4.8.0
+   */
+  @NonNull TriState value(final String permission);
+
+  @Override
+  default boolean test(final String permission) {
+    return this.value(permission) == TriState.TRUE;
+  }
+}

api/src/main/java/net/kyori/adventure/permission/PermissionCheckers.java

@@ -0,0 +1,51 @@
+/*
+ * This file is part of adventure, licensed under the MIT License.
+ *
+ * Copyright (c) 2017-2021 KyoriPowered
+ *
+ * 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.kyori.adventure.permission;
+
+import net.kyori.adventure.util.TriState;
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+final class PermissionCheckers {
+  static final PermissionChecker NOT_SET = new Always(TriState.NOT_SET);
+  static final PermissionChecker FALSE = new Always(TriState.FALSE);
+  static final PermissionChecker TRUE = new Always(TriState.TRUE);
+
+  private static final class Always implements PermissionChecker {
+    private final TriState value;
+
+    private Always(final TriState value) {
+      this.value = value;
+    }
+
+    @Override
+    public @NonNull TriState value(final String permission) {
+      return this.value;
+    }
+
+    @Override
+    public String toString() {
+      return PermissionChecker.class.getSimpleName() + ".always(" + this.value + ")";
+    }
+  }
+}