Attribute Macro command_attr::group
source · #[group]
Expand description
Create a grouping of commands.
It is a prerequisite for all commands to be assigned under a common group, before they may be executed by a user.
A group might have one or more prefixes set. This will necessitate for one of the prefixes to
appear before the group’s command. For example, for a general prefix !
, a group prefix foo
and a command bar
, the invocation would be !foo bar
.
It might have some options apply to all of its commands. E.g. guild or dm only.
It may even couple other groups as well.
This group macro purports all of the said purposes above, applied onto a struct
:
use command_attr::{command, group};
#[command]
fn bar() -> CommandResult {
println!("baz");
Ok(())
}
#[command]
fn answer_to_life() -> CommandResult {
println!("42");
Ok(())
}
#[group]
// All sub-groups must own at least one prefix.
#[prefix = "baz"]
#[commands(answer_to_life)]
struct Baz;
#[group]
#[commands(bar)]
// Case does not matter; the names will be all uppercased.
#[sub_groups(baz)]
struct Foo;
§Options
These appear after #[group]
as a series of attributes:
Syntax | Description | Argument explanation |
---|---|---|
#[commands(commands)] | Set of commands belonging to this group. | commands is a comma separated list of identifiers referencing functions marked by the #[command] macro |
#[sub_groups(subs)] | Set of sub groups belonging to this group. | subs is a comma separated list of identifiers referencing structs marked by the #[group] macro |
#[prefixes(prefs)] | Text that must appear before an invocation of a command of this group may occur. | prefs is a comma separated list of strings |
#[prefix(pref)] | Assign just a single prefix. | pref is a string |
#[allowed_roles(roles)] | Set of roles the user must possess | roles is a comma separated list of strings containing role names |
#[only_in(ctx)] | Which environment the command can be executed in. | ctx is a string with the accepted values guild /guilds and dm / dms (Direct Message). |
#[owners_only] #[owners_only(b)] | If this command is exclusive to owners. | b is a boolean. If no boolean is provided, the value is assumed to be true . |
#[owner_privilege] #[owner_privilege(b)] | If owners can bypass certain options. | b is a boolean. If no boolean is provided, the value is assumed to be true . |
#[help_available] #[help_available(b)] | If the group should be displayed in the help message. | b is a boolean. If no boolean is provided, the value is assumed to be true . |
#[checks(identifiers)] | Preconditions that must met before the command’s execution. | identifiers is a comma separated list of identifiers referencing functions marked by the #[check] macro |
#[required_permissions(perms)] | Set of permissions the user must possess. In order for this attribute to work, “Presence Intent” and “Server Member Intent” options in bot application must be enabled and all intent flags must be enabled during client creation. | perms is a comma separated list of permission names.These can be found at Discord’s official documentation. |
#[default_command(cmd)] | A command to execute if none of the group’s prefixes are given. | cmd is an identifier referencing a function marked by the #[command] macro |
#[description(desc)] #[description = desc] | The group’s description or summary. | desc is a string describing the group. |
#[summary(desc)] #[summary = desc] | A summary group description displayed when shown multiple groups. | desc is a string summaryly describing the group. |
Documentation comments (///
) applied onto the struct are interpreted as sugar for the
#[description]
option. When more than one application of the option is performed, the text is
delimited by newlines. This mimics the behaviour of regular doc-comments, which are sugar for
the #[doc = "..."]
attribute. If you wish to join lines together, however, you have to end
the previous lines with \$
.
Similarly to command
, this macro generates static instances of the group and its options.
The identifiers of these instances are based off the name of the struct to differentiate this
group from others. This name is given as the default value of the group’s name
field, used in
the help command for display and browsing of the group. It may also be passed as an argument to
the macro. For example: #[group("Banana Phone")]
.