#[derive(Parse)]
enum Choices {
    First,
    Second,
    Third,
    #[parse(rename = "Forth")]
    Other
}

#[command]
#[description = "Some description"]
async fn choices(
    ctx: &SlashContext<()>,
    #[description = "Some description"] choice: Choices
) -> DefaultCommandResult
{
    // Command body
    Ok(())
}

自动完成命令

使用Zephyrus可以轻松实现自动完成用户输入，只需使用框架提供的autocomplete宏。

这里，看看这个例子。我们将使用一个这样的空命令作为基础：

#[command]
#[description = "Some description"]
async fn some_command(
    ctx: &SlashCommand</* Some type */>,
    #[autocomplete = "autocomplete_arg"] #[description = "Some description"] arg: String
) -> DefaultCommandResult
{
    // Logic goes here
    Ok(())
}

如您所注意到的，我们在参数 arg 上添加了一个 autocomplete 属性。该输入必须指向一个带有类似这样的 #[autocomplete] 属性的函数

#[autocomplete]
async fn autocomplete_arg(ctx: AutocompleteContext</* Some type */>) -> Option<InteractionResponseData> {
    // Function body
}

自动完成函数必须有一个 AutocompleteContext<T> 作为唯一参数，它允许您访问框架存储的数据，同时允许您访问原始交互、框架的 HTTP 客户端以及用户输入（如果存在）。

权限

要指定运行命令所需权限，只需在声明命令时使用 #[required_permissions] 属性，或者在声明命令组时使用 .required_permissions 方法。

该属性接受一个逗号分隔的列表作为输入 twilight 的权限。让我们看看创建一个需要 MANAGE_CHANNELS 和 MANAGE_MESSAGES 权限的命令会是什么样子。

#[command]
#[description = "Super cool command"]
#[required_permissions(MANAGE_CHANNELS, MANAGE_MESSAGES)]
async fn super_cool_command(ctx: &SlashContext</* Your type */>) -> DefaultCommandResult {
    // Body
    Ok(())
}

命令组

Zephyrus 默认支持 SubCommands 和 SubCommandGroups。

为了举例，假设我们创建了以下命令

#[command]
#[description = "Something"]
async fn something(ctx: &SlashContext</* Your type */>) -> DefaultCommandResult {
    // Command block
    Ok(())
}

有了这个，我们现在可以创建子命令和子命令组

创建子命令

要创建一个子命令，您需要创建一个组，然后可以添加所有子命令。

#[tokio::main]
async fn main() {
    let framework = Framework::builder()
        .group(|g| {
            g.name("<GROUP_NAME>")
                .description("<GROUP_DESCRIPTION>")
                .add_command(something)
                .add_command(..)
                ..
        })
        .build();
}

创建子命令组

子命令组与子命令非常相似，它们的创建方式几乎相同，但与直接使用 .add_command 不同，我们必须在注册组之前使用 .group。

#[tokio::main]
async fn main() {
    let framework = Framework::builder()
        .group(|g| {
            g.name("<GROUP_NAME>")
                .description("<GROUP_DESCRIPTION>")
                .group(|sub| { // With this we have created a subcommand group.
                    sub.name("<SUBGROUP_NAME>")
                        .description("<SUBGROUP_DESCRIPTION>")
                        .add_command(something)
                        .add_command(..)
                        ..
                })
        })
        .build();
}

钩子

有三种钩子可用，分别是 before、after 和 error_handler。

Before

在钩子触发之前，命令必须返回一个 bool，表示是否应该执行该命令。

#[before]
async fn before_hook(ctx: &SlashContext</*Your type*/>, command_name: &str) -> bool {
    // Do something
    
    true // <- if we return true, the command will be executed normally.
}

After

在命令执行后触发 after 钩子，并提供命令的结果。

#[after]
async fn after_hook(ctx: &SlashContext</* Your type */>, command_name: &str, result: Option<DefaultCommandResult>) {
    // Do something with the result.
}

特定错误处理

命令可以具有特定的错误处理器。当错误处理器被设置为命令时，如果命令（或其任何检查）失败，错误处理器将被调用，并且 after 钩子将接收 None 作为第三个参数。然而，如果命令执行完成而没有引发错误，after 钩子将接收命令的结果。

让我们看看一个简单的实现

