Struct serenity::framework::standard::StandardFramework

pub struct StandardFramework {
    pub initialized: bool,
    // some fields omitted
}

A utility for easily managing dispatches to commands.

Refer to the module-level documentation for more information.

Fields

initialized: bool

Whether the framework has been "initialized".

The framework is initialized once one of the following occurs:

• configuration has been set;
• a command handler has been set;
• a command check has been set.

This is used internally to determine whether or not - in addition to dispatching to the EventHandler::message handler - to have the framework check if a Event::MessageCreate should be processed by itself.

Implementations

impl StandardFramework

pub fn new() -> Self

pub fn configure<F>(self, f: F) -> Self where
    F: FnOnce(&mut Configuration) -> &mut Configuration, 

Configures the framework, setting non-default values. All fields are optional. Refer to Configuration::default for more information on the default values.

Examples

Configuring the framework for a Client, allowing whitespace between prefixes, and setting the prefix to "~":

use serenity::Client;
use serenity::framework::StandardFramework;

let token = std::env::var("DISCORD_TOKEN")?;
let framework = StandardFramework::new()
    .configure(|c| c
        .with_whitespace(true)
        .prefix("~"));

let mut client = Client::builder(&token).event_handler(Handler).framework(framework).await?;

pub async fn bucket<F, '_>(self, name: &'_ str, f: F) -> Self where
    F: FnOnce(&mut BucketBuilder) -> &mut BucketBuilder, 

Defines a bucket with delay between each command, and the limit of uses per time_span.

Examples

Create and use a bucket that limits a command to 3 uses per 10 seconds with a 2 second delay inbetween invocations:

use serenity::framework::standard::macros::command;
use serenity::framework::standard::{StandardFramework, CommandResult};

#[command]
// Registers the bucket `basic` to this command.
#[bucket = "basic"]
async fn nothing() -> CommandResult {
    Ok(())
}

let framework = StandardFramework::new()
    .bucket("basic", |b| b.delay(2).time_span(10).limit(3))
    .await;

