Command Annotations

Written for HalpBot-Core-1.0.1

Command arguments can be annotated to change how they're parsed by HalpBot. Annotations are useful for hiding away and reusing parsing rules and can be easily created using TypeParsers as described here. That being said, HalpBot does comes with a number of built-in annotations as summarised below.

A parameter can have as many annotations as you like and be in any order.

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.

Example:

@Command(alias = "unmodifiableDemo", description = "Shows how to use the unmodifiable annotation")
public void unmodifiableDemo(@Implicit @Unmodifiable List<String> words) {
    // The list will not be mutable due to the @Unmodifiable annotation. 
}

Usage: $unmodifiableDemo These words will be collected in an unmodifiable list