net.dv8tion.jda.api.interactions.commands.build.SubcommandData Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of JDA Show documentation
Show all versions of JDA Show documentation
Java wrapper for the popular chat & VOIP service: Discord https://discord.com
/*
* Copyright 2015 Austin Keener, Michael Ritter, Florian Spieß, and the JDA contributors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package net.dv8tion.jda.api.interactions.commands.build;
import net.dv8tion.jda.api.events.interaction.command.CommandAutoCompleteInteractionEvent;
import net.dv8tion.jda.api.interactions.DiscordLocale;
import net.dv8tion.jda.api.interactions.commands.Command;
import net.dv8tion.jda.api.interactions.commands.OptionType;
import net.dv8tion.jda.api.interactions.commands.localization.LocalizationMap;
import net.dv8tion.jda.api.utils.data.DataArray;
import net.dv8tion.jda.api.utils.data.DataObject;
import net.dv8tion.jda.api.utils.data.SerializableData;
import net.dv8tion.jda.internal.utils.Checks;
import net.dv8tion.jda.internal.utils.localization.LocalizationUtils;
import javax.annotation.Nonnull;
import java.util.*;
import java.util.function.Predicate;
import java.util.stream.Stream;
/**
* Builder for a Slash-Command subcommand.
*/
public class SubcommandData implements SerializableData
{
protected final List options = new ArrayList<>(CommandData.MAX_OPTIONS);
protected String name, description;
private final LocalizationMap nameLocalizations = new LocalizationMap(this::checkName);
private final LocalizationMap descriptionLocalizations = new LocalizationMap(this::checkDescription);
private boolean allowRequired = true;
/**
* Create a subcommand builder.
*
* @param name
* The subcommand name, 1-32 lowercase alphanumeric characters
* @param description
* The subcommand description, 1-100 characters
*
* @throws IllegalArgumentException
* If any of the following requirements are not met
*
* - The name must be lowercase alphanumeric (with dash), 1-32 characters long
* - The description must be 1-100 characters long
*
*/
public SubcommandData(@Nonnull String name, @Nonnull String description)
{
setName(name);
setDescription(description);
}
protected void checkName(@Nonnull String name)
{
Checks.inRange(name, 1, 32, "Name");
Checks.matches(name, Checks.ALPHANUMERIC_WITH_DASH, "Name");
Checks.isLowercase(name, "Name");
}
protected void checkDescription(@Nonnull String description)
{
Checks.notEmpty(description, "Description");
Checks.notLonger(description, 100, "Description");
}
/**
* Configure the name
*
* @param name
* The lowercase alphanumeric (with dash) name, 1-32 characters
*
* @throws IllegalArgumentException
* If the name is null, not alphanumeric, or not between 1-32 characters
*
* @return The SubcommandData instance, for chaining
*/
@Nonnull
public SubcommandData setName(@Nonnull String name)
{
checkName(name);
this.name = name;
return this;
}
/**
* Sets a {@link DiscordLocale language-specific} localization of this subcommand's name.
*
* @param locale
* The locale to associate the translated name with
*
* @param name
* The translated name to put
*
* @throws IllegalArgumentException
*
* - If the locale is null
* - If the name is null
* - If the locale is {@link DiscordLocale#UNKNOWN}
* - If the name does not pass the corresponding {@link #setName(String) name check}
*
*
* @return This builder instance, for chaining
*/
@Nonnull
public SubcommandData setNameLocalization(@Nonnull DiscordLocale locale, @Nonnull String name)
{
//Checks are done in LocalizationMap
nameLocalizations.setTranslation(locale, name);
return this;
}
/**
* Sets multiple {@link DiscordLocale language-specific} localizations of this subcommand's name.
*
* @param map
* The map from which to transfer the translated names
*
* @throws IllegalArgumentException
*
* - If the map is null
* - If the map contains an {@link DiscordLocale#UNKNOWN} key
* - If the map contains a name which does not pass the corresponding {@link #setName(String) name check}
*
*
* @return This builder instance, for chaining
*/
@Nonnull
public SubcommandData setNameLocalizations(@Nonnull Map map)
{
//Checks are done in LocalizationMap
nameLocalizations.setTranslations(map);
return this;
}
/**
* Configure the description
*
* @param description
* The description, 1-100 characters
*
* @throws IllegalArgumentException
* If the name is null or not between 1-100 characters
*
* @return The SubcommandData instance, for chaining
*/
@Nonnull
public SubcommandData setDescription(@Nonnull String description)
{
checkDescription(description);
this.description = description;
return this;
}
/**
* Sets a {@link DiscordLocale language-specific} localization of this subcommand's description.
*
* @param locale
* The locale to associate the translated description with
*
* @param description
* The translated description to put
*
* @throws IllegalArgumentException
*
* - If the locale is null
* - If the description is null
* - If the locale is {@link DiscordLocale#UNKNOWN}
* - If the description does not pass the corresponding {@link #setDescription(String) description check}
*
*
* @return This builder instance, for chaining
*/
@Nonnull
public SubcommandData setDescriptionLocalization(@Nonnull DiscordLocale locale, @Nonnull String description)
{
//Checks are done in LocalizationMap
descriptionLocalizations.setTranslation(locale, description);
return this;
}
/**
* Sets multiple {@link DiscordLocale language-specific} localizations of this subcommand's description.
*
* @param map
* The map from which to transfer the translated descriptions
*
* @throws IllegalArgumentException
*
* - If the map is null
* - If the map contains an {@link DiscordLocale#UNKNOWN} key
* - If the map contains a description which does not pass the corresponding {@link #setDescription(String) description check}
*
*
* @return This builder instance, for chaining
*/
@Nonnull
public SubcommandData setDescriptionLocalizations(@Nonnull Map map)
{
//Checks are done in LocalizationMap
descriptionLocalizations.setTranslations(map);
return this;
}
/**
* Removes all options that evaluate to {@code true} under the provided {@code condition}.
*
* Example: Remove all options
*
{@code
* command.removeOptions(option -> true);
* }
* Example: Remove all options that are required
*
{@code
* command.removeOptions(option -> option.isRequired());
* }
*
* @param condition
* The removal condition (must not throw)
*
* @throws IllegalArgumentException
* If the condition is null
*
* @return True, if any options were removed
*/
public boolean removeOptions(@Nonnull Predicate condition)
{
Checks.notNull(condition, "Condition");
return options.removeIf(condition);
}
/**
* Removes options by the provided name.
*
* @param name
* The case-sensitive option name
*
* @return True, if any options were removed
*/
public boolean removeOptionByName(@Nonnull String name)
{
return removeOptions(option -> option.getName().equals(name));
}
/**
* Adds up to {@value CommandData#MAX_OPTIONS} options to this subcommand.
*
* Required options must be added before non-required options!
*
* @param options
* The {@link OptionData options} to add
*
* @throws IllegalArgumentException
*
* - If this option is required and you already added a non-required option.
* - If more than {@value CommandData#MAX_OPTIONS} options are provided.
* - If the option name is not unique
* - If null is provided
*
*
* @return The SubcommandData instance, for chaining
*/
@Nonnull
public SubcommandData addOptions(@Nonnull OptionData... options)
{
Checks.noneNull(options, "Option");
Checks.check(options.length + this.options.size() <= CommandData.MAX_OPTIONS, "Cannot have more than %d options for a subcommand!", CommandData.MAX_OPTIONS);
boolean allowRequired = this.allowRequired;
for (OptionData option : options)
{
Checks.check(option.getType() != OptionType.SUB_COMMAND, "Cannot add a subcommand to a subcommand!");
Checks.check(option.getType() != OptionType.SUB_COMMAND_GROUP, "Cannot add a subcommand group to a subcommand!");
Checks.check(allowRequired || !option.isRequired(), "Cannot add required options after non-required options!");
allowRequired = option.isRequired(); // prevent adding required options after non-required options
}
Checks.checkUnique(Stream.concat(getOptions().stream(), Arrays.stream(options)).map(OptionData::getName),
"Cannot have multiple options with the same name. Name: \"%s\" appeared %d times!",
(count, value) -> new Object[]{ value, count });
this.allowRequired = allowRequired;
this.options.addAll(Arrays.asList(options));
return this;
}
/**
* Adds up to {@value CommandData#MAX_OPTIONS} options to this subcommand.
*
* Required options must be added before non-required options!
*
* @param options
* The {@link OptionData options} to add
*
* @throws IllegalArgumentException
*
* - If this option is required and you already added a non-required option.
* - If more than {@value CommandData#MAX_OPTIONS} options are provided.
* - If the option name is not unique
* - If null is provided
*
*
* @return The SubcommandData instance, for chaining
*/
@Nonnull
public SubcommandData addOptions(@Nonnull Collection options)
{
Checks.noneNull(options, "Options");
return addOptions(options.toArray(new OptionData[0]));
}
/**
* Adds an option to this subcommand.
*
* Required options must be added before non-required options!
*
* @param type
* The {@link OptionType}
* @param name
* The lowercase option name, 1-{@value OptionData#MAX_NAME_LENGTH} characters
* @param description
* The option description, 1-{@value OptionData#MAX_DESCRIPTION_LENGTH} characters
* @param required
* Whether this option is required (See {@link OptionData#setRequired(boolean)})
* @param autoComplete
* Whether this option supports auto-complete via {@link CommandAutoCompleteInteractionEvent},
* only supported for option types which {@link OptionType#canSupportChoices() support choices}
*
* @throws IllegalArgumentException
*
* - If this option is required and you already added a non-required option.
* - If the provided option type does not support auto-complete
* - If more than {@value CommandData#MAX_OPTIONS} options are provided.
* - If the option name is not unique
* - If null is provided
*
*
* @return The SubcommandData instance, for chaining
*/
@Nonnull
public SubcommandData addOption(@Nonnull OptionType type, @Nonnull String name, @Nonnull String description, boolean required, boolean autoComplete)
{
return addOptions(new OptionData(type, name, description)
.setRequired(required)
.setAutoComplete(autoComplete));
}
/**
* Adds an option to this subcommand.
*
* Required options must be added before non-required options!
*
* @param type
* The {@link OptionType}
* @param name
* The lowercase option name, 1-{@value OptionData#MAX_NAME_LENGTH} characters
* @param description
* The option description, 1-{@value OptionData#MAX_DESCRIPTION_LENGTH} characters
* @param required
* Whether this option is required (See {@link OptionData#setRequired(boolean)})
*
* @throws IllegalArgumentException
*
* - If this option is required and you already added a non-required option.
* - If more than {@value CommandData#MAX_OPTIONS} options are provided.
* - If the option name is not unique
* - If null is provided
*
*
* @return The SubcommandData instance, for chaining
*/
@Nonnull
public SubcommandData addOption(@Nonnull OptionType type, @Nonnull String name, @Nonnull String description, boolean required)
{
return addOption(type, name, description, required, false);
}
/**
* Adds an option to this subcommand.
*
The option is set to be non-required! You can use {@link #addOption(OptionType, String, String, boolean)} to add a required option instead.
*
* Required options must be added before non-required options!
*
* @param type
* The {@link OptionType}
* @param name
* The lowercase option name, 1-{@value OptionData#MAX_NAME_LENGTH} characters
* @param description
* The option description, 1-{@value OptionData#MAX_DESCRIPTION_LENGTH} characters
*
* @throws IllegalArgumentException
*
* - If this option is required and you already added a non-required option.
* - If more than {@value CommandData#MAX_OPTIONS} options are provided.
* - If the option name is not unique
* - If null is provided
*
*
* @return The SubcommandData instance, for chaining
*/
@Nonnull
public SubcommandData addOption(@Nonnull OptionType type, @Nonnull String name, @Nonnull String description)
{
return addOption(type, name, description, false);
}
/**
* The options for this command.
*
* @return Immutable list of {@link OptionData}
*/
@Nonnull
public List getOptions()
{
return Collections.unmodifiableList(options);
}
/**
* The configured name
*
* @return The name
*/
@Nonnull
public String getName()
{
return name;
}
/**
* The localizations of this subcommand's name for {@link DiscordLocale various languages}.
*
* @return The {@link LocalizationMap} containing the mapping from {@link DiscordLocale} to the localized name
*/
@Nonnull
public LocalizationMap getNameLocalizations()
{
return nameLocalizations;
}
/**
* The configured description
*
* @return The description
*/
@Nonnull
public String getDescription()
{
return description;
}
/**
* The localizations of this subcommand's description for {@link DiscordLocale various languages}.
*
* @return The {@link LocalizationMap} containing the mapping from {@link DiscordLocale} to the localized description
*/
@Nonnull
public LocalizationMap getDescriptionLocalizations()
{
return descriptionLocalizations;
}
@Nonnull
@Override
public DataObject toData()
{
return DataObject.empty()
.put("type", OptionType.SUB_COMMAND.getKey())
.put("name", name)
.put("name_localizations", nameLocalizations)
.put("description", description)
.put("description_localizations", descriptionLocalizations)
.put("options", DataArray.fromCollection(options));
}
/**
* Parses the provided serialization back into an SubcommandData instance.
*
This is the reverse function for {@link #toData()}.
*
* @param json
* The serialized {@link DataObject} representing the subcommand
*
* @throws net.dv8tion.jda.api.exceptions.ParsingException
* If the serialized object is missing required fields
* @throws IllegalArgumentException
* If any of the values are failing the respective checks such as length
*
* @return The parsed SubcommandData instance, which can be further configured through setters
*/
@Nonnull
public static SubcommandData fromData(@Nonnull DataObject json)
{
String name = json.getString("name");
String description = json.getString("description");
SubcommandData sub = new SubcommandData(name, description);
json.optArray("options").ifPresent(arr ->
arr.stream(DataArray::getObject)
.map(OptionData::fromData)
.forEach(sub::addOptions)
);
sub.setNameLocalizations(LocalizationUtils.mapFromProperty(json, "name_localizations"));
sub.setDescriptionLocalizations(LocalizationUtils.mapFromProperty(json, "description_localizations"));
return sub;
}
/**
* Converts the provided {@link Command.Subcommand} into a SubCommandData instance.
*
* @param subcommand
* The subcommand to convert
*
* @throws IllegalArgumentException
* If null is provided or the subcommand has illegal configuration
*
* @return An instance of SubCommandData
*/
@Nonnull
public static SubcommandData fromSubcommand(@Nonnull Command.Subcommand subcommand)
{
Checks.notNull(subcommand, "Subcommand");
SubcommandData data = new SubcommandData(subcommand.getName(), subcommand.getDescription());
data.setNameLocalizations(subcommand.getNameLocalizations().toMap());
data.setDescriptionLocalizations(subcommand.getDescriptionLocalizations().toMap());
subcommand.getOptions()
.stream()
.map(OptionData::fromOption)
.forEach(data::addOptions);
return data;
}
}