#[error_handler]
async fn handle_ban_error(_ctx: &SlashContext</* Some type */>, error: DefaultError) {
    println!("The ban command had an error");
    
    // Handle the error
}


#[command]
#[description = "Tries to ban the bot itself, raising an error"]
#[error_handler(handle_ban_error)]
async fn ban_itself(ctx: &SlashContext</* Some type */>) -> DefaultCommandResult {
    // A bot cannot ban itself, so this will result in an error.
    ctx.http_client().ban(ctx.interaction.guild_id.unwrap(), Id::new(ctx.application_id.get()))
        .await?;
    
    Ok(())
}

由于命令总是会失败，因为机器人不能禁止自己，所以每次命令执行时都会调用错误处理器，如果设置了，则将 None 传递给 after 钩子。

检查

检查与 Before 钩子非常相似，但与它不同，它们不是全局的。相反，它们需要分配给每个命令。

让我们看看如何使用它

让我们创建一些检查，如下所示

#[check]
async fn only_guilds(ctx: &SlashContext</* Some type */>) -> Result<bool, DefaultError> {
    // Only execute the command if we are inside a guild.
    Ok(ctx.interaction.guild_id.is_some())
}

#[check]
async fn other_check(_ctx: &SlashContext</* Some type */>) -> Result<bool, DefaultError> {
    // Some other check here.
    Ok(true)
}

然后我们可以使用 check 属性将它们分配给我们的命令，该属性接受一个逗号分隔的检查列表

#[command]
#[description = "Some description"]
#[checks(only_guilds, other_check)]
async fn my_command(ctx: &SlashContext</* Some type */>) -> DefaultCommandResult {
    // Do something
    Ok(())
}

使用自定义返回类型

框架允许用户指定命令/检查执行返回的类型。框架定义如下

pub struct Framework<D, T = (), E = DefaultError>

其中 D 是框架中保存的数据类型，而 T 和 E 是命令的返回类型，以 Result<T, E> 的形式，然而，指定自定义类型是可选的，并且框架为那些不想自定义错误的人提供了 DefaultCommandResult 和 DefaultError。

根据框架中指定的泛型，after、error_handler 和 check 钩子参数的类型相应变化，因此它们的签名可以解释如下

钩子后

async fn(&SlashContext</* Some type */>, &str, Option<Result<T, E>>)

错误处理钩子

async fn(&SlashContext</* Some type */>, E)

命令检查

async fn(&SlashContext</* Some type */>) -> Result<bool, E>

注意，这些并不是真正的签名，因为这些函数返回 Box 包裹的 future。

模态框

从版本 0.8.0 开始，框架提供了一个 derive 宏，使模态框尽可能简单。让我们看一个例子

use zephyrus::prelude::*;

#[derive(Modal, Debug)]
#[modal(title = "Test modal")]
struct MyModal {
    field: String,
    #[modal(paragraph, label = "Paragraph")]
    paragraph: String,
    #[modal(placeholder = "This is an optional field")]
    optional: Option<String>
}

#[command]
#[description = "My command description"]
async fn my_command(ctx: &SlashContext</* Some type */>) -> DefaultCommandResult {
    let modal_waiter = ctx.create_modal::<MyModal>().await?;
    let output = modal_waiter.await?;
    
    println!("{output:?}");
    
    Ok(())
}

在这里，`Modal` derive 宏派生了 modal 特性，这使我们能够创建它们，然后我们可以使用 #[modal(..)} 属性来修改它将如何显示给用户。要查看允许的属性完整列表，请查看 宏声明。

目前，只允许 String 和 Option<String> 字段。

批量命令覆盖

如果您想使用 Discord 的 批量覆盖全局应用命令 端点，也许与一个 命令锁文件 结合使用，您将想要使用 Framework#twilight_commands。

注意 这需要 bulk 功能。

fn create_framework(
    http_client: Arc<Client>,
    app_id: Id<ApplicationMarker>
) -> Framework<()> {
    Framework::builder(http_client, app_id, ())
        .command(hello)
        .build()
}

fn create_lockfile(framework: Framework<()>) -> Result<()> {
    let commands = framework.twilight_commands();
    let content = serde_json::to_string_pretty(&commands)?;

    let path = concat!(env!("CARGO_MANIFEST_DIR"), "/commands.lock.json").to_string();
	std::fs::write(path, content).unwrap();

    Ok(())
}