package com.jcwhatever.bukkit.generic.commands;

import java.util.Collection;

import javax.annotation.Nullable;

import org.bukkit.command.CommandSender;
import org.bukkit.inventory.ItemStack;

/**
 * Represents an implementation that processes command arguments as needed.
 *
 * <p>Commands can request parameters by name and have them parsed into the expected
 * object type at the same time. If the parameter has no provided value, cannot be parsed
 * or required conditions for parsing the object are not met, an {@code InvalidValueException}
 * is thrown and should be caught by the command handler.</p>
 *
 * @author JC The Pants
 *
 */
public interface ICommandArguments {

    /**
     * The number of arguments in the collection.
     *
     * <p>Includes arguments automatically added due to the
     * parameter having a default value.</p>
     *
     * @return
     */
    public int size();

    /**
     * The number of arguments expected.
     *
     * <p>Used by the command handler to quickly determine if the number of
     * arguments provided is valid.</p>
     *
     * @return
     */
    public int expectedSize();

    /**
     * Get an {@code ICommandParameter} by index
     *
     * @param index  The index position of the parameter as provided by the command sender
     *
     * @return
     */
    @Nullable
    public ICommandArgument get(int index);

    /**
     * Get an argument as a {@code String} and ensures it meets proper naming conventions.
     *
     * <p>The name must be alphanumeric characters only, must not start with a number,
     * no spaces, underscores are allowed. Must be no more than 16 characters in length.</p>
     *
     * @param parameterName  The name of the parameter to get
     *
     * @return {@code String}
     *
     * @throws InvalidValueException
     */
	public String getName(String parameterName) throws InvalidValueException;

	/**
     * Get an argument as a {@code String} and ensures it meets proper naming conventions.
     *
     * <p>The name must be alphanumeric characters only, must not start with a number,
     * no spaces, underscores are allowed. </p>
     *
     * @param parameterName  The name of the arguments parameter
     * @param maxLen         The maximum length of the value
     *
     * @return {@code String}
     *
     * @throws InvalidValueException
     */
	public String getName(String parameterName, int maxLen) throws InvalidValueException;

	/**
	 * Get an argument as a string.
	 *
	 * @param parameterName  The name of the arguments parameter
	 *
	 * @return {@code String}
	 *
	 * @throws InvalidValueException
	 */
	public String getString(String parameterName) throws InvalidValueException;

	/**
	 * Get an argument as a character.
	 *
	 * @param parameterName  The name of the arguments parameter
	 *
	 * @return {@code char}
	 *
	 * @throws InvalidValueException
	 */
	public char getChar(String parameterName) throws InvalidValueException;

	/**
	 * Gets an argument as an integer.
	 *
	 * @param parameterName  The name of the arguments parameter
	 *
	 * @return {@code int}
	 *
	 * @throws InvalidValueException
	 */
	public int getInt(String parameterName) throws InvalidValueException;

	/**
	 * Gets an argument as a short.
	 *
	 * @param parameterName  The name of the arguments parameter
	 *
	 * @return {@code short}
	 *
	 * @throws InvalidValueException
	 */
	public short getShort(String parameterName) throws InvalidValueException;

	/**
	 * Gets an argument as a byte.
	 *
	 * @param parameterName  The name of the arguments parameter
	 *
	 * @return {@code byte}
	 *
	 * @throws InvalidValueException
	 */
	public byte getByte(String parameterName) throws InvalidValueException;

	/**
	 * Gets an argument as a double.
	 *
	 * @param parameterName  The name of the arguments parameter
	 *
	 * @return {@code double}
	 *
	 * @throws InvalidValueException
	 */
	public double getDouble(String parameterName) throws InvalidValueException;

	/**
	 * Gets an argument as a float.
	 *
	 * @param parameterName  The name of the arguments parameter
	 *
	 * @return {@code float}
	 *
	 * @throws InvalidValueException
	 */
	public float getFloat(String parameterName) throws InvalidValueException;

	/**
	 * Gets an argument as a boolean.
	 *
	 * <p>true,on,yes = true</p>
	 * <p>false,off,no = false</p>
	 *
	 * @param parameterName  The name of the arguments parameter
	 *
	 * @return {@code boolean}
	 *
	 * @throws InvalidValueException
	 */
	public boolean getBoolean(String parameterName) throws InvalidValueException;

	/**
	 * Gets an argument as a double. "%" characters are ignored.
	 *
	 * @param parameterName  The name of the arguments parameter
	 *
	 * @return {@code double}
	 *
	 * @throws InvalidValueException
	 */
	public double getPercent(String parameterName) throws InvalidValueException;

	/**
	 * Gets an arguments raw {@code String} value, splits it at the space character
	 * and returns it as a {@code String[]}
	 *
	 * @param parameterName  The name of the arguments parameter
	 *
	 * @return {@code String[]}
	 */
	public String[] getParams(String parameterName) throws InvalidValueException;

	/**
	 * Gets an argument as an {@code ItemStack[]}.
	 *
	 * <p>The supplied argument can be a parsable string representing an {@code ItemStack}</p>
	 *
	 * <p>The supplied argument can also be "inhand" for the stack in the players hand,
	 * "inventory" to return all items in the players inventory, or "hotbar" to return
	 * all items in the players hotbar. All items returned from the player are cloned objects.</p>
	 *
	 * <p>Use getString(parameterName) method on the same parameter to determine if the player
	 * typed "inhand", "inventory", or "hotbar" if that information is needed.</p>
	 *
	 * <p>If the command sender is not a player, and therefore has no inventory, the argument
	 * will only be valid if a parsable item stack string was provided.</p>
	 *
	 * @param sender         The {@code CommandSender} who executed the command
	 * @param parameterName  The name of the arguments parameter
	 *
	 * @return {@code ItemStack[]}
	 *
	 * @throws InvalidValueException
	 */
	public ItemStack[] getItemStack(CommandSender sender, String parameterName) throws InvalidValueException;

