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
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

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

use std::time::Duration;

use serenity::collector::ReactionAction;
use serenity::futures::StreamExt;
use serenity::model::prelude::{Message, ReactionType, User};
use serenity::prelude::Context;

use crate::error::Error;
use crate::misc::add_reactions;

/// Creates a reaction prompt to get user's reaction.
///
/// Reactions are collected on the specified message. Only messages sent by `user`
/// are considered. Reactions are only considered for `timeout` seconds.
///
/// ## Example
///
/// ```
/// # use serenity::{
/// #    model::prelude::{ChannelId, Message, ReactionType},
/// #    prelude::Context,
/// # };
/// # use serenity_utils::{prompt::reaction_prompt, Error};
/// #
/// async fn prompt(ctx: &Context, msg: &Message) -> Result<(), Error> {
///     // Emojis for the prompt.
///     let emojis = [ReactionType::from('🐶'), ReactionType::from('🐱')];
///
///     let prompt_msg = ChannelId(7).say(&ctx.http, "Dogs or cats?").await?;
///
///     // Creates the prompt and returns the result. Because of `reaction_prompt`'s
///     // return type, you can use the `?` operator to get the result.
///     // The `Ok()` value is the selected emoji's index (wrt the `emojis` slice)
///     // and the emoji itself. We don't require the emoji here, so we ignore it.
///     let (idx, _) = reaction_prompt(ctx, &prompt_msg, &msg.author, &emojis, 30.0).await?;
///
///     if idx == 0 {
///         // Dogs!
///     } else {
///         // Cats!
///     }
///
///     Ok(())
/// }
/// ```
///
/// ## Errors
///
/// Returns [`Error::SerenityError`] if cache is enabled and the current
/// user does not have the required permissions to add reactions.
///
/// Returns [`Error::TimeoutError`] if user does not react at all.
pub async fn reaction_prompt(
    ctx: &Context,
    msg: &Message,
    user: &User,
    emojis: &[ReactionType],
    timeout: f32,
) -> Result<(usize, ReactionType), Error> {
    add_reactions(ctx, msg, emojis.to_vec()).await?;

    let mut collector = user
        .await_reactions(&ctx)
        .message_id(msg.id)
        .timeout(Duration::from_secs_f32(timeout))
        .build();

    while let Some(action) = collector.next().await {
        if let ReactionAction::Added(reaction) = action.as_ref() {
            if emojis.contains(&reaction.emoji) {
                return Ok((
                    emojis.iter().position(|p| p == &reaction.emoji).unwrap(),
                    reaction.emoji.clone(),
                ));
            }
        }
    }

    Err(Error::TimeoutError)
}

/// A special reaction prompt to check if user reacts with yes or no.
///
/// ✅ is used for yes and ❌ is used for no.
///
/// This function behaves in same way as [`reaction_prompt`] except for the
/// return type. If the user reacts with the yes emoji, the Ok value is `true`.
/// It user reacts with no emoji, the value is `false`.
///
/// ## Example
///
/// ```
/// # use serenity::{
/// #    model::prelude::{ChannelId, Message, ReactionType},
/// #    prelude::Context,
/// # };
/// # use serenity_utils::{prompt::yes_or_no_prompt, Error};
/// #
/// async fn prompt(ctx: &Context, msg: &Message) -> Result<(), Error> {
///     let prompt_msg = ChannelId(7).say(&ctx.http, "Are you a bot?").await?;
///
///     // Creates a yes/no prompt and returns the result.
///     let result = yes_or_no_prompt(ctx, &prompt_msg, &msg.author, 30.0).await?;
///
///     if result {
///         // Is a bot!
///     } else {
///         // Not a bot!
///     }
///
///     Ok(())
/// }
/// ```
///
/// ## Errors
///
/// It can return the same errors as [`reaction_prompt`].
pub async fn yes_or_no_prompt(
    ctx: &Context,
    msg: &Message,
    user: &User,
    timeout: f32,
) -> Result<bool, Error> {
    let emojis = [ReactionType::from('✅'), ReactionType::from('❌')];

    reaction_prompt(ctx, msg, user, &emojis, timeout).await.map(|(i, _)| i == 0)
}