1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
use std::default::Default;
use std::fmt;
use ::model::{ChannelId, Emoji, Mentionable, RoleId, UserId};
/// The Message Builder is an ergonomic utility to easily build a message,
/// by adding text and mentioning mentionable structs.
///
/// The finalized value can be accessed via [`build`] or the inner value.
///
/// # Examples
///
/// Build a message, mentioning a [`user`] and an [`emoji`], and retrieving the
/// value:
///
/// ```rust,ignore
/// use serenity::utils::MessageBuilder;
///
/// // assuming an `emoji` and `user` have already been bound
///
/// let content = MessageBuilder::new()
/// .push("You sent a message, ")
/// .mention(user)
/// .push("! ")
/// .mention(emoji)
/// .build();
/// ```
///
/// [`build`]: #method.build
/// [`emoji`]: #method.emoji
/// [`user`]: #method.user
pub struct MessageBuilder(pub String);
impl MessageBuilder {
/// Creates a new, empty-content builder.
pub fn new() -> MessageBuilder {
MessageBuilder::default()
}
/// Pulls the inner value out of the builder.
///
/// # Examples
///
/// This is equivilant to simply retrieving the tuple struct's first value:
///
/// ```rust
/// use serenity::utils::MessageBuilder;
///
/// let content = MessageBuilder::new().push("test").0;
///
/// assert_eq!(content, "test");
/// ```
pub fn build(self) -> String {
self.0
}
/// Mentions the [`PublicChannel`] in the built message.
///
/// This accepts anything that converts _into_ a [`ChannelId`]. Refer to
/// `ChannelId`'s documentation for more information.
///
/// Refer to `ChannelId`'s [Display implementation] for more information on
/// how this is formatted.
///
/// [`ChannelId`]: ../model/struct.ChannelId.html
/// [`PublicChannel`]: ../model/struct.PublicChannel.html
/// [Display implementation]: ../model/struct.ChannelId.html#method.fmt-1
pub fn channel<C: Into<ChannelId>>(mut self, channel: C) -> Self {
self.0.push_str(&format!("{}", channel.into()));
self
}
/// Displays the given emoji in the built message.
///
/// Refer to `Emoji`s [Display implementation] for more information on how
/// this is formatted.
///
/// [Display implementation]: ../model/struct.Emoji.html#method.fmt
pub fn emoji(mut self, emoji: Emoji) -> Self {
self.0.push_str(&format!("{}", emoji));
self
}
/// Mentions something that implements the [`Mentionable`] trait.
///
/// [`Mentionable`]: ../model/trait.Mentionable.html
pub fn mention<M: Mentionable>(mut self, item: M) -> Self {
self.0.push_str(&item.mention());
self
}
/// Pushes a string to the internal message content.
///
/// Note that this does not mutate either the given data or the internal
/// message content in anyway prior to appending the given content to the
/// internal message.
///
/// # Examples
///
/// ```rust
/// use serenity::utils::MessageBuilder;
///
/// let message = MessageBuilder::new().push("test");
///
/// assert_eq!(message.push("ing").0, "testing");
/// ```
pub fn push(mut self, content: &str) -> Self {
self.0.push_str(content);
self
}
/// Mentions the [`Role`] in the built message.
///
/// This accepts anything that converts _into_ a [`RoleId`]. Refer to
/// `RoleId`'s documentation for more information.
///
/// Refer to `RoleId`'s [Display implementation] for more information on how
/// this is formatted.
///
/// [`Role`]: ../model/struct.Role.html
/// [`RoleId`]: ../model/struct.RoleId.html
/// [Display implementation]: ../model/struct.RoleId.html#method.fmt-1
pub fn role<R: Into<RoleId>>(mut self, role: R) -> Self {
self.0.push_str(&format!("{}", role.into()));
self
}
/// Mentions the [`User`] in the built message.
///
/// This accepts anything that converts _into_ a [`UserId`]. Refer to
/// `UserId`'s documentation for more information.
///
/// Refer to `UserId`'s [Display implementation] for more information on how
/// this is formatted.
///
/// [`User`]: ../model/struct.User.html
/// [`UserId`]: ../model/struct.UserId.html
/// [Display implementation]: ../model/struct.UserId.html#method.fmt-1
pub fn user<U: Into<UserId>>(mut self, user: U) -> Self {
self.0.push_str(&format!("{}", user.into()));
self
}
}
impl fmt::Display for MessageBuilder {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
fmt::Display::fmt(&self.0, f)
}
}
impl Default for MessageBuilder {
fn default() -> MessageBuilder {
MessageBuilder(String::default())
}
}
|