Merge pull request #28 from muunitnocQ/feature/convo-utils

Added a bunch of conversation API related tools

Author: KodySimpson

src/main/java/me/kodysimpson/simpapi/conversations/ArrayMatchCanceller.java

@@ -0,0 +1,44 @@
+package me.kodysimpson.simpapi.conversations;
+
+import org.bukkit.conversations.Conversation;
+import org.bukkit.conversations.ConversationCanceller;
+import org.bukkit.conversations.ConversationContext;
+import org.jetbrains.annotations.NotNull;
+
+import java.util.Arrays;
+import java.util.List;
+
+//A better version of o.b.c.ExactMatchConversationCanceller
+
+/**
+ * @author muunitnocQ
+ */
+final class ArrayMatchCanceller implements ConversationCanceller {
+
+    private final boolean caseSensitive;
+    private final List<String> escapeWords;
+
+    ArrayMatchCanceller(boolean caseSensitive, String... escapeWords) {
+        this(caseSensitive, Arrays.asList(escapeWords));
+    }
+
+    ArrayMatchCanceller(boolean caseSensitive, List<String> escapeWords) {
+        this.caseSensitive = caseSensitive;
+        this.escapeWords = escapeWords;
+    }
+
+    @Override
+    public void setConversation(@NotNull Conversation conversation) {
+    }
+
+    @Override
+    public boolean cancelBasedOnInput(@NotNull ConversationContext context, @NotNull String input) {
+        return escapeWords.stream()
+                .anyMatch(escapeWord -> caseSensitive ? escapeWord.equals(input) : escapeWord.equalsIgnoreCase(input));
+    }
+
+    @Override
+    public ConversationCanceller clone() {
+        return new ArrayMatchCanceller(caseSensitive, escapeWords);
+    }
+}

src/main/java/me/kodysimpson/simpapi/conversations/ConversationStarter.java

@@ -0,0 +1,133 @@
+package me.kodysimpson.simpapi.conversations;
+
+import me.kodysimpson.simpapi.colors.ColorTranslator;
+import org.bukkit.conversations.*;
+import org.bukkit.entity.Player;
+import org.bukkit.plugin.Plugin;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Range;
+
+import java.util.Collections;
+import java.util.Map;
+
+/**
+ * Helper class for construction of conversations.
+ * Wraps {@link ConversationFactory} to make building conversations with players
+ * significantly less tedious and boiler-plate prone.
+ *
+ * @see ConversationOptions
+ * @author muunitnocQ
+ */
+public final class ConversationStarter {
+
+    /**
+     * Constructs a conversation with the first prompt for a given player under the authority of the provided plugin,
+     * with optionally attached data.
+     *
+     * @param plugin      The plugin owning this conversation instance
+     * @param player      Who the conversation is for
+     * @param firstPrompt The prompt to start off on
+     * @param options     Optional fine-grained configuration of the conversation. Refer to {@link ConversationOptions}
+     * @param initialData Optional session data to start off with. Refer to {@link ConversationContext#getAllSessionData()}
+     * @return The conversation, not yet started. See {@link Conversation#begin()}
+     */
+    public static @NotNull Conversation getForPlayer(
+            @NotNull Plugin plugin,
+            @NotNull Player player,
+            @NotNull Prompt firstPrompt,
+            @Nullable ConversationOptions options,
+            @Nullable Map<Object, Object> initialData
+    ) {
+        if (options == null) options = ConversationOptions.DEFAULT_OPTIONS;
+
+        ConversationFactory factory = new ConversationFactory(plugin)
+                .withFirstPrompt(firstPrompt)
+                .withLocalEcho(options.localEcho)
+                .withPrefix(options.prefix)
+                .addConversationAbandonedListener(new PrefixedAbandonedListener(options.rawPrefix))
+                .withConversationCanceller(new ArrayMatchCanceller(options.escapeWordsCaseSensitive, options.escapeWords))
+                .withInitialSessionData(initialData == null ? Collections.emptyMap() : initialData)
+                .withTimeout(options.timeOut);
+        Conversation convo = factory.buildConversation(player);
+
+        new ServerReloadListener(plugin, convo);
+
+        return convo;
+    }
+
+    //I really want records, koby
+    //java 8 makes me go grrr
+
+    /**
+     * Represents the configurable options in a conversation.
+     *
+     * @see ConversationOptions#ConversationOptions(String, boolean, boolean, int, boolean, String...)
+     */
+    public final static class ConversationOptions {
+
+        //Applied if the options for ConversationStarter#getForPlayer is null
+        private static final ConversationOptions DEFAULT_OPTIONS = new ConversationOptions(
+                null,
+                true,
+                false,
+                60,
+                false,
+                "cancel", "exit", "quit", "escape", "done"
+        );
+
+        /**
+         * Shown before every line of output in the conversation.
+         * Supports Minecraft vanilla colors and hex colors in the format &#RRGGBB.
+         *
+         * @see ColorTranslator#translateColorCodes(String)
+         */
+        public final ConversationPrefix prefix;
+        private final String rawPrefix;
+        public final boolean localEcho;
+        public final boolean modal;
+        public final int timeOut;
+        public final boolean escapeWordsCaseSensitive;
+        public final String[] escapeWords;
+
+        /**
+         * Describes all options a conversation can have.
+         *
+         * @param prefix                   Shown before every line of output in the conversation
+         *                                 Defaults to "" if null is passed
+         * @param localEcho                Should the player's input be displayed back to them?
+         * @param modal                    Determines if the player can see other players chatting during the conversation
+         * @param timeOut                  An automatic time-out in which the conversation will cancel upon receiving no input from the player
+         *                                 Clamps to 0 as a minimum.
+         * @param escapeWordsCaseSensitive Should escape words be case sensitive? See next parameter for details
+         * @param escapeWords              Words that, when entered as input, will force the conversation to be abandoned.
+         */
+        public ConversationOptions(
+                @Nullable String prefix,
+                boolean localEcho,
+                boolean modal,
+                @Range(from = 0, to = Integer.MAX_VALUE) int timeOut,
+                boolean escapeWordsCaseSensitive,
+                String... escapeWords
+        ) {
+            if (prefix == null) {
+                this.rawPrefix = "";
+                this.prefix = new NullConversationPrefix();
+            } else {
+                this.rawPrefix = ColorTranslator.translateColorCodes(prefix);
+                this.prefix = (context) -> rawPrefix;
+            }
+
+            this.localEcho = localEcho;
+            this.modal = modal;
+            this.timeOut = timeOut;
+            this.escapeWordsCaseSensitive = escapeWordsCaseSensitive;
+
+            if (escapeWords == null || escapeWords.length < 1) {
+                this.escapeWords = new String[]{
+                        "cancel", "exit", "quit", "escape", "done"
+                };
+            } else this.escapeWords = escapeWords;
+        }
+    }
+}

