twilight_mention/
fmt.rs

1//! Formatters for creating mentions.
2
3use super::timestamp::Timestamp;
4use std::fmt::{Display, Formatter, Result as FmtResult, Write};
5use twilight_model::{
6    channel::Channel,
7    guild::{Emoji, Member, Role},
8    id::{
9        marker::{ChannelMarker, CommandMarker, EmojiMarker, RoleMarker, UserMarker},
10        Id,
11    },
12    user::{CurrentUser, User},
13};
14
15/// Formatter to mention a resource that implements `std::fmt::Display`.
16///
17/// # Examples
18///
19/// Mention a `Id<UserMarker>`:
20///
21/// ```
22/// use twilight_mention::Mention;
23/// use twilight_model::id::{marker::UserMarker, Id};
24///
25/// assert_eq!("<@123>", Id::<UserMarker>::new(123).mention().to_string());
26/// ```
27#[derive(Clone, Copy, Debug, Eq, PartialEq)]
28pub struct MentionFormat<T>(T);
29
30/// Mention a channel. This will format as `<#ID>`.
31impl Display for MentionFormat<Id<ChannelMarker>> {
32    fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
33        f.write_str("<#")?;
34        Display::fmt(&self.0, f)?;
35
36        f.write_str(">")
37    }
38}
39
40/// Mention a command. This will format as:
41/// - `</NAME:COMMAND_ID>` for commands
42/// - `</NAME SUBCOMMAND:ID>` for subcommands
43/// - `</NAME SUBCOMMAND_GROUP SUBCOMMAND:ID>` for subcommand groups
44impl Display for MentionFormat<CommandMention> {
45    fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
46        f.write_str("</")?;
47
48        match &self.0 {
49            CommandMention::Command { name, id } => {
50                // </NAME:COMMAND_ID>
51                f.write_str(name)?;
52                f.write_char(':')?;
53                Display::fmt(id, f)?;
54            }
55            CommandMention::SubCommand {
56                name,
57                sub_command,
58                id,
59            } => {
60                // </NAME SUBCOMMAND:ID>
61                f.write_str(name)?;
62                f.write_char(' ')?;
63                f.write_str(sub_command)?;
64                f.write_char(':')?;
65                Display::fmt(id, f)?;
66            }
67            CommandMention::SubCommandGroup {
68                name,
69                sub_command_group,
70                sub_command,
71                id,
72            } => {
73                // </NAME SUBCOMMAND_GROUP SUBCOMMAND:ID>
74                f.write_str(name)?;
75                f.write_char(' ')?;
76                f.write_str(sub_command_group)?;
77                f.write_char(' ')?;
78                f.write_str(sub_command)?;
79                f.write_char(':')?;
80                Display::fmt(id, f)?;
81            }
82        }
83
84        f.write_char('>')
85    }
86}
87
88/// Mention an emoji. This will format as `<:emoji:ID>`.
89impl Display for MentionFormat<Id<EmojiMarker>> {
90    fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
91        f.write_str("<:emoji:")?;
92        Display::fmt(&self.0, f)?;
93
94        f.write_str(">")
95    }
96}
97
98/// Mention a role. This will format as `<@&ID>`.
99impl Display for MentionFormat<Id<RoleMarker>> {
100    fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
101        f.write_str("<@&")?;
102        Display::fmt(&self.0, f)?;
103
104        f.write_str(">")
105    }
106}
107
108/// Mention a user. This will format as `<t:UNIX>` if a style is not specified or
109/// `<t:UNIX:STYLE>` if a style is specified.
110impl Display for MentionFormat<Timestamp> {
111    fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
112        f.write_str("<t:")?;
113        Display::fmt(&self.0.unix(), f)?;
114
115        if let Some(style) = self.0.style() {
116            f.write_str(":")?;
117            Display::fmt(&style, f)?;
118        }
119
120        f.write_str(">")
121    }
122}
123
124/// Mention a user. This will format as `<@ID>`.
125impl Display for MentionFormat<Id<UserMarker>> {
126    fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
127        f.write_str("<@")?;
128        Display::fmt(&self.0, f)?;
129
130        f.write_str(">")
131    }
132}
133
134/// Mention a resource, such as an emoji or user.
135///
136/// This will create a mention that will link to a user if it exists.
137///
138/// Look at the implementations list to see what you can mention.
139///
140/// # Examples
141///
142/// Mention a channel ID:
143///
144/// ```
145/// use twilight_mention::Mention;
146/// use twilight_model::id::{marker::ChannelMarker, Id};
147///
148/// let id = Id::<ChannelMarker>::new(123);
149/// assert_eq!("<#123>", id.mention().to_string());
150/// ```
151pub trait Mention<T> {
152    /// Mention a resource by using its ID.
153    fn mention(&self) -> MentionFormat<T>;
154}
155
156impl<T, M: Mention<T>> Mention<T> for &'_ M {
157    fn mention(&self) -> MentionFormat<T> {
158        (*self).mention()
159    }
160}
161
162/// Mention a channel ID. This will format as `<#ID>`.
163impl Mention<Id<ChannelMarker>> for Id<ChannelMarker> {
164    fn mention(&self) -> MentionFormat<Id<ChannelMarker>> {
165        MentionFormat(*self)
166    }
167}
168
169/// Mention a channel. This will format as `<#ID>`.
170impl Mention<Id<ChannelMarker>> for Channel {
171    fn mention(&self) -> MentionFormat<Id<ChannelMarker>> {
172        MentionFormat(self.id)
173    }
174}
175
176/// Mention a command.
177///
178/// This will format as:
179/// - `</NAME:COMMAND_ID>` for commands
180/// - `</NAME SUBCOMMAND:ID>` for subcommands
181/// - `</NAME SUBCOMMAND_GROUP SUBCOMMAND:ID>` for subcommand groups
182///
183/// # Cloning
184///
185/// This implementation uses [`clone`](Clone::clone) to construct a [`MentionFormat`] that owns the
186/// inner `CommandMention` as [`mention`](Mention::mention) takes a `&self`.
187/// The other implementations do this for types that are [`Copy`] and therefore do not need to use
188/// [`clone`](Clone::clone).
189///
190/// To avoid cloning use [`CommandMention::into_mention`].
191impl Mention<CommandMention> for CommandMention {
192    fn mention(&self) -> MentionFormat<CommandMention> {
193        MentionFormat(self.clone())
194    }
195}
196
197impl CommandMention {
198    /// Mention a command.
199    ///
200    /// This will format as:
201    /// - `</NAME:COMMAND_ID>` for commands
202    /// - `</NAME SUBCOMMAND:ID>` for subcommands
203    /// - `</NAME SUBCOMMAND_GROUP SUBCOMMAND:ID>` for subcommand groups
204    ///
205    /// This is a self-consuming alternative to [`CommandMention::mention`] and avoids cloning.
206    pub const fn into_mention(self) -> MentionFormat<CommandMention> {
207        MentionFormat(self)
208    }
209}
210
211/// Mention the current user. This will format as `<@ID>`.
212impl Mention<Id<UserMarker>> for CurrentUser {
213    fn mention(&self) -> MentionFormat<Id<UserMarker>> {
214        MentionFormat(self.id)
215    }
216}
217
218/// Mention an emoji. This will format as `<:emoji:ID>`.
219impl Mention<Id<EmojiMarker>> for Id<EmojiMarker> {
220    fn mention(&self) -> MentionFormat<Id<EmojiMarker>> {
221        MentionFormat(*self)
222    }
223}
224
225/// Mention an emoji. This will format as `<:emoji:ID>`.
226impl Mention<Id<EmojiMarker>> for Emoji {
227    fn mention(&self) -> MentionFormat<Id<EmojiMarker>> {
228        MentionFormat(self.id)
229    }
230}
231
232/// Mention a member's user. This will format as `<@ID>`.
233impl Mention<Id<UserMarker>> for Member {
234    fn mention(&self) -> MentionFormat<Id<UserMarker>> {
235        MentionFormat(self.user.id)
236    }
237}
238
239/// Mention a role ID. This will format as `<@&ID>`.
240impl Mention<Id<RoleMarker>> for Id<RoleMarker> {
241    fn mention(&self) -> MentionFormat<Id<RoleMarker>> {
242        MentionFormat(*self)
243    }
244}
245
246/// Mention a role ID. This will format as `<@&ID>`.
247impl Mention<Id<RoleMarker>> for Role {
248    fn mention(&self) -> MentionFormat<Id<RoleMarker>> {
249        MentionFormat(self.id)
250    }
251}
252
253/// Mention a timestamp. This will format as `<t:UNIX>` if a style is not
254/// specified or `<t:UNIX:STYLE>` if a style is specified.
255impl Mention<Self> for Timestamp {
256    fn mention(&self) -> MentionFormat<Self> {
257        MentionFormat(*self)
258    }
259}
260
261/// Mention a user ID. This will format as `<&ID>`.
262impl Mention<Id<UserMarker>> for Id<UserMarker> {
263    fn mention(&self) -> MentionFormat<Id<UserMarker>> {
264        MentionFormat(*self)
265    }
266}
267
268/// Mention a user. This will format as `<&ID>`.
269impl Mention<Id<UserMarker>> for User {
270    fn mention(&self) -> MentionFormat<Id<UserMarker>> {
271        MentionFormat(self.id)
272    }
273}
274
275/// Components to construct a slash command mention.
276///
277/// Format slash commands, subcommands and subcommand groups.
278/// See [Discord Docs/Message Formatting].
279/// See [Discord Docs Changelog/Slash Command Mentions].
280///
281/// [Discord Docs/Message Formatting]: https://discord.com/developers/docs/reference#message-formatting
282/// [Discord Docs Changelog/Slash Command Mentions]: https://discord.com/developers/docs/change-log#slash-command-mentions
283#[allow(missing_docs)]
284#[derive(Clone, Debug, Eq, PartialEq)]
285pub enum CommandMention {
286    Command {
287        id: Id<CommandMarker>,
288        name: String,
289    },
290
291    SubCommand {
292        id: Id<CommandMarker>,
293        name: String,
294        sub_command: String,
295    },
296
297    SubCommandGroup {
298        id: Id<CommandMarker>,
299        name: String,
300        sub_command: String,
301        sub_command_group: String,
302    },
303}
304
305#[cfg(test)]
306mod tests {
307    use crate::timestamp::{Timestamp, TimestampStyle};
308
309    use super::{CommandMention, Mention, MentionFormat};
310    use static_assertions::assert_impl_all;
311    use std::fmt::{Debug, Display};
312    use twilight_model::id::marker::CommandMarker;
313    use twilight_model::{
314        channel::Channel,
315        guild::{Emoji, Member, Role},
316        id::{
317            marker::{ChannelMarker, EmojiMarker, RoleMarker, UserMarker},
318            Id,
319        },
320        user::{CurrentUser, User},
321    };
322
323    assert_impl_all!(MentionFormat<()>: Clone, Copy, Debug, Eq, PartialEq, Send, Sync);
324    assert_impl_all!(MentionFormat<Id<ChannelMarker>>: Clone, Copy, Debug, Display, Eq, PartialEq, Send, Sync);
325    assert_impl_all!(MentionFormat<CommandMention>: Clone, Debug, Display, Eq, PartialEq, Send, Sync);
326    assert_impl_all!(MentionFormat<Id<EmojiMarker>>: Clone, Copy, Debug, Display, Eq, PartialEq, Send, Sync);
327    assert_impl_all!(MentionFormat<Id<RoleMarker>>: Clone, Copy, Debug, Display, Eq, PartialEq, Send, Sync);
328    assert_impl_all!(MentionFormat<Id<UserMarker>>: Clone, Copy, Debug, Display, Eq, PartialEq, Send, Sync);
329    assert_impl_all!(Id<ChannelMarker>: Mention<Id<ChannelMarker>>);
330    assert_impl_all!(&'static Id<ChannelMarker>: Mention<Id<ChannelMarker>>);
331    assert_impl_all!(Channel: Mention<Id<ChannelMarker>>);
332    assert_impl_all!(&'static Channel: Mention<Id<ChannelMarker>>);
333    assert_impl_all!(CurrentUser: Mention<Id<UserMarker>>);
334    assert_impl_all!(&'static CurrentUser: Mention<Id<UserMarker>>);
335    assert_impl_all!(Id<EmojiMarker>: Mention<Id<EmojiMarker>>);
336    assert_impl_all!(&'static Id<EmojiMarker>: Mention<Id<EmojiMarker>>);
337    assert_impl_all!(Emoji: Mention<Id<EmojiMarker>>);
338    assert_impl_all!(&'static Emoji: Mention<Id<EmojiMarker>>);
339    assert_impl_all!(Member: Mention<Id<UserMarker>>);
340    assert_impl_all!(&'static Member: Mention<Id<UserMarker>>);
341    assert_impl_all!(Id<RoleMarker>: Mention<Id<RoleMarker>>);
342    assert_impl_all!(&'static Id<RoleMarker>: Mention<Id<RoleMarker>>);
343    assert_impl_all!(Role: Mention<Id<RoleMarker>>);
344    assert_impl_all!(&'static Role: Mention<Id<RoleMarker>>);
345    assert_impl_all!(Id<UserMarker>: Mention<Id<UserMarker>>);
346    assert_impl_all!(&'static Id<UserMarker>: Mention<Id<UserMarker>>);
347    assert_impl_all!(User: Mention<Id<UserMarker>>);
348    assert_impl_all!(&'static User: Mention<Id<UserMarker>>);
349
350    #[test]
351    fn mention_format_channel_id() {
352        assert_eq!(
353            "<#123>",
354            Id::<ChannelMarker>::new(123).mention().to_string()
355        );
356    }
357
358    #[test]
359    fn mention_format_command() {
360        assert_eq!(
361            "</name:123>",
362            MentionFormat(CommandMention::Command {
363                id: Id::<CommandMarker>::new(123),
364                name: "name".to_string()
365            })
366            .to_string()
367        );
368    }
369
370    #[test]
371    fn mention_format_sub_command() {
372        assert_eq!(
373            "</name subcommand:123>",
374            MentionFormat(CommandMention::SubCommand {
375                id: Id::<CommandMarker>::new(123),
376                name: "name".to_string(),
377                sub_command: "subcommand".to_string()
378            })
379            .to_string()
380        );
381    }
382
383    #[test]
384    fn mention_format_sub_command_group() {
385        assert_eq!(
386            "</name subcommand_group subcommand:123>",
387            MentionFormat(CommandMention::SubCommandGroup {
388                id: Id::<CommandMarker>::new(123),
389                name: "name".to_string(),
390                sub_command: "subcommand".to_string(),
391                sub_command_group: "subcommand_group".to_string()
392            })
393            .to_string()
394        );
395    }
396
397    #[test]
398    fn mention_format_emoji_id() {
399        assert_eq!(
400            "<:emoji:123>",
401            Id::<EmojiMarker>::new(123).mention().to_string()
402        );
403    }
404
405    #[test]
406    fn mention_format_role_id() {
407        assert_eq!("<@&123>", Id::<RoleMarker>::new(123).mention().to_string());
408    }
409
410    /// Test that a timestamp with a style displays correctly.
411    #[test]
412    fn mention_format_timestamp_styled() {
413        let timestamp = Timestamp::new(1_624_047_064, Some(TimestampStyle::RelativeTime));
414
415        assert_eq!("<t:1624047064:R>", timestamp.mention().to_string());
416    }
417
418    /// Test that a timestamp without a style displays correctly.
419    #[test]
420    fn mention_format_timestamp_unstyled() {
421        let timestamp = Timestamp::new(1_624_047_064, None);
422
423        assert_eq!("<t:1624047064>", timestamp.mention().to_string());
424    }
425
426    #[test]
427    fn mention_format_user_id() {
428        assert_eq!("<@123>", Id::<UserMarker>::new(123).mention().to_string());
429    }
430}
twilight_mention/fmt.rs

twilight_mention/
fmt.rs