	/**
	 * Gets an argument as a location.
	 *
	 * <p>Possible values are "current" or "select"</p>
	 *
	 * <p>If the argument value is "current", the players current location is returned via
	 * the {@code LocationHandler}.</p>
	 *
	 * <p>If the argument value is "select", the player is asked to click on the location
	 * to be selected and the value is return via the {@code LocationHandler}.</p>
	 *
	 * <p>If the {@CommandSender} is not a player the argument is always considered invalid.</p>
	 *
	 * @param sender           The {@code CommandSender} who executed the command
	 * @param parameterName    The name of the arguments parameter
	 * @param locationHandler  The {@code LocationHandler} responsible for dealing with the return location.
	 *
	 * @throws InvalidValueException
	 */
	public void getLocation(CommandSender sender, String parameterName, LocationHandler locationHandler) throws InvalidValueException;

	/**
	 * Gets an argument as an enum. The argument must be the name of the enum constant and
	 * is not case sensitive, unless there are case conflicts.
	 *
	 * @param parameterName  The name of the arguments parameter
	 * @param enumClass      The enums class
	 *
	 * @return
	 *
	 * @throws InvalidValueException
	 */
	public <T extends Enum<T>> T getEnum(String parameterName, Class<T> enumClass) throws InvalidValueException;

	/**
     * Gets an argument as an enum. The argument must be the name of the enum constant and
     * is not case sensitive, unless there are case conflicts.
     *
     * <p>Valid values can be specified to prevent all of an enums constants from being valid.
     * Use if you have no control over the enum and it isn't practical to make a
     * new enum.</p>
	 *
	 * @param parameterName  The name of the arguments parameter
	 * @param enumClass      The enums class
	 * @param validValues    an array of valid enum constants
	 *
	 * @return
	 *
	 * @throws InvalidValueException
	 */
	public <T extends Enum<T>> T getEnum(String parameterName, Class<T> enumClass, T[] validValues) throws InvalidValueException;

	/**
     * Gets an argument as an enum. The argument must be the name of the enum constant and
     * is not case sensitive, unless there are case conflicts.
     *
     * <p>Valid values can be specified to prevent all of an enums constants from being valid.
     * Use if you have no control over the enum and it isn't practical to make a
     * new enum.</p>
	 *
	 * @param parameterName  The name of the arguments parameter
	 * @param enumClass      The enums class
	 * @param validValues    A collection of valid enum constants
	 *
	 * @return
	 *
	 * @throws InvalidValueException
	 */
	public <T extends Enum<T>> T getEnum(String parameterName, Class<T> enumClass, Collection<T> validValues) throws InvalidValueException;


	/**
	 * Determine if an argument is provided.
	 *
	 * @param parameterName  The name of the arguments parameter
	 *
	 * @return
	 */
	public boolean hasValue(String parameterName);

	/**
	 * Determine if an argument is provided.
	 *
	 * @param parameterName  The name of the arguments parameter
	 *
	 * @return
	 */
	public boolean hasString(String parameterName);

	/**
	 * Determine if an argument is provided and is a single character.
	 *
	 * @param parameterName  The name of the arguments parameter
	 *
	 * @return
	 */
	public boolean hasChar(String parameterName);

	/**
	 * Determine if an argument is provided and can be used as an integer value.
	 *
	 * @param parameterName  The name of the arguments parameter
	 *
	 * @return
	 */
	public boolean hasInt(String parameterName);

	/**
	 * Determine if an argument is provided and can be used as a short value.
	 *
	 * @param parameterName  The name of the arguments parameter
	 *
	 * @return
	 */
	public boolean hasShort(String parameterName);

	/**
	 * Determine if an argument is provided and can be used as a byte value.
	 *
	 * @param parameterName  The name of the arguments parameter
	 *
	 * @return
	 */
	public boolean hasByte(String parameterName);

	/**
	 * Determine if an argument is provided and can be used as a double value.
	 *
	 * @param parameterName  The name of the arguments parameter
	 *
	 * @return
	 */
	public boolean hasDouble(String parameterName);

	/**
	 * Determine if an argument is provided and can be used as a float value.
	 *
	 * @param parameterName  The name of the arguments parameter
	 *
	 * @return
	 */
	public boolean hasFloat(String parameterName);

	/**
	 * Determine if an argument is provided and can be used as a boolean value.
	 *
	 * @param parameterName  The name of the arguments parameter
	 * @return
	 */
	public boolean hasBoolean(String parameterName);

	/**
	 * Determine if an argument is provided and can be used as an item stack array.
	 *
	 * @param parameterName  The name of the arguments parameter
	 * @return
	 */
	public boolean hasItemStack(String parameterName);

	/**
	 * Determine if an argument is provided and can be used as a double value.
	 *
	 * <p>A '%' character in the value will not invalidate the argument.</p>
	 *
	 * @param parameterName  The name of the arguments parameter
	 * @return
	 */
	public boolean hasPercent(String parameterName);

	/**
	 * Determine if an argument is provided and can be used as an enum.
	 *
	 * @param parameterName  The name of the arguments parameter
	 * @param enumClass      The enum class the argument must be used as
	 * @return
	 */
	public <T extends Enum<T>> boolean hasEnum(String parameterName, Class<T> enumClass);




}