src/main/java/me/kodysimpson/simpapi/conversations/MultilineMessage.java

@@ -0,0 +1,57 @@
+package me.kodysimpson.simpapi.conversations;
+
+
+import me.kodysimpson.simpapi.colors.ColorTranslator;
+import org.bukkit.conversations.ConversationContext;
+import org.bukkit.conversations.MessagePrompt;
+import org.bukkit.conversations.Prompt;
+import org.jetbrains.annotations.NotNull;
+
+import java.util.Arrays;
+
+/**
+ * Convenience class for describing messages that take up more than one line of chat.
+ * Expected usage encompasses extending this class to define concrete message classes:
+ * <pre>
+ * final class InvalidInputMessage extends MultilineMessage {
+ *    public InvalidInputMessage(Prompt previousPrompt, Player player) {
+ *        super(previousPrompt,
+ *         "That is not valid input, " + player.getName(),
+ *         "Please enter input as follows:",
+ *         "x... y... or z",
+ *         "Returning to the previous prompt."
+ *        );
+ *    }
+ * }
+ * </pre>
+ * Or by calling {@link MultilineMessage#MultilineMessage(Prompt, String...)} directly.
+ *
+ * @author muunitnocQ
+ */
+public class MultilineMessage extends MessagePrompt {
+
+    private final Prompt end;
+    private final String[] messages;
+
+    public MultilineMessage(Prompt end, String... messages) {
+        if (messages == null || messages.length == 0) {
+            throw new IllegalStateException("Invalid multiline message");
+        }
+
+        this.end = end;
+        this.messages = messages;
+    }
+
+    @Override
+    public @NotNull String getPromptText(@NotNull ConversationContext context) {
+        return ColorTranslator.translateColorCodes(messages[0]);
+    }
+
+    @Override
+    protected Prompt getNextPrompt(@NotNull ConversationContext context) {
+        if (messages.length == 1) return end;
+        return new MultilineMessage(end, Arrays.copyOfRange(messages, 1, messages.length));
+    }
+
+
+}

src/main/java/me/kodysimpson/simpapi/conversations/PrefixedAbandonedListener.java

