Struct serenity::framework::standard::StandardFramework

pub struct StandardFramework {
    pub initialized: bool,
    /* private fields */
}

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Available on crate features framework and standard_framework only.

A utility for easily managing dispatches to commands.

Refer to the module-level documentation for more information.

Fields

initialized: bool

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

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

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

pub fn configure(&self, config: Configuration)

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

Configures the framework, setting non-default values.

This passes a mutable reference to the current configuration, allowing for runtime configuration of the Framework.

Examples

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

use serenity::framework::standard::{Configuration, StandardFramework};
use serenity::Client;

let framework = StandardFramework::new();
framework.configure(Configuration::new().with_whitespace(true).prefix("~"));

let token = std::env::var("DISCORD_TOKEN")?;
let mut client = Client::builder(&token, GatewayIntents::default())
    .event_handler(Handler)
    .framework(framework)
    .await?;

pub async fn bucket( self, name: impl Into<String>, builder: BucketBuilder ) -> Self

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

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 in between invocations:

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

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

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

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

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

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)

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

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 Self::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)

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

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: for<'fut> fn(_: &'fut Context, _: &'fut Message, _: DispatchError, _: &'fut str) -> BoxFuture<'fut, ()> ) -> Self

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

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,
    command_name: &str,
) {
    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 in {}.", command_name),
    }
}

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

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

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

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

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

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

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

Examples

Using Self::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: for<'fut> fn(_: &'fut Context, _: &'fut Message, _: &'fut str, _: Result<(), CommandError>) -> BoxFuture<'fut, ()> ) -> Self

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

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 Self::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: for<'fut> fn(_: &'fut Context, _: &'fut Message, _: &'fut str) -> BoxFuture<'fut, ()> ) -> Self

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

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

Examples

Using Self::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 execute an unknown command: {}",
        msg.author.name, unrecognised_command_name
    );
}

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

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

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

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

Examples

Using Self::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

👎Deprecated: The standard framework is deprecated, and will be removed in 0.13. Please migrate to poise for command handling

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

fn default() -> StandardFramework

Returns the “default value” for a type.

impl Framework for StandardFramework

fn dispatch<'life0, 'async_trait>( &'life0 self, ctx: Context, event: FullEvent ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Called on every incoming event.

fn init<'life0, 'life1, 'async_trait>( &'life0 mut self, client: &'life1 Client ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Called directly after the Client is created.