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.

Methods

impl StandardFramework

pub fn new() -> Self

pub 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 token = env::var("DISCORD_TOKEN").unwrap();
let mut client = Client::new(&token, Handler).unwrap();
client.with_framework(StandardFramework::new()
    .configure(|c| c
        .depth(3)
        .allow_whitespace(true)
        .prefix("~")));

pub fn bucket(self, s: &str, delay: i64, time_span: i64, limit: i32) -> Self

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(|_, msg, _| {
            msg.channel_id.say("pong!")?;

            Ok(())
        })));

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

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| {
        // Our bucket is very strict. It cannot apply in DMs.
        // And can only apply if it's in the specific guild, channel and by the specific user.
        guild_id.is_some() && guild_id.unwrap() == 123 && channel_id == 456
        && user_id == 789
    })
    .command("ping", |c| c
        .bucket("basic")
        .exec(|_, msg, _| {
            msg.channel_id.say("pong!")?;

            Ok(())
        })
    )
);

pub fn simple_bucket(self, s: &str, delay: i64) -> Self

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(|_, msg, _| { msg.channel_id.say("pong!")?; Ok(()) })));

pub fn on(     self,     name: &str,     f: fn(_: &mut Context, _: &Message, _: Args) -> Result<(), CommandError> ) -> Self

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", |_, msg, _| {
    msg.channel_id.say("pong!")?;

    Ok(())
}));

pub fn cmd<C: Command + 'static>(self, name: &str, c: C) -> Self

Same as on, but accepts a Command directly.

pub fn command<F>(self, command_name: &str, f: F) -> Self where     F: FnOnce(CreateCommand) -> CreateCommand,

Adds a command using command builder.

Examples

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

pub fn group<F>(self, group_name: &str, f: F) -> Self where     F: FnOnce(CreateGroup) -> CreateGroup,

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
        .on("ping", |_, msg, _| { msg.channel_id.say("pong!")?; Ok(()) })
        .on("pong", |_, msg, _| { msg.channel_id.say("ping!")?; Ok(()) })));

pub 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."),
        }
    }));

pub 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.to_channel() {
            //  Don't run unless in nsfw channel
            if !channel.is_nsfw() {
                return false;
            }
        }

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

        true
    }));

pub 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);
        }
    }));

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

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

Examples

Using unrecognised_command:

use serenity::framework::StandardFramework;

client.with_framework(StandardFramework::new()
    .unrecognised_command(|ctx, msg, unrecognised_command_name| { }));

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

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

Examples

Using message_without_command:

use serenity::framework::StandardFramework;

client.with_framework(StandardFramework::new()
    .message_without_command(|ctx, msg| { }));

pub fn help(self, f: HelpFunction) -> Self

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

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

pub fn customised_help<F>(self, f: HelpFunction, c: F) -> Self where     F: FnOnce(CreateHelpCommand) -> CreateHelpCommand,

Sets what code should be executed when sends (prefix)help. Additionally takes a closure with a CreateHelpCommand in order to alter help-commands.

Trait Implementations

impl Framework for StandardFramework

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

fn update_current_user(&mut self, user_id: UserId)

impl Default for StandardFramework

fn default() -> StandardFramework

Returns the "default value" for a type.