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's ArgumentConvert 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(())
}

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 get Member from user name, tag or nickname when using the Conversion trait.
rustls_backend: Uses Rustls for all platforms, a pure Rust implementation.
native_tls_backend: Uses SChannel on Windows, Secure Transport on macOS, and OpenSSL on other platforms.

cache and rustls_backend are enabled by default.

default_native_tls: Enables default serenity_utils features with native_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.

serenity_utils 0.7.0