twilight_interactions/command/
mod.rs

1//! Slash command parsing and creation.
2//!
3//!
4//! # Slash commands
5//! This crate provides parsing slash command data as typed structs. It also
6//! provides a convenient way to register commands from these structs. Derive
7//! macros are provided to automatically implement related traits.
8//!
9//! - Command parsing with the [`CommandModel`] trait.
10//! - Command creation with the [`CreateCommand`] trait.
11//! - Support for subcommands and subcommand groups.
12//! - Command option choices with the [`CommandOption`] and [`CreateOption`]
13//!   traits.
14//!
15//! Read the documentation of the [`CommandModel`] and [`CreateCommand`] traits
16//! for more information and the complete list of supported attributes.
17//!
18//! ## Example
19//! ```
20//! use twilight_interactions::command::{CommandModel, CreateCommand, ResolvedUser};
21//!
22//! #[derive(CommandModel, CreateCommand)]
23//! #[command(name = "hello", desc = "Say hello")]
24//! struct HelloCommand {
25//!     /// The message to send.
26//!     message: String,
27//!     /// The user to send the message to.
28//!     user: Option<ResolvedUser>,
29//! }
30//! ```
31//!
32//! For a more complete example, see the [`examples/xkcd-bot`] directory in the
33//! library repository.
34//!
35//! [`examples/xkcd-bot`]:
36//!     https://github.com/baptiste0928/twilight-interactions/tree/main/examples/xkcd-bot
37//!
38//! ## Localization
39//! Command names and descriptions can be localized using the
40//! `name_localizations` and `desc_localizations` attributes on the command
41//! structs and fields.
42//!
43//! - For command names, you should provide the `name` attribute with the
44//!   default command name, and `name_localizations` with the name of a function
45//!   that returns a [`NameLocalizations`] struct.
46//!
47//! - For description, you should only provide the `name_localizations`
48//!   attribute with the name of a function that returns a [`DescLocalizations`]
49//!   struct.
50//!
51//!   These structs take a list of tuples, where the first tuple element is a
52//!   valid [Discord locale] and the second tuple element is the localized
53//!   value.
54//!
55//! [Discord locale]: https://discord.com/developers/docs/reference#locales
56//!
57//! ```
58//! use twilight_interactions::command::{
59//!     CommandModel, CreateCommand, ResolvedUser, NameLocalizations, DescLocalizations
60//! };
61//!
62//! #[derive(CommandModel, CreateCommand)]
63//! #[command(
64//!     name = "hello",
65//!     name_localizations = "hello_name",
66//!     desc_localizations = "hello_desc"
67//! )]
68//! struct HelloCommand;
69//!
70//! pub fn hello_name() -> NameLocalizations {
71//!     NameLocalizations::new([("fr", "bonjour"), ("de", "hallo")])
72//! }
73//!
74//! pub fn hello_desc() -> DescLocalizations {
75//!     DescLocalizations::new("Say hello", [("fr", "Dis bonjour"), ("de", "Sag Hallo")])
76//! }
77//! ```
78//!
79//! ## Supported types
80//! The [`CommandOption`] and [`CreateOption`] traits are implemented for the
81//! following types:
82//!
83//! | Command option type | Provided implementations                       |
84//! |---------------------|------------------------------------------------|
85//! | `STRING`            | [`String`], [`Cow`]                            |
86//! | `INTEGER`           | [`i64`]                                        |
87//! | `NUMBER`            | [`f64`]                                        |
88//! | `BOOLEAN`           | [`bool`]                                       |
89//! | `USER`              | [`ResolvedUser`], [`User`], [`Id<UserMarker>`] |
90//! | `CHANNEL`           | [`InteractionChannel`], [`Id<ChannelMarker>`]  |
91//! | `ROLE`              | [`Role`], [`Id<RoleMarker>`]                   |
92//! | `MENTIONABLE`       | [`ResolvedMentionable`], [`Id<GenericMarker>`] |
93//! | `ATTACHMENT`        | [`Attachment`], [`Id<AttachmentMarker>`]       |
94//!
95//! Option choices are supported for the `STRING`, `INTEGER` and `NUMBER` option
96//! types. See the [`CommandOption`] and [`CreateOption`] traits documentation
97//! for more information.
98//!
99//! [`from_interaction`]: CommandModel::from_interaction
100//!
101//! [`Cow`]: std::borrow::Cow
102//! [`User`]: twilight_model::user::User
103//! [`Id<UserMarker>`]: twilight_model::id::Id
104//! [`InteractionChannel`]:
105//!     twilight_model::application::interaction::InteractionChannel
106//! [`Id<ChannelMarker>`]: twilight_model::id::Id
107//! [`Role`]: twilight_model::guild::Role
108//! [`Id<RoleMarker>`]: twilight_model::id::Id
109//! [`Id<GenericMarker>`]: twilight_model::id::Id
110//! [`Attachment`]: twilight_model::channel::Attachment
111//! [`Id<AttachmentMarker>`]: twilight_model::id::Id
112
113mod command_model;
114mod create_command;
115
116#[doc(hidden)]
117pub mod internal;
118
119pub use command_model::{
120    AutocompleteValue, CommandInputData, CommandModel, CommandOption, ResolvedMentionable,
121    ResolvedUser,
122};
123pub use create_command::{
124    ApplicationCommandData, CreateCommand, CreateOption, DescLocalizations, NameLocalizations,
125};
126#[cfg(feature = "derive")]
127#[cfg_attr(docsrs, doc(cfg(feature = "derive")))]
128pub use twilight_interactions_derive::{CommandModel, CommandOption, CreateCommand, CreateOption};
twilight_interactions/command/mod.rs

twilight_interactions/command/
mod.rs
