Command Annotations

Command arguments can be annotated to change how they're parsed. HalpBot comes with a number of built-in annotations as summarised below.

Remaining

Supported Types: String

Returns the rest of the arguments as a single String.

Example:

private final Map<String, String> definitions = new HashMap<>();

@Command(alias = "define", description = "Adds a description for a word to the dictionary")
public String define(String word, @Remaining String definition) {
    word = word.toLowerCase(Locale.ROOT);
    if (this.definitions.containsKey(word))
        return "That word is already defined in the dictionary as: " + this.definitions.get(word);
    else {
        this.definitions.put(word, definition);
        return "Added the word '" + word + "' to the dictionary";
    }
}

Usage: $define HalpBot A robust JDA command framework

Source

Supported Types: MessageChannel, TextChannel, PrivateChannel, User (Message Author), Guild, ChannelType

Retrieves the specified type from the MessageReceivedEvent that invoked the command.

Example:

@Command(alias = "ping", description = "Pings the person who calls this command")
public String ping(@Source User author) {
    return "Haha... " + author.getAsMention();
}

Usage: $ping

Unrequired

Supported Types: All

Marks a parameter as optional. If that parameter is not present, you can specify a default value as a string, this will then be parsed just as though it had been an argument used in the invocation of the command. This default value is null unless specified.

Example:

@Command(alias = "ban", description = "Bans a user from the discord server", permissions = Permission.BAN_MEMBERS)
public String ban(@Source Guild guild, User user,
                  @Remaining @Unrequired("No reason specified") String reason) {

    guild.ban(user, 0).reason(reason).queue();
    return user.getName() + " has been banned from the server";
}

Usage: $ban @pumbas600 or $ban @pumbas600 For being too cool

@Command(alias = "unrequiredDemo")
public void unrequiredDemo(@Unrequired("[]") List<Double> numbers) {
    // If no numbers are specified, then 'numbers' will be an empty list due to the '[]' in the @Unrequired parameter.
}

Usage: $unrequiredDemo or $unrequiredDemo [1 3 4 5.4 3.1]

Implicit

Supported Types: List, Set, Arrays

Allows you to use Collections as arguments when invoking commands without explicitly surrounding the elements with [...]. Do note that this is greedy and will keep adding elements to the Collection until the next argument being parsed is not of the correct type.

Example:

@Command(alias = "average", description = "Returns the average of the specified numbers")
public double average(@Implicit List<Double> numbers) {
    double total = numbers.stream()
        .reduce(0D, Double::sum);
    return total / numbers.size();
}

Usage: $average 10 6.1 5.3 18.4

Id

Supported Types: Long/long

Parses the id of the specified type as a long. This is useful if you only require the id of one of a User, or Member as retrieving the actual User or Member objects can be expensive if they're not cached. The specified type supports: User, Member and TextChannel. Note: JDA doesn't recommend caching their objects as they can become invalidated and no longer able to perform requests. Refer to the official JDA documentation here for more information.

Example:

private final Set<Long> cursedUsers = new HashSet<>();

@Command(alias = "curse", description = "Adds the specified user to the cursed list")
public String curse(@Id(User.class) long id) {
    this.cursedUsers.add(id);
    return "They have been cursed!";
}

Usage: $curse @pumbas600

Unmodifiable

Supported Types: List, Set

You can easily make collection arguments unmodifiable, simply by adding the @Unmodifiable attribute to it.