Merge branch 'master' into feature/update-documentation

src/main/java/me/clip/placeholderapi/PlaceholderAPI.java

@@ -29,6 +29,7 @@ import java.util.regex.Pattern;
 import java.util.stream.Collectors;
 import me.clip.placeholderapi.expansion.PlaceholderExpansion;
 import me.clip.placeholderapi.expansion.Relational;
+import me.clip.placeholderapi.expansion.manager.LocalExpansionManager;
 import me.clip.placeholderapi.replacer.CharsReplacer;
 import me.clip.placeholderapi.replacer.Replacer;
 import me.clip.placeholderapi.replacer.Replacer.Closure;
@@ -166,7 +167,7 @@ public final class PlaceholderAPI {
 
   /**
    * set relational placeholders in the text specified placeholders are matched with the pattern
-   * %<rel_(identifier)_(params)>% when set with this method
+   * {@literal %<rel_(identifier)_(params)>%} when set with this method
    *
    * @param one First player to compare
    * @param two Second player to compare
@@ -306,10 +307,10 @@ public final class PlaceholderAPI {
 
   /**
    * Get map of registered placeholders
+   * 
+   * @deprecated Use {@link LocalExpansionManager#getExpansions()} instead.
    *
    * @return Map of registered placeholders
-   * @deprecated Use {@link me.clip.placeholderapi.PlaceholderAPIPlugin().getLocalExpansionManager()
-   * .getExpansions()} instead.
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -320,8 +321,12 @@ public final class PlaceholderAPI {
   }
 
   /**
-   * @deprecated Please use {@link me.clip.placeholderapi.expansion.PlaceholderExpansion} to
+   * @deprecated Please use {@link PlaceholderExpansion} to
    * register placeholders instead
+   * 
+   * @param plugin The Plugin to register with this {@link PlaceholderHook}
+   * @param placeholderHook The {@link PlaceholderHook} to register
+   * @return always false
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -334,8 +339,12 @@ public final class PlaceholderAPI {
   }
 
   /**
-   * @deprecated Please use {@link me.clip.placeholderapi.expansion.PlaceholderExpansion} to
+   * @deprecated Please use {@link PlaceholderExpansion} to
    * register placeholders instead
+   * 
+   * @param identifier The identifier to use for the {@link PlaceholderHook}
+   * @param placeholderHook The {@link PlaceholderHook} to register
+   * @return always false
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -347,8 +356,11 @@ public final class PlaceholderAPI {
   }
 
   /**
-   * @deprecated Please use {@link me.clip.placeholderapi.expansion.PlaceholderExpansion} to
+   * @deprecated Please use {@link PlaceholderExpansion} to
    * unregister placeholders instead
+   * 
+   * @param plugin The plugin to unregister
+   * @return always false
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -361,8 +373,11 @@ public final class PlaceholderAPI {
   }
 
   /**
-   * @deprecated Please use {@link me.clip.placeholderapi.expansion.PlaceholderExpansion} to
+   * @deprecated Please use {@link PlaceholderExpansion} to
    * unregister placeholders instead
+   * 
+   * @param identifier The identifier to unregister
+   * @return always false
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -374,6 +389,8 @@ public final class PlaceholderAPI {
 
   /**
    * @deprecated Will be removed in a future release.
+   * 
+   * @return Set of registered identifiers
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -383,6 +400,8 @@ public final class PlaceholderAPI {
 
   /**
    * @deprecated Will be removed in a future release.
+   * 
+   * @return always null
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -392,6 +411,12 @@ public final class PlaceholderAPI {
 
   /**
    * @deprecated Please use {@link #setPlaceholders(OfflinePlayer, String)} instead
+   * 
+   * @param player The offline player to parse the placeholders against
+   * @param text The text to parse
+   * @param pattern The Pattern to use
+   * @param colorize If PlaceholderAPI should also parse color codes
+   * @return String with the parsed placeholders
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -402,6 +427,12 @@ public final class PlaceholderAPI {
 
   /**
    * @deprecated Please use {@link #setPlaceholders(OfflinePlayer, List)} instead
+   * 
+   * @param player The offline player to parse the placeholders against
+   * @param text The List of text to parse
+   * @param pattern The Pattern to use
+   * @param colorize If PlaceholderAPI should also parse color codes
+   * @return String with the parsed placeholders
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -412,6 +443,11 @@ public final class PlaceholderAPI {
 
   /**
    * @deprecated Use {@link #setPlaceholders(OfflinePlayer, List)} instead.
+   *
+   * @param player The offline player to parse the placeholders against
+   * @param text The List of text to parse
+   * @param colorize If PlaceholderAPI should also parse color codes
+   * @return String with the parsed placeholders
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -422,6 +458,11 @@ public final class PlaceholderAPI {
 
   /**
    * @deprecated Use {@link #setPlaceholders(OfflinePlayer, List)} instead.
+   *
+   * @param player The offline player to parse the placeholders against
+   * @param text The List of text to parse
+   * @param pattern The Pattern to use
+   * @return String with the parsed placeholders
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -431,6 +472,11 @@ public final class PlaceholderAPI {
   }
   /**
    * @deprecated Will be removed in a future release.
+   *
+   * @param player The offline player to parse the placeholders against
+   * @param text The text to parse
+   * @param colorize If PlaceholderAPI should also parse color codes
+   * @return String with the parsed placeholders
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -440,6 +486,11 @@ public final class PlaceholderAPI {
 
   /**
    * @deprecated Will be removed in a future release.
+   *
+   * @param player The offline player to parse the placeholders against
+   * @param text The List of text to parse
+   * @param colorize If PlaceholderAPI should also parse color codes
+   * @return String with the parsed placeholders
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -449,6 +500,11 @@ public final class PlaceholderAPI {
 
   /**
    * @deprecated Use {@link #setPlaceholders(OfflinePlayer, String)} instead.
+   *
+   * @param player The offline player to parse the placeholders against
+   * @param text The text to parse
+   * @param colorize If PlaceholderAPI should also parse color codes
+   * @return String with the parsed placeholders
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -458,6 +514,11 @@ public final class PlaceholderAPI {
 
   /**
    * @deprecated Use {@link #setPlaceholders(OfflinePlayer, String)} instead.
+   *
+   * @param player The offline player to parse the placeholders against
+   * @param text The text to parse
+   * @param pattern The Pattern to use
+   * @return String with the parsed placeholders
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -467,6 +528,11 @@ public final class PlaceholderAPI {
 
   /**
    * @deprecated Use {@link #setPlaceholders(OfflinePlayer, List)} instead.
+   *
+   * @param player The offline player to parse the placeholders against
+   * @param text The List of text to parse
+   * @param colorize If PlaceholderAPI should also parse color codes
+   * @return String with the parsed placeholders
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -477,6 +543,11 @@ public final class PlaceholderAPI {
 
   /**
    * @deprecated Use {@link #setPlaceholders(OfflinePlayer, String)} instead.
+   *
+   * @param player The offline player to parse the placeholders against
+   * @param text The text to parse
+   * @param colorize If PlaceholderAPI should also parse color codes
+   * @return String with the parsed placeholders
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -486,6 +557,11 @@ public final class PlaceholderAPI {
 
   /**
    * @deprecated Will be removed in a future release.
+   *
+   * @param player The offline player to parse the placeholders against
+   * @param text The text to parse
+   * @param colorize If PlaceholderAPI should also parse color codes
+   * @return String with the parsed placeholders
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -495,6 +571,11 @@ public final class PlaceholderAPI {
 
   /**
    * @deprecated Will be removed in a future release.
+   *
+   * @param player The offline player to parse the placeholders against
+   * @param text The List of text to parse
+   * @param colorize If PlaceholderAPI should also parse color codes
+   * @return String with the parsed placeholders
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -505,12 +586,12 @@ public final class PlaceholderAPI {
 
   /**
    * set relational placeholders in the text specified placeholders are matched with the pattern
-   * %<rel_(identifier)_(params)>% when set with this method
+   * {@literal %<rel_(identifier)_(params)>%} when set with this method
    *
    * @param one Player to compare
    * @param two Player to compare
    * @param text Text to parse the placeholders in
-   * @param colorize If color codes (&[0-1a-fk-o]) should be translated
+   * @param colorize If color codes ({@literal &[0-1a-fk-o]}) should be translated
    * @return The text containing the parsed relational placeholders
    * @deprecated Use {@link #setPlaceholders(OfflinePlayer, String)} instead.
    */
@@ -528,9 +609,9 @@ public final class PlaceholderAPI {
    * @param one First player to compare
    * @param two Second player to compare
    * @param text Text to parse the placeholders in
-   * @param colorize If color codes (&[0-1a-fk-o]) should be translated
+   * @param colorize If color codes ({@literal &[0-1a-fk-o]}) should be translated
    * @return The text containing the parsed relational placeholders
-   * @deprecated Use {@link #setRelationalPlaceholders(Player, Player, List<String>)} instead.
+   * @deprecated Use {@link #setRelationalPlaceholders(Player, Player, List)} instead.
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")

src/main/java/me/clip/placeholderapi/commands/impl/local/CommandInfo.java

@@ -47,7 +47,7 @@ public final class CommandInfo extends PlaceholderCommand {
     }
 
     final PlaceholderExpansion expansion = plugin.getLocalExpansionManager()
-        .findExpansionByName(params.get(0)).orElse(null);
+        .findExpansionByIdentifier(params.get(0)).orElse(null);
     if (expansion == null) {
       Msg.msg(sender,
           "&cThere is no expansion loaded with the identifier: &f" + params.get(0));

src/main/java/me/clip/placeholderapi/events/ExpansionsLoadedEvent.java

@@ -0,0 +1,46 @@
+/*
+ * This file is part of PlaceholderAPI
+ *
+ * PlaceholderAPI
+ * Copyright (c) 2015 - 2020 PlaceholderAPI Team
+ *
+ * PlaceholderAPI free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * PlaceholderAPI is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package me.clip.placeholderapi.events;
+
+
+import org.bukkit.event.Event;
+import org.bukkit.event.HandlerList;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * This event is called when all expansions are loaded (when reloading config, on plugin start and on server load).
+ */
+public class ExpansionsLoadedEvent extends Event {
+
+    @NotNull
+    private static final HandlerList HANDLERS = new HandlerList();
+
+    @NotNull
+    @Override
+    public HandlerList getHandlers() {
+        return HANDLERS;
+    }
+
+    @NotNull
+    public static HandlerList getHandlerList() {
+        return HANDLERS;
+    }
+}

src/main/java/me/clip/placeholderapi/expansion/NMSVersion.java

@@ -39,7 +39,9 @@ public enum NMSVersion {
   SPIGOT_1_13_R2("v1_13_R2"),
   SPIGOT_1_14_R1("v1_14_R1"),
   SPIGOT_1_15_R1("v1_15_R1"),
-  SPIGOT_1_16_R1("v1_16_R1");
+  SPIGOT_1_16_R1("v1_16_R1"),
+  SPIGOT_1_16_R2("v1_16_R2"),
+  SPIGOT_1_16_R3("v1_16_R3");
 
   private final String version;
 

src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java

@@ -268,6 +268,20 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {
     return section == null ? Collections.emptyList() : section.getStringList(path);
   }
   
+  /**
+   * Gets the boolean relative to the {@link #getConfigSection() default ConfigurationSection} set
+   * by the expansion or the default boolean, when the default ConfigurationSection is null
+   *
+   * @param path The path to get the boolean from. This is relative to the default section
+   * @param def The default boolean to return when the ConfigurationSection is null
+   * @return boolean from the provided path or the default one provided
+   */
+  @NotNull
+  public final boolean getBoolean(@NotNull final String path, final boolean def) {
+    final ConfigurationSection section = getConfigSection();
+    return section == null ? def : section.getBoolean(path, def);
+  }
+
   /**
    * Whether the {@link #getConfigSection() default ConfigurationSection} contains the provided path
    * or not. This will return {@code false} when either the default section is null, or doesn't
@@ -324,6 +338,8 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {
 
   /**
    * @deprecated As of versions greater than 2.8.7, use {@link #getRequiredPlugin()}
+   *
+   * @return The plugin name.
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -333,6 +349,8 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {
 
   /**
    * @deprecated As of versions greater than 2.8.7, use the expansion cloud to show a description
+   *
+   * @return The description of the expansion.
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")
@@ -342,6 +360,8 @@ public abstract class PlaceholderExpansion extends PlaceholderHook {
 
   /**
    * @deprecated As of versions greater than 2.8.7, use the expansion cloud to display a link
+   *
+   * @return The link for the expansion.
    */
   @Deprecated
   @ApiStatus.ScheduledForRemoval(inVersion = "2.11.0")

src/main/java/me/clip/placeholderapi/expansion/VersionSpecific.java

@@ -34,6 +34,8 @@ public interface VersionSpecific {
    * This method is called before the expansion is attempted to be registered The server version
    * will be passed to this method so you know what version the server is currently running.
    *
+   * @param v The {@link Version} to check against
+   *
    * @return true if your expansion is compatible with the version the server is running.
    */
   boolean isCompatibleWith(Version v);

src/main/java/me/clip/placeholderapi/expansion/manager/LocalExpansionManager.java

@@ -36,6 +36,7 @@ import java.util.logging.Level;
 import me.clip.placeholderapi.PlaceholderAPIPlugin;
 import me.clip.placeholderapi.events.ExpansionRegisterEvent;
 import me.clip.placeholderapi.events.ExpansionUnregisterEvent;
+import me.clip.placeholderapi.events.ExpansionsLoadedEvent;
 import me.clip.placeholderapi.expansion.Cacheable;
 import me.clip.placeholderapi.expansion.Cleanable;
 import me.clip.placeholderapi.expansion.Configurable;
@@ -173,10 +174,7 @@ public final class LocalExpansionManager implements Listener {
 
     return Optional.empty();
   }
-
-  /**
-   * Do not call this method yourself, use {@link PlaceholderExpansion#register()}
-   */
+  
   @ApiStatus.Internal
   public boolean register(@NotNull final PlaceholderExpansion expansion) {
     final String identifier = expansion.getIdentifier().toLowerCase();
@@ -270,9 +268,6 @@ public final class LocalExpansionManager implements Listener {
     return true;
   }
 
-  /**
-   * Do not call this method yourself, use {@link PlaceholderExpansion#unregister()}
-   */
   @ApiStatus.Internal
   public boolean unregister(@NotNull final PlaceholderExpansion expansion) {
     if (expansions.remove(expansion.getIdentifier()) == null) {
@@ -320,6 +315,8 @@ public final class LocalExpansionManager implements Listener {
       Msg.msg(sender,
           registered == 0 ? "&6No expansions were registered!"
               : registered + "&a placeholder hooks successfully registered!");
+
+      Bukkit.getPluginManager().callEvent(new ExpansionsLoadedEvent());
     });
   }