RPCommons - Command Base

package net.risenphoenix.commons.Commands;

import net.risenphoenix.commons.Plugin;
import net.risenphoenix.commons.Localization.LocalizationManager;

import org.bukkit.command.CommandSender;
import org.bukkit.permissions.Permission;

/**
 * Base class for Plugin Commands. This class contains common shared methods which all
 * plugin commands inherit.</br>
 *
 * </br>This class is responsible for performing checks for player
 * permissions, storing and providing command specific variables such as Name, Syntax
 * and Help Text, as well as providing access to Global Resources such as the Localization
 * Manager.
 *
 * @author Jacob Keep (Jnk1296)
 */

public class Command {
    private final Plugin plugin;

    private String name;
    private String syntax;
    private String help;

    private boolean isConsoleExecutable = true;

    private String[] callArgs;
    private int requiredArgs;

    private Permission[] commandPerms = null;

    private LocalizationManager LM;

    /**
     * <strong>Constructor:</strong> Responisble for the main initialization of the
     * Command instance. Registers the required arguments for the command to be
     * identified, as well as the number of arguments needed to successfully call the
     * command. The Plugin instance is required to link to the LocalizationManager.</br>
     *
     * </br>The number passed for <strong>requiredArgs</strong> can be any positive number
     * (0+) or -1. When -1 is specified, this signals that the command is open-ended, and
     * allows for a variable number of arguments. This is typically used for commands such
     * as those allowing for custom messages to specified. <strong>When setting the
     * number of arguments required, DO NOT INCLUDE the root command!</strong> The
     * Command Manager will fail to parse input for your command if you do this.</br>
     *
     * <br><strong>callArgs</strong> contains the sic arguments which would be typed
     * in-game to call the command. <strong>Ex: </strong><em>/ipc exempt-list ip</em>
     * <strong>-></strong> { "exempt-list", "ip" }. The root command is always absent
     * from the arguments array.
     *
     * @param plugin
     * @param callArgs
     * @param requiredArgs
     */

    public Command(final Plugin plugin, String[] callArgs, int requiredArgs) {
        this.plugin = plugin;
        this.callArgs = callArgs;
        this.requiredArgs = requiredArgs;
        this.LM = this.plugin.getLocalizationManager();
    }

    /**
     * Called by the CommandManager during execution. This method is the public executor
     * for all Commands, and should be called whenever you wish to execute a Command in
     * your code.</br>
     *
     * </br>The method returns a boolean value depending on whether the CommandSender
     * Object passed can call the command or not.</br>
     *
     * </br><b>Operation is as follows: <ul>
     *
     * <li></b>When called, the method
     * checks the CommandSender object passed for OP Status. If the CS has OP Status, all
     * further checks are skipped and <b>onExecute()</b> is called, causing the method to
     * return <b>TRUE</b>.</li>
     *
     * <li>If the CS object does not have OP Status, the method then checks
     * to see if the Command Instance has any permissions specified in <b>commandPerms</b>
     * .</li>
     *
     * <li>If permissions are found, they are looped through and checked against the CS
     * Object one by one. Should the CS Object fail to have any of the specified
     * permissions, the method returns <b>FALSE</b>.</li></ul>
     */

    public final boolean onCall(CommandSender sender, String[] args) {
        if (!sender.isOp()) {
            if (this.commandPerms != null) {
                for (int i = 0; i < this.commandPerms.length; i++) {
                    if (!sender.hasPermission(this.commandPerms[i])) return false;
                }
            }
        }
        onExecute(sender, args);
        return true;
    }

    /**
     * Sets the permissions required for this Command to be executed.</br>
     *
     * </br>The permission should be passed as an array like such:<ul>
     * <li><em>new Permission[]{ new Permission("permission.one"), new Permission
     * ("permission.two"), etc... };</em></li></ul>
     * @param perms
     */
    public final void setPermissions(Permission[] perms) {
        this.commandPerms = perms;
    }

    /**
     * Sets the Display Name for this Command.</br>
     *
     * </br>The name can be any string.
     * @param cmdName
     */
    public final void setName(String cmdName) {
        this.name = cmdName;
    }

