serenity_utils 0.7.0

A library to provide additional utilies for Discord bots created with serenity.
Documentation 
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

//! Prompts to get a user's response via a message.
//!
//! ## Example
//!
//! ```
//! # use serenity::{
//! #    model::prelude::{ChannelId, Message},
//! #    prelude::Context,
//! # };
//! # use serenity_utils::{prompt::message_prompt_content, Error};
//! #
//! async fn prompt(ctx: &Context, msg: &Message) -> Result<(), Error> {
//!     // Assuming `channel_id` is bound.
//!     let prompt_msg = ChannelId(7).say(&ctx.http, "What is your favourite colour?").await?;
//!
//!     // User's optional response to the message.
//!     let optional_content = message_prompt_content(ctx, &prompt_msg, &msg.author, 30.0).await;
//!
//!     Ok(())
//! }
//! ```

use std::time::Duration;

use serenity::model::prelude::{Message, User};
use serenity::prelude::Context;

/// Creates a message prompt to get the next message a user sends.
///
/// Only messages sent in the channel of the original message are considered.
/// The bot waits for a message for `timeout` seconds only. `None` is returned
/// if the user does not send another message.
///
/// ## Example
///
/// ```
/// # use serenity::{
/// #    model::prelude::{ChannelId, Message},
/// #    prelude::Context,
/// # };
/// # use serenity_utils::{prompt::message_prompt, Error};
/// #
/// async fn prompt(ctx: &Context, msg: &Message) -> Result<(), Error> {
///     // Assuming `channel_id` is bound.
///     let prompt_msg = ChannelId(7).say(&ctx.http, "What is your favourite colour?").await?;
///
///     // Optional `Message` object of user's response to the message.
///     let optional_msg = message_prompt(ctx, &prompt_msg, &msg.author, 30.0).await;
///
///     Ok(())
/// }
/// ```
///
/// See [`message_prompt_content`] if you only need the message's content.
pub async fn message_prompt(
    ctx: &Context,
    msg: &Message,
    user: &User,
    timeout: f32,
) -> Option<Message> {
    user.await_reply(&ctx)
        .channel_id(msg.channel_id)
        .timeout(Duration::from_secs_f32(timeout))
        .await
        .map(|m| m.as_ref().clone())
}

/// Creates a message prompt to get the content of the next message a user sends.
///
/// Only messages sent in the channel of the original message are considered.
/// The bot waits for a message for `timeout` seconds only. `None` is returned
/// if the user does not send another message.
///
/// ## Example
///
/// ```
/// # use serenity::{
/// #    model::prelude::{ChannelId, Message},
/// #    prelude::Context,
/// # };
/// # use serenity_utils::{prompt::message_prompt_content, Error};
/// #
/// async fn prompt(ctx: &Context, msg: &Message) -> Result<(), Error> {
///     // Assuming `channel_id` is bound.
///     let prompt_msg = ChannelId(7).say(&ctx.http, "What is your favourite colour?").await?;
///
///     // User's optional response to the message.
///     let optional_content = message_prompt_content(ctx, &prompt_msg, &msg.author, 30.0).await;
///
///     Ok(())
/// }
/// ```
///
/// See [`message_prompt`] if you need the whole message object.
pub async fn message_prompt_content(
    ctx: &Context,
    msg: &Message,
    user: &User,
    timeout: f32,
) -> Option<String> {
    user.await_reply(&ctx)
        .channel_id(msg.channel_id)
        .timeout(Duration::from_secs_f32(timeout))
        .await
        .map(|m| m.content.clone())
}