com.freya02.botcommands.api.commands.application.GuildApplicationSettings Maven / Gradle / Ivy

Go to download
package com.freya02.botcommands.api.commands.application;

import com.freya02.botcommands.api.commands.CommandPath;
import com.freya02.botcommands.api.commands.annotations.GeneratedOption;
import com.freya02.botcommands.api.commands.application.annotations.AppOption;
import com.freya02.botcommands.api.commands.application.annotations.CommandId;
import com.freya02.botcommands.api.commands.application.slash.ApplicationGeneratedValueSupplier;
import com.freya02.botcommands.api.commands.application.slash.annotations.JDASlashCommand;
import com.freya02.botcommands.api.parameters.ParameterType;
import com.freya02.botcommands.api.parameters.SlashParameterResolver;
import net.dv8tion.jda.api.entities.Guild;
import net.dv8tion.jda.api.interactions.commands.Command;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

import java.util.Collection;
import java.util.Collections;
import java.util.List;

/**
 * Interface providing getters for settings commands stuff on a per-guild basis
 */
public interface GuildApplicationSettings {
	/**
	 * Returns the choices available for this command path, on the specific optionIndex (option index starts at 0 and is composed of only the parameters annotated with {@link AppOption @AppOption})
	 *
	 * The choices returned by this method will have their name and values localized if they are present in the BotCommands resource bundles
	 *
	 * 
Note: This method is only used for annotation-declared application commands.
	 *
	 * @param guild       The {@link Guild} in which the command is, might be null for global commands with choices
	 * @param commandPath The {@link CommandPath} of the command, this is composed of it's name and optionally of its group and subcommand name
	 * @param optionName  The option name, this is the same name that appears on Discord
	 *
	 * @return The list of choices for this slash command's options
	 *
	 * @see SlashParameterResolver#getPredefinedChoices(Guild)
	 */
	@NotNull
	default List getOptionChoices(@Nullable Guild guild, @NotNull CommandPath commandPath, @NotNull String optionName) {
		return Collections.emptyList();
	}

	/**
	 * Returns a collection of {@link Guild} IDs in which the specified command ID will be allowed to be pushed in
	 * 
A null return value means that the command can be used in any guild
	 * 
Meanwhile, an empty list means that the command cannot be used anywhere
	 *
	 * 
You will have exceptions later if multiple commands IDs under the same command path share at least one guild ID
	 *
	 * 
Be very cautious with your command IDs.
	 *
	 * @param commandId   The ID of the command that has been set with {@link CommandId}
	 * @param commandPath The {@link CommandPath} of the specified command ID
	 *
	 * @return A collection of Guild IDs where the specified command is allowed to be pushed in
	 * 		
This returns null by default
	 */
	@Nullable
	default Collection getGuildsForCommandId(@NotNull String commandId, @NotNull CommandPath commandPath) {
		return null;
	}

	/**
	 * Returns the generated value supplier of an {@link GeneratedOption}, if the method doesn't return a generated value supplier, the framework will throw.
	 * 
This method is called only if your option is annotated with {@link GeneratedOption}
	 *
	 * This method will only be called once per command option per guild
	 *
	 * @param guild         The {@link Guild} in which to add the default value, null if the scope is not {@link CommandScope#GUILD}
	 * @param commandId     The ID of the command, as optionally set in {@link CommandId}, might be null
	 * @param commandPath   The path of the command, as set in {@link JDASlashCommand}
	 * @param optionName    The name of the transformed command option, might not be equal to the parameter name
	 * @param parameterType The boxed type of the command option
	 *
	 * @return A {@link ApplicationGeneratedValueSupplier} to generate the option on command execution
	 */
	@NotNull
	default ApplicationGeneratedValueSupplier getGeneratedValueSupplier(@Nullable Guild guild,
	                                                                    @Nullable String commandId, @NotNull CommandPath commandPath,
	                                                                    @NotNull String optionName, @NotNull ParameterType parameterType) {
		final StringBuilder errorBuilder = new StringBuilder("Option '%s' in command path '%s'".formatted(optionName, commandPath.getFullPath()));
		if (commandId != null) errorBuilder.append(" (id '%s')".formatted(commandId));
		if (guild != null) errorBuilder.append(" in guild '%s' (id %s)".formatted(guild.getName(), guild.getId()));
		errorBuilder.append(" is a generated option but no generated value supplier has been given");

		throw new IllegalArgumentException(errorBuilder.toString());
	}
}