9 releases (breaking)
0.7.0 | Jul 26, 2022 |
---|---|
0.6.1 | Feb 1, 2021 |
0.6.0 | Jan 10, 2021 |
0.5.1 | Nov 28, 2020 |
#1707 in Web programming
85KB
1K
SLoC
serenity-utils
A library to provide conversions, prompts and menu functionality for Discord bots created with serenity.
This library provides implementations to easily:
- Get user response using message or reaction prompts.
- Display paginated reaction-based messages/menus.
- Format text in different ways before sending.
Convert a string to serenity's guild-specific models.(deprecated; use serenity'sArgumentConvert
trait instead)Create embeds and messages with field access.(deprecated; use serenity's builder directly)
Installation and Usage
To use this crate, add the following to your Cargo.toml
:
[dependencies]
serenity_utils = "0.7.0"
Note: This crate only supports serenity's async versions and a minimum of Rust 1.53 (consistent with the latest serenity version).
Examples
Here are a few examples to use some of serenity_utils's features.
Reaction Prompt
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(())
}
Menu
use serenity::{
builder::CreateMessage,
model::prelude::Message,
prelude::Context,
};
use serenity_utils::{
menu::{Menu, MenuOptions},
Error,
};
async fn use_menu(ctx: &Context, msg: &Message) -> Result<(), Error> {
let mut page_one = CreateMessage::default();
page_one
.content("Page number one!")
.embed(|e| {
e.description("The first page!");
e
});
let mut page_two = CreateMessage::default();
page_two
.content("Page number two!")
.embed(|e| {
e.description("The second page!");
e
});
let pages = [page_one, page_two];
// Creates a new menu.
let menu = Menu::new(ctx, msg, &pages, MenuOptions::default());
// Runs the menu and returns optional `Message` used to display the menu.
let opt_message = menu.run().await?;
Ok(())
}
More Examples
More examples detailing the crate's functionality can be found in the examples
directory.
Features
Some functionality of this crate is dependent on serenity's features.
The following serenity features are required when using serenity_utils
:
- client
- collector
- gateway
- model
The following serenity_utils
features are optional:
- cache: Enables serenity's
cache
feature. It is required to getMember
from user name, tag or nickname when using theConversion
trait. - rustls_backend: Uses
Rustls
for all platforms, a pure Rust implementation. - native_tls_backend: Uses
SChannel
on Windows,Secure Transport
on macOS, andOpenSSL
on other platforms.
cache and rustls_backend are enabled by default.
- default_native_tls: Enables default
serenity_utils
features withnative_tls_backend
.
They enable serenity's features with the same names.
Note: One of rustls_backend
and native_tls_backend
must be used.
You can specify features by adding this to your Cargo.toml
:
[dependencies.serenity_utils]
version = "0.7.0"
# To disable default features.
default-features = false
# Choose features you need.
features = ["cache", "native_tls_backend"]
License
serenity_utils
is available under the ISC license. See LICENSE for more details.
Dependencies
~7–23MB
~360K SLoC