[Bleeding] Added Help API. Addresses BUKKIT-863

By: rmichela <deltahat@gmail.com>

paper-api/src/main/java/org/bukkit/help/HelpMap.java

@@ -0,0 +1,44 @@
+package org.bukkit.help;
+
+/**
+ * The HelpMap tracks all help topics registered in a Bukkit server. When the server starts up or is reloaded,
+ * help is processed and topics are added in the following order:
+ *
+ * 1. General topics are loaded from the help.yml
+ * 2. Plugins load and optionally call {@code addTopic()}
+ * 3. Registered plugin commands are processed by {@link HelpTopicFactory} objects to create topics
+ * 4. Topic contents are amended as directed in help.yml
+ */
+public interface HelpMap {
+    /**
+     * Returns a help topic for a given topic name.
+     *
+     * @param topicName The help topic name to look up.
+     * @return A {@link HelpTopic} object matching the topic name or null if none can be found.
+     */
+    public HelpTopic getHelpTopic(String topicName);
+
+    /**
+     * Adds a topic to the server's help index.
+     *
+     * @param topic The new help topic to add.
+     */
+    public void addTopic(HelpTopic topic);
+
+    /**
+     * Clears out the contents of the help index. Normally called during server reload.
+     */
+    public void clear();
+
+    /**
+     * Associates a {@link HelpTopicFactory} object with given command base class. Plugins typically
+     * call this method during {@code onLoad()}. Once registered, the custom HelpTopicFactory will
+     * be used to create a custom {@link HelpTopic} for all commands deriving from the {@code commandClass}
+     * base class.
+     *
+     * @param commandClass The class for which the custom HelpTopicFactory applies. Must derive from {@link org.bukkit.command.Command}.
+     * @param factory The {@link HelpTopicFactory} implementation to associate with the {@code commandClass}.
+     * @throws IllegalArgumentException Thrown if {@code commandClass} does not derive from Command.
+     */
+    public void registerHelpTopicFactory(Class commandClass, HelpTopicFactory factory);
+}

paper-api/src/main/java/org/bukkit/help/HelpTopic.java

@@ -0,0 +1,90 @@
+package org.bukkit.help;
+
+import org.bukkit.command.CommandSender;
+import org.bukkit.entity.Player;
+
+/**
+ * HelpTopic implementations are displayed to the user when the user uses the /help command.
+ *
+ * Custom implementations of this class can work at two levels. A simple implementation only
+ * needs to set the value of {@code name}, {@code shortText}, and {@code fullText} int the
+ * constructor. This base class will take care of the rest.
+ *
+ * Complex implementations can be created by overriding the behavior of all the methods in
+ * this class.
+ */
+public abstract class HelpTopic {
+    protected String name;
+    protected String shortText;
+    protected String fullText;
+    
+    /**
+     * Determines if a {@link Player} is allowed to see this help topic.
+     *
+     * @param player The Player in question.
+     * @return True of the Player can see this help topic, false otherwise.
+     */
+    public abstract boolean canSee(CommandSender player);
+
+    /**
+     * Returns the name of this help topic.
+     * @return The topic name.
+     */
+    public String getName() {
+        return name;
+    }
+
+    /**
+     * Returns a brief description that will be displayed in the topic index.
+     * @return A brief topic description.
+     */
+    public String getShortText() {
+        return shortText;
+    }
+
+    /**
+     * Returns the full description of this help topic that is displayed when the user requests this topic's details.
+     * The result will be paginated to properly fit the user's client.
+     *
+     * @param forWho The player or console requesting the full text. Useful for further security trimming
+     *               the command's full text based on sub-permissions in custom implementations.
+     *
+     * @return A full topic description.
+     */
+    public String getFullText(CommandSender forWho) {
+        return fullText;
+    }
+
+    /**
+     * Allows the server admin (or another plugin) to add or replace the contents of a help topic. A null in
+     * either parameter will leave that part of the topic unchanged. In either amending parameter, the string
+     * {@literal <text>} is replaced with the existing contents in the help topic. Use this to append or prepend
+     * additional content into an automatically generated help topic.
+     *
+     * @param amendedShortText The new topic short text to use, or null to leave alone.
+     * @param amendedFullText The new topic full text to use, or null to leave alone.
+     */
+    public void amendTopic(String amendedShortText, String amendedFullText) {
+        shortText = applyAmendment(shortText, amendedShortText);
+        fullText = applyAmendment(fullText, amendedFullText);
+    }
+
+    /**
+     * Developers implementing their own custom HelpTopic implementations can use this utility method to ensure
+     * their implementations comply with the expected behavior of the {@link HelpTopic#amendTopic(String, String)}
+     * method.
+     *
+     * @param baseText The existing text of the help topic.
+     * @param amendment The amending text from the amendTopic() method.
+     *
+     * @return The application of the amending text to the existing text, according to the expected rules of
+     * amendTopic().
+     */
+    protected String applyAmendment(String baseText, String amendment) {
+        if (amendment == null) {
+            return baseText;
+        } else {
+            return amendment.replaceAll("<text>", baseText);
+        }
+    }
+}

paper-api/src/main/java/org/bukkit/help/HelpTopicFactory.java

@@ -0,0 +1,27 @@
+package org.bukkit.help;
+
+import org.bukkit.command.Command;
+
+/**
+ * A HelpTopicFactory is used to create custom {@link HelpTopic} objects from commands that inherit from a
+ * common base class. You can use a custom HelpTopic to change the way all the commands in your plugin display
+ * in the help. If your plugin implements a complex permissions system, a custom help topic may also be appropriate.
+ *
+ * To automatically bind your plugin's commands to your custom HelpTopic implementation, first make sure all your
+ * commands derive from a custom base class (it doesn't have to do anything). Next implement a custom HelpTopicFactory
+ * for that accepts your custom command base class and instantiates an instance of your custom HelpTopic from it.
+ * Finally, register your HelpTopicFactory against your command base class using the {@link HelpMap#registerHelpTopicFactory(Class, HelpTopicFactory)}
+ * method.
+ *
+ * @param <TCommand> The base class for your custom commands.
+ */
+public interface HelpTopicFactory<TCommand extends Command> {
+    /**
+     * This method accepts a command deriving from a custom command base class and constructs a custom HelpTopic
+     * for it.
+     *
+     * @param command The custom command to build a help topic for.
+     * @return A new custom help topic.
+     */
+    public HelpTopic createTopic(TCommand command);
+}