@@ -0,0 +1,61 @@
+package me.kodysimpson.simpapi.conversations;
+
+import me.kodysimpson.simpapi.colors.ColorTranslator;
+import org.bukkit.conversations.ConversationAbandonedEvent;
+import org.bukkit.conversations.ConversationAbandonedListener;
+import org.bukkit.conversations.ConversationCanceller;
+import org.bukkit.conversations.InactivityConversationCanceller;
+import org.bukkit.entity.Player;
+
+import java.util.Objects;
+
+//A nice conversation abandoned listener that prefixes messages with the conversation's prefix
+//Detects a few different conversation cancellers and writes a smarter message versus "conversation abandoned"
+
+/**
+ * @author muunitnocQ
+ */
+final class PrefixedAbandonedListener implements ConversationAbandonedListener {
+
+    private final String prefix;
+
+    PrefixedAbandonedListener(String prefix) {
+        this.prefix = prefix;
+    }
+
+    @Override
+    public void conversationAbandoned(ConversationAbandonedEvent abandonedEvent) {
+        if (abandonedEvent.gracefulExit()) return;
+
+        Player player = (Player) abandonedEvent.getContext().getForWhom();
+        ConversationCanceller canceller = Objects.requireNonNull(abandonedEvent.getCanceller(), "[m.k.s.c.ArrayMatchCanceller] Canceller is null but gracefulExit is false");
+
+        //JEP 406 can't land soon enough
+
+        //The player entered one of the escape words.
+        if (canceller instanceof ArrayMatchCanceller) {
+            player.sendMessage(tl(prefix + "&9Good bye!"));
+            return;
+        }
+
+        //Server is reloading, abandon the conversation
+        if (canceller instanceof ServerReloadListener.ServerReloadCanceller) {
+            player.sendMessage(tl(prefix + "&9Server reloaded, quitting."));
+            return;
+        }
+
+        //Conversation timed out
+        if (canceller instanceof InactivityConversationCanceller) {
+            player.sendMessage(tl(prefix + "&9Session timed out."));
+            return;
+        }
+
+        //Unknown canceller
+        player.sendMessage(tl(prefix + "&9Conversation cancelled by &#FF00FFcosmic energy&9."));
+    }
+
+    private static String tl(String msg) {
+        return ColorTranslator.translateColorCodes(msg);
+    }
+
+}

src/main/java/me/kodysimpson/simpapi/conversations/ServerReloadListener.java

@@ -0,0 +1,67 @@
+package me.kodysimpson.simpapi.conversations;
+
+import org.bukkit.Bukkit;
+import org.bukkit.conversations.Conversation;
+import org.bukkit.conversations.ConversationAbandonedEvent;
+import org.bukkit.conversations.ConversationCanceller;
+import org.bukkit.conversations.ConversationContext;
+import org.bukkit.event.EventHandler;
+import org.bukkit.event.Listener;
+import org.bukkit.event.server.PluginDisableEvent;
+import org.bukkit.plugin.Plugin;
+import org.jetbrains.annotations.NotNull;
+
+//Addresses a bug with conversations where, upon server reload, active conversations enter a "zombie" state.
+//In this state, the conversation is *still* alive, but the player cannot interact with it normally.
+//This class detects when the conversation's owning plugin is disabled (/reload, plugin managers, etc) and abandons
+//the associated conversation.
+
+/**
+ * @author muunitnocQ
+ */
+final class ServerReloadListener implements Listener {
+
+    final ServerReloadCanceller canceller;
+    private final Class<? extends Plugin> pluginClazz;
+
+    ServerReloadListener(Plugin plugin, Conversation convo) {
+        this.pluginClazz = plugin.getClass();
+        this.canceller = new ServerReloadCanceller();
+
+        convo.getCancellers().add(canceller);
+        Bukkit.getPluginManager().registerEvents(this, plugin);
+    }
+
+    @EventHandler
+    public void onReload(PluginDisableEvent event) {
+        if (event.getPlugin().getClass() != pluginClazz) return;
+        canceller.forceAbandon();
+    }
+
+    //Dummy implementation save for reloadCancel
+    static final class ServerReloadCanceller implements ConversationCanceller {
+        private Conversation conversation;
+
+        @Override
+        public void setConversation(@NotNull Conversation conversation) {
+            this.conversation = conversation;
+        }
+
+        @Override
+        public boolean cancelBasedOnInput(@NotNull ConversationContext context, @NotNull String input) {
+            return false;
+        }
+
+        @Override
+        public ConversationCanceller clone() {
+            return this;
+        }
+
+        //A "backdoor" into the ConversationCanceller API so the listener can notify this instance when to abandon
+        //the conversation.
+        void forceAbandon() {
+            conversation.abandon(new ConversationAbandonedEvent(conversation, this));
+        }
+
+    }
+}