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(&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;
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
        .with_whitespace(true)
        .prefix("~")));

pub 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"]
fn nothing() -> CommandResult {
    Ok(())
}

client.with_framework(StandardFramework::new()
    .bucket("basic", |b| b.delay(2).time_span(10).limit(3)));

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]
fn ping(ctx: &mut Context, msg: &Message) -> CommandResult {
    msg.channel_id.say(&ctx.http, "pong!")?;

    Ok(())
}

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

    Ok(())
}

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

client.with_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<F>(self, f: F) -> Self where
    F: Fn(&mut 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(|context, msg, error| {
        match error {
            NotEnoughArguments { min, given } => {
                let s = format!("Need {} arguments, but only got {}.", min, given);

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

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

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

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

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(|ctx, msg, cmd_name| {
        if let Ok(channel) = msg.channel_id.to_channel(ctx) {
            //  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| {
       println!("A user named {:?} tried to executute an unknown command: {}", msg.author.name, unrecognised_command_name);
    }));

pub fn normal_message<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 normal_message:

use serenity::framework::StandardFramework;

client.with_framework(StandardFramework::new()
    .normal_message(|ctx, msg| {
        println!("Received a generic message: {:?}", msg.content);
    }));

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

fn default() -> StandardFramework

Returns the "default value" for a type.

impl Framework for StandardFramework

fn dispatch(&mut self, ctx: Context, msg: Message, threadpool: &ThreadPool)