io.github.freya022.botcommands.api.commands.application.ApplicationCommand.kt Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of BotCommands Show documentation
A Kotlin-first (and Java) framework that makes creating Discord bots a piece of cake, using the JDA library.
There is a newer version: 3.0.0-alpha.23
package io.github.freya022.botcommands.api.commands.application

import io.github.freya022.botcommands.api.commands.CommandPath
import io.github.freya022.botcommands.api.commands.annotations.GeneratedOption
import io.github.freya022.botcommands.api.commands.application.annotations.CommandId
import io.github.freya022.botcommands.api.commands.application.context.annotations.JDAMessageCommand
import io.github.freya022.botcommands.api.commands.application.context.annotations.JDAUserCommand
import io.github.freya022.botcommands.api.commands.application.slash.annotations.JDASlashCommand
import io.github.freya022.botcommands.api.commands.application.slash.options.builder.SlashCommandOptionBuilder
import io.github.freya022.botcommands.api.core.config.BApplicationConfigBuilder
import io.github.freya022.botcommands.api.core.reflect.ParameterType
import io.github.freya022.botcommands.api.parameters.resolvers.SlashParameterResolver
import io.github.freya022.botcommands.internal.utils.throwArgument
import net.dv8tion.jda.api.entities.Guild
import net.dv8tion.jda.api.interactions.commands.Command

/**
 * Base class for **annotated** application commands such as slash / context commands.
 *
 * You are not required to use this if you use the application command provider interfaces.
 *
 * @see JDASlashCommand @JDASlashCommand
 * @see JDAMessageCommand @JDAMessageCommand
 * @see JDAUserCommand @JDAUserCommand
 */
abstract class ApplicationCommand {
    /**
     * Returns the choices available for this command path,
     * on the specific [optionName].
     *
     * The choices returned by this method will have their name localized
     * if they are present in the [localization bundles][BApplicationConfigBuilder.addLocalizations].
     *
     * @param guild       The [Guild] in which the command is, might be `null` for global commands with choices
     * @param commandPath The [CommandPath] of the command, this is composed of it's name and optionally of its group and subcommand name
     * @param optionName  The option name, not the same as the parameter name, this is the same name that appears on Discord
     *
     * @return The list of choices for this slash command's options
     *
     * @see SlashParameterResolver.getPredefinedChoices
     *
     * @see SlashCommandOptionBuilder.choices DSL equivalent
     */
    open fun getOptionChoices(guild: Guild?, commandPath: CommandPath, optionName: String): List {
        return emptyList()
    }

    /**
     * Returns a collection of [Guild] IDs in which the specified command ID will be allowed to be pushed in.
     *
     * Return values:
     * - `null` if the command can be used in any guild
     * - An empty list if the command cannot be used anywhere
     * - A list of guild IDs, where the command will be usable
     *
     * Make sure to not allow more than one command with the same path.
     *
     * @param commandId   The ID of the command that has been set with [@CommandId][CommandId]
     * @param commandPath The [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
     *
     * @see CommandId @CommandId
     */
    @Deprecated(message = "Replaced by DeclarationFilter and CommandDeclarationFilter")
    open fun getGuildsForCommandId(commandId: String, commandPath: CommandPath): Collection? {
        return null
    }

    /**
     * Returns the generated value supplier of a [@GeneratedOption][GeneratedOption].
     *
     * This function will only be called once per command option per guild.
     *
     * @param guild         The [Guild] in which to add the default value, `null` if the scope is **not** [CommandScope.GUILD]
     * @param commandId     The ID of the command, as optionally set in [@CommandId][CommandId], might be `null`
     * @param commandPath   The path of the command, as set in [@JDASlashCommand][JDASlashCommand]
     * @param optionName    The option name, not the same as the parameter name, this is the same name that appears on Discord
     * @param parameterType The **boxed** type of the command option
     *
     * @return A [ApplicationGeneratedValueSupplier] to generate the option on command execution
     */
    open fun getGeneratedValueSupplier(
        guild: Guild?,
        commandId: String?, commandPath: CommandPath,
        optionName: String, parameterType: ParameterType
    ): ApplicationGeneratedValueSupplier {
        val errorStr = buildString {
            append("Option '$optionName' in command path '${commandPath.fullPath}'")
            if (commandId != null) append(" (id '$commandId')")
            if (guild != null) append(" in guild '${guild.name}' (id ${guild.id})")
            append(" is a generated option but no generated value supplier has been given")
        }

        throwArgument(errorStr)
    }
}