Command Arguments

Written for HalpBot-Core-1.0.1

In HalpBot, method parameters are automatically assumed to be command arguments except in the following 3 situations:

1. The parameter type extends GenericEvent (E.g: MessageReceivedEvent). Instead, it'll pass the MessageReceivedEvent that JDA received when the command was called.

2. The parameter type extends AbstractCommandAdapter (E.g: TokenCommandAdapter). Instead, it'll pass the TokenCommandAdapter that the command is registered to.

3. The parameter is annotated with @Source. This tells HalpBot that the parameter is meant to be extracted from the MessageReceivedEvent (Just so that you don't have to).

Supported Types

HalpBot comes with built-in parsers that handle the most commonly used types.

Type	Notes
Byte/byte
Short/short
Integer/int
Long/long
Float/float
Double/double
Character/char
Boolean/bool	true is considered to be any of: true, yes, t, y (Not case-sensitive). Anything else will be false
String	By default this only captures a single word
Enums	Not case-sensitive
List	Returns ArrayList. By default, you need to surround the elements with [...]
Set	Returns HashSet. By default, you need to surround the elements with [...]
Arrays	By default, you need to surround the elements with [...]
TextChannel	A text channel specified by #channel-name. Note: For performance reasons, if you just need the id use a long annotated with @Id(TextChannel.class)
User	The user specified by @username. Note: For performance reasons, if you just need the id use a long annotated with @Id(User.class)
Member	The member specified by @username. Note: For performance reasons, if you just need the id use a long annotated with @Id(Member.class)
Default Object Parser	See this for more information
MessageReceivedEvent	Returns the MessageReceivedEvent that invoked the command
AbstractCommandAdapter	Returns the AbstractCommandAdapter that the command is registered to

Built-In Annotations

Remaining

Supported Types: String

Returns the rest of the arguments as a single String.

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.

@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.

@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.

@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();
}

Id

Supported Types: Long/long

Custom Objects

Reflections

Custom Type Parsers