    /**
     * Sets the syntax for this Command.</br>
     *
     * </br>When set, the string passed should contain the literal (sic) syntax to be used
     * when calling your command, <strong>minus the root command</strong>. The syntax
     * string is generally used for displaying help information and should be relatively
     * easy to understand.</br>
     *
     * </br>Ex: <em>ban {@literal <}player{@literal >} [message]</em>
     * @param cmdSyntax
     */
    public final void setSyntax(String cmdSyntax) {
        this.syntax = cmdSyntax;
    }

    /**
     * Sets the Help Description text for this command.</br>
     *
     * </br>This text is displayed in the Help Command and is used to describe what this
     * Command does, as well as any other information the end user may need to know.
     * @param helpDesc
     */
    public final void setHelp(String helpDesc) {
        this.help = helpDesc;
    }

    /**
     * Sets whether this Command can be called by Console or not.</br>
     *
     * </br>Depending on the status of this flag, you can limit this Command to being a
     * Player-only Command, meaning that Console cannot execute this Command.</br>
     *
     * </br><strong>TRUE</strong> = Console can execute, <strong>FALSE</strong> = Console
     * cannot execute.
     * @param consoleCanExecute
     */
    public final void setConsoleExecutable(boolean consoleCanExecute) {
        this.isConsoleExecutable = consoleCanExecute;
    }

    /**
     * The main execution method for this Command.</br>
     *
     * </br>The only overrideable method of this Command, this method contains the code
     * that your Command will execute when onCall() is callled. The method can be set to
     * return any number of Types, but doing so will break compliance with the API. Also,
     * such Type specification will not work, as the result of this method (void) is
     * returned to the onCall method, which also returns void.</br>
     *
     * </br>If you wish for this Command to return a value other than <strong>void
     * </strong>, you must set the return type of both onExecute() and onCall() so that
     * they both return the same Type.
     */
    private void onExecute(CommandSender sender, String[] args) {
        throw new UnsupportedOperationException(this.getLocalString("NO_IMPLEMENT"));
    }

    /**
     * Returns the Name of this Command.
     * @return String
     */
    public final String getName() {
        return this.name;
    }

    /**
     * Returns the Syntax of this Command, minus the root.
     * @return String
     */
    public final String getSyntax() {
        return this.syntax;
    }

    /**
     * Returns the Help Description text for this Command.
     * @return String
     */
    public final String getHelp() {
        return this.help;
    }

    /**
     * Returns a Permission[] containing all the permissions this Command requires to
     * be executed.
     * @return Permission[]
     */
    public final Permission[] getPermissions() {
        return this.commandPerms;
    }

    /**
     * Returns a boolean denoting whether this command can be executed by the Console or
     * not.
     * @return boolean
     */
    public final boolean canConsoleExecute() {
        return this.isConsoleExecutable;
    }

    /**
     * Returns a String[] containing all the arguments required to be typed by the end
     * user for this Command to be identified by the Command Manager.
     * @return String[]
     */
    public final String[] getCallArgs() {
        return this.callArgs;
    }

    /**
     * Returns an integer of the number of arguments required for this Command to be
     * identified by the Command Manager.
     * @return int
     */
    public final int getArgumentsRequired() {
        return this.requiredArgs;
    }

    /**
     * This method checks the CommandSender Object passed against the permissions this
     * Command requires in order to be executed. If the CS Object has all the required
     * permissions, this method will return <strong>TRUE</strong>, else it will return
     * <strong>FALSE</strong>.
     * @param sender
     * @return boolean
     */
    public final boolean canExecute(CommandSender sender) {
        if (this.commandPerms == null) return true;

        for (int i = 0; i < this.commandPerms.length; i++) {
            if (!sender.hasPermission(this.commandPerms[i])) return false;
        }

        return true;
    }

    /**
     * This method is used to obtain localized messages from the Localization Manager. In
     * order to get a Localized Message, a String <strong><em>key</em></strong> must be
     * passed which corresponds to the message in the Localization Manager.
     * @param key
     * @return String
     */
    private final String getLocalString(String key) {
        return this.LM.getLocalString(key);
    }

}