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::on_message handler - to have the framework check if a Event::MessageCreate should be processed by itself.

Methods

impl StandardFramework

fn new() -> Self

fn configure<F>(self, f: F) -> Self where
    F: FnOnce(Configuration) -> 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, setting the depth to 3, allowing whitespace, and setting the prefix to "~":

use serenity::Client;
use serenity::framework::StandardFramework;
use std::env;

let mut client = Client::new(&env::var("DISCORD_TOKEN").unwrap(), Handler);
client.with_framework(StandardFramework::new()
    .configure(|c| c
        .depth(3)
        .allow_whitespace(true)
        .prefix("~")));

fn bucket<S>(self, s: S, delay: i64, time_span: i64, limit: i32) -> Self where
    S: Into<String>, 

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::StandardFramework;

client.with_framework(StandardFramework::new()
    .bucket("basic", 2, 10, 3)
    .command("ping", |c| c
        .bucket("basic")
        .exec_str("pong!")));

fn complex_bucket<S, Check>(
    self,
    s: S,
    delay: i64,
    time_span: i64,
    limit: i32,
    check: Check
) -> Self where
    Check: Fn(&mut Context, Option<GuildId>, ChannelId, UserId) -> bool + Send + Sync + 'static,
    S: Into<String>, 

Same as bucket but with a check added.

Examples

use serenity::framework::StandardFramework;

client.with_framework(StandardFramework::new()
    .complex_bucket("basic", 2, 10, 3, |_, guild_id, channel_id, user_id| {
// check if the guild is `123` and the channel where the command(s) was called:
// `456`
        // and if the user who called the command(s) is `789`
        // otherwise don't apply the bucket at all.
guild_id.is_some() && guild_id.unwrap() == 123 && channel_id == 456
&& user_id == 789
    })
    .command("ping", |c| c
        .bucket("basic")
        .exec_str("pong!")));

fn simple_bucket<S>(self, s: S, delay: i64) -> Self where
    S: Into<String>, 

Defines a bucket with only a delay between each command.

Examples

Create and use a simple bucket that has a 2 second delay between invocations:

use serenity::framework::StandardFramework;

client.with_framework(StandardFramework::new()
    .simple_bucket("simple", 2)
    .command("ping", |c| c
        .bucket("simple")
        .exec_str("pong!")));

fn on<F, S>(self, command_name: S, f: F) -> Self where
    F: Fn(&mut Context, &Message, Args) -> Result<(), CommandError> + Send + Sync + 'static,
    S: Into<String>, 

Adds a function to be associated with a command, which will be called when a command is used in a message.

This requires that a check - if one exists - passes, prior to being called.

Prior to v0.2.0, you will need to use the command builder via the command method to set checks. This command will otherwise only be for simple commands.

Refer to the module-level documentation for more information and usage.

Examples

Create and use a simple command:

use serenity::framework::StandardFramework;

client.with_framework(StandardFramework::new().on("ping", ping));

command!(ping(_ctx, msg) {
    let _ = msg.channel_id.say("pong!");
});

fn command<F, S>(self, command_name: S, f: F) -> Self where
    F: FnOnce(CreateCommand) -> CreateCommand,
    S: Into<String>, 

Adds a command using command builder.

Examples

framework.command("ping", |c| c
    .description("Responds with 'pong'.")
    .exec(|ctx, _, _| {
        let _ = ctx.say("pong");
    }));

fn group<F, S>(self, group_name: S, f: F) -> Self where
    F: FnOnce(CreateGroup) -> CreateGroup,
    S: Into<String>, 

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

Examples

Creating a simple group:

use serenity::framework::StandardFramework;

client.with_framework(StandardFramework::new()
    .group("ping-pong", |g| g
        .command("ping", |c| c.exec_str("pong!"))
        .command("pong", |c| c.exec_str("ping!"))));

fn on_dispatch_error<F>(self, f: F) -> Self where
    F: Fn(Context, Message, DispatchError) + Send + Sync + 'static, 

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::DispatchError::{NotEnoughArguments,
TooManyArguments};
use serenity::framework::StandardFramework;

client.with_framework(StandardFramework::new()
    .on_dispatch_error(|_, msg, error| {
        match error {
            NotEnoughArguments { min, given } => {
                let s = format!("Need {} arguments, but only got {}.", min, given);

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

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

fn before<F>(self, f: F) -> Self where
    F: Fn(&mut Context, &Message, &str) -> bool + Send + Sync + 'static, 

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::StandardFramework;

client.with_framework(StandardFramework::new()
    .before(|ctx, msg, cmd_name| {
        println!("Running command {}", cmd_name);
        true
    }));

Using before to prevent command usage:

use serenity::framework::StandardFramework;

client.with_framework(StandardFramework::new()
    .before(|_, msg, cmd_name| {
        if let Ok(channel) = msg.channel_id.get() {
            //  Don't run unless in nsfw channel
            if !channel.is_nsfw() {
                return false;
            }
        }

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

        true
    }));

fn after<F>(self, f: F) -> Self where
    F: Fn(&mut Context, &Message, &str, Result<(), CommandError>) + Send + Sync + 'static, 

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::StandardFramework;

client.with_framework(StandardFramework::new()
    .after(|ctx, msg, cmd_name, error| {
        //  Print out an error if it happened
        if let Err(why) = error {
            println!("Error in {}: {:?}", cmd_name, why);
        }
    }));

Trait Implementations

impl Default for StandardFramework

fn default() -> StandardFramework

Returns the "default value" for a type.

impl Framework for StandardFramework

fn dispatch(&mut self, context: Context, message: Message)

fn update_current_user(&mut self, user_id: UserId, is_bot: bool)