Argument Parsing

Every command can define the arguments and flags it requires by setting the Args field in its meta. There you can set which required and optional arguments, as well as what flags your command expects.

Choosing an Argument Parser

The syntax expected from the arguments, i.e. the choice of parser, is deliberately specified separately to allow the easy use of third-party commands. By default adam uses a comma based notation (arg.DelimiterParser), however, commands that require custom notations can opt to use a custom parser by specifying the ArgParser field in the command's meta.

If you don't want to use a comma-based notation for any of your arguments, you can change the global parser in the bot's Options by setting bot.Options.ArgParser.

Adam comes with support for two different notations out of the box: Firstly, arg.DelimiterParser, a delimiter-based parser, which allows you to specify a custom delimiter. Secondly, arg.ShellwordParser, a space-delimited shellword parser. You can find more information about the syntactic requirements of both parsers in their respective docs here and here.

There is also the option to use the RawParser. It does not actually parse and simply hands the input to the sole argument as specified in the command meta's Args field.

Types

Before you can start adding Args to your command, you need to understand how an argument or flag is parsed and validated. Every argument and flag has an arg.Type. Type is an interface, and is basically a miniature parser that parses a single argument. There are a lot of built-in Types, but you can also easily create your own, using said interface. Below is a list of all built-in types, with their Go type equivalents in parentheses:

• TextChannel (*discord.Channel) – Text or announcement (news) channels.

• Category (*discord.Channel)

• VoiceChannel (*discord.Channel)

• Emoji (*discord.Emoji)

• RawEmoji (discord.APIEmoji) – The same as Emoji, but not just limited to emojis from the invoking guild.

• Role (*discord.Role)

• User (*discord.User)

• Member (*discord.Member)

• Switch (bool) – Bool type used exclusively for flags.

• Integer (int)

• Decimal (float64)

• NumericID (uint64)

• AlphanumericID (string)

• Text (string)

• Link (string)

• RegularExpression (*regexp.Regexp)

• Code (string) – A Markdown code block.

• Choice (string) – An enum type.

• Duration (time.Duration)

• Time (*time.Time)

• Date (*time.Time)

• DateTime (*time.Time)

• TimeZone (*time.Location)

• Command (*plugin.RegisteredCommand)

• Module (*plugin.RegisteredModule)

• Plugin (nil, *plugin.RegisteredCommand, or *plugin.RegisteredModule)

Examples

mute-Command

To illustrate the usage of an ArgConfig, let's create an ArgConfig for a mute command, that takes in a user, and optionally a reason. Furthermore, the duration of the mute can be specified using a flag.

&arg.Config{
    Required: []arg.RequiredArg{
        {
            Name: "User",
            Type: arg.User,
            Description: "The user that shall be muted.",
        },
    },
    Optional: []arg.OptionalArg{
        {
            Name: "Reason",
            Type: arg.SimpleText,
            Description: "The reason for the mute.",
        },
    },
    Flags: []arg.Flag{
        {
            Name: "duration",
            Aliases: []string{"d"},
            Type: arg.SimpleDuration,
            Description: "The duration to mute the user for.",
        },
    },
}

purge-Command

A purge command is another great example of how ArgConfigs work. In our example, the purge command takes in a required number of messages to delete. The number of messages must be between 1 and 100. Furthermore, we have a user flag, that can be used multiple times to limit the messages to delete to certain users. Lastly, there is also a flag that forces purge to remove pinned messages.

&arg.Config{
    Required: []arg.RequiredArg{
        {
            Name: "Number of Messages",
            Type: &arg.Integer{Min: 1, Max: 100},
            Description: "The number of messages to delete (max. 100).",
        },
    },
    Flags: []arg.Flag{
        {
            Name: "user",
            Aliases: []string{"u"},
            Type: arg.Member,
            Multi: true, // this allows multiple uses of the flag
            Description: "The users to delete messages from.",
        },
        {
            Name: "rm-pins",
            Aliades: []string{"pin", "p"},
            Type: arg.Switch, // Switch is special and can only be used for flags
            Description: "Whether to delete pinned messages as well.",
        },
    },
}