pub fn group(self, group: &'static CommandGroup) -> Self

Adds a group which can organize several related commands. Groups are taken into account when using serenity::framework::standard::help_commands.

Examples

Add a group with ping and pong commands:

use serenity::client::{Client, Context};
use serenity::model::channel::Message;
use serenity::framework::standard::{
    StandardFramework,
    CommandResult,
    macros::{command, group},
};

// For information regarding this macro, learn more about it in its documentation in `command_attr`.
#[command]
async fn ping(ctx: &Context, msg: &Message) -> CommandResult {
    msg.channel_id.say(&ctx.http, "pong!").await?;

    Ok(())
}

#[command]
async fn pong(ctx: &Context, msg: &Message) -> CommandResult {
    msg.channel_id.say(&ctx.http, "ping!").await?;

    Ok(())
}

#[group("bingbong")]
#[commands(ping, pong)]
struct BingBong;

let framework = StandardFramework::new()
    // Groups' names are changed to all uppercase, plus appended with `_GROUP`.
    .group(&BINGBONG_GROUP);

pub fn group_add(&mut self, group: &'static CommandGroup)

Adds a group to be used by the framework. Primary use-case is runtime modification of groups in the framework; will not mark the framework as initialized. Refer to group for adding groups in initial configuration.

Note: does not return Self like many other commands. This is because it's not intended to be chained as the other commands are.

pub fn group_remove(&mut self, group: &'static CommandGroup)

Removes a group from being used in the framework. Primary use-case is runtime modification of groups in the framework.

Note: does not return Self like many other commands. This is because it's not intended to be chained as the other commands are.

pub fn on_dispatch_error(
    self,
    f: fn'fut(_: &'fut Context, _: &'fut Message, _: DispatchError) -> BoxFuture<'fut, ()>
) -> Self

Specify the function that's called in case a command wasn't executed for one reason or another.

DispatchError represents all possible fail conditions.

Examples

Making a simple argument error responder:

use serenity::framework::standard::macros::hook;
use serenity::framework::standard::DispatchError;
use serenity::framework::StandardFramework;

#[hook]
async fn dispatch_error_hook(context: &Context, msg: &Message, error: DispatchError) {
    match error {
        DispatchError::NotEnoughArguments { min, given } => {
            let s = format!("Need {} arguments, but only got {}.", min, given);

            let _ = msg.channel_id.say(&context, &s).await;
        },
        DispatchError::TooManyArguments { max, given } => {
            let s = format!("Max arguments allowed is {}, but got {}.", max, given);

            let _ = msg.channel_id.say(&context, &s).await;
        },
        _ => println!("Unhandled dispatch error."),
    }
}

let framework = StandardFramework::new()
    .on_dispatch_error(dispatch_error_hook);

pub fn prefix_only(
    self,
    f: fn'fut(_: &'fut Context, _: &'fut Message) -> BoxFuture<'fut, ()>
) -> Self

Specify the function to be called on messages comprised of only the prefix.

pub fn before(
    self,
    f: fn'fut(_: &'fut Context, _: &'fut Message, _: &'fut str) -> BoxFuture<'fut, bool>
) -> Self

Specify the function to be called prior to every command's execution. If that function returns true, the command will be executed.

Examples

Using before to log command usage:

use serenity::framework::standard::macros::hook;
use serenity::framework::StandardFramework;

#[hook]
async fn before_hook(_: &Context, _: &Message, cmd_name: &str) -> bool {
    println!("Running command {}", cmd_name);
    true
}
let framework = StandardFramework::new()
    .before(before_hook);

Using before to prevent command usage:

use serenity::framework::standard::macros::hook;
use serenity::framework::StandardFramework;

#[hook]
async fn before_hook(ctx: &Context, msg: &Message, cmd_name: &str) -> bool {
    if let Ok(channel) = msg.channel_id.to_channel(ctx).await {
        //  Don't run unless in nsfw channel
        if !channel.is_nsfw() {
            return false;
        }
    }

    println!("Running command {}", cmd_name);

    true
}

let framework = StandardFramework::new()
    .before(before_hook);

pub fn after(
    self,
    f: fn'fut(_: &'fut Context, _: &'fut Message, _: &'fut str, _: Result<(), CommandError>) -> BoxFuture<'fut, ()>
) -> Self

Specify the function to be called after every command's execution. Fourth argument exists if command returned an error which you can handle.

Examples

Using after to log command usage:

use serenity::framework::standard::macros::hook;
use serenity::framework::standard::CommandError;
use serenity::framework::StandardFramework;

#[hook]
async fn after_hook(_: &Context, _: &Message, cmd_name: &str, error: Result<(), CommandError>) {
    //  Print out an error if it happened
    if let Err(why) = error {
        println!("Error in {}: {:?}", cmd_name, why);
    }
}

let framework = StandardFramework::new()
    .after(after_hook);

pub fn unrecognised_command(
    self,
    f: fn'fut(_: &'fut Context, _: &'fut Message, _: &'fut str) -> BoxFuture<'fut, ()>
) -> Self

Specify the function to be called if no command could be dispatched.

Examples

Using unrecognised_command:

use serenity::framework::standard::macros::hook;
use serenity::framework::StandardFramework;

#[hook]
async fn unrecognised_command_hook(_: &Context, msg: &Message, unrecognised_command_name: &str) {
    println!("A user named {:?} tried to executute an unknown command: {}",
        msg.author.name, unrecognised_command_name
    );
}

let framework = StandardFramework::new()
    .unrecognised_command(unrecognised_command_hook);

pub fn normal_message(
    self,
    f: fn'fut(_: &'fut Context, _: &'fut Message) -> BoxFuture<'fut, ()>
) -> Self

Specify the function to be called if a message contains no command.

Examples

Using normal_message:

use serenity::framework::standard::macros::hook;
use serenity::framework::StandardFramework;

#[hook]
async fn normal_message_hook(_: &Context, msg: &Message) {
    println!("Received a generic message: {:?}", msg.content);
}

let framework = StandardFramework::new()
    .normal_message(normal_message_hook);

pub fn help(self, h: &'static HelpCommand) -> Self

Sets what code should be executed when a user sends (prefix)help.

If a command named help in a group was set, then this takes precedence first.

Trait Implementations

impl Default for StandardFramework

pub fn default() -> StandardFramework

Returns the "default value" for a type.

impl Framework for StandardFramework

pub fn dispatch<'life0, 'async_trait>(
    &'life0 self,
    ctx: Context,
    msg: Message
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: 'async_trait,