<!--
# @title Application Commands
-->

# Application Commands

## What is an application command?

> Application commands are commands that an application can register to Discord. They provide users a first-class way of interacting directly with your application that feels deeply integrated into Discord.

From: [Discord API docs](https://discord.com/developers/docs/interactions/application-commands#application-commands)

## How do I register an application command?

Write to your script:

- {Discorb::ApplicationCommand::Handler.slash}, {Discorb::ApplicationCommand::Handler.slash_group} for slash commands,
- {Discorb::ApplicationCommand::Handler.user_command} for user menu commands,
- {Discorb::ApplicationCommand::Handler.message_command} for message menu commands.

And then run `discorb setup` to register your application commands.
{file:docs/cli/setup.md Learn more about `discorb setup`}.

### Note

To register a global command, it will take 1 hour to be registered.
Guild commands will be registered immediately.

### Register Slash Commands

This example registers a slash command that says "Hello, world!" when the user types `/hello`.

```ruby
require "discorb"

client = Discorb::Client.new

client.slash("hello", "Greet for you") do |interaction|
  interaction.post("Hello World!", ephemeral: true)
end

client.run(ENV["DISCORD_BOT_TOKEN"])
```

{Discorb::ApplicationCommand::Handler#slash} takes 5 arguments:

| Argument       | Description                                              |
| -------------- | -------------------------------------------------------- |
| `command_name` | The name of the command.                                 |
| `description`  | The description of the command.                          |
| `options`      | A hash of options.                                       |
| `guild_ids`    | The ID of the guild to register the command in.          |
| `block`        | A block that will be called when the command is invoked. |

Block will be called with a {Discorb::Interaction} object and specified options.

#### Register options

You can set hash to `options` argument.
In `options`, hash should be like this:

```ruby
{
  "name" => {
    type: :string,
    required: true,
    description: "The description of the command."
  }
}
```

| Key                      | Type                                     | Description                                                                           |
| ------------------------ | ---------------------------------------- | ------------------------------------------------------------------------------------- |
| `:name_localizations`    | `Hash{Symbol => String}`                 | Localizations of option name.                                                         |
| `:description`           | `String`                                 | Description of the option.                                                            |
| `:required`              | `Boolean(true\|false)`                   | Whether the argument is required. `optional` will be used if not specified.           |
| `:optional`              | `Boolean(true\|false)`                   | Whether the argument is optional. `required` will be used if not specified.           |
| `:type`                  | `Object`                                 | Type of the option.                                                                   |
| `:choices`               | `Hash{String => String, Integer, Float}` | Choice of the option.                                                                 |
| `:choices_localizations` | `Hash{String => Hash{Symbol => String}}` | Localization of the choice. Key must be the name of a choice. (See below for example) |
| `:default`               | `Object`                                 | Default value of the option.                                                          |
| `:channel_types`         | `Array<Class<Discorb::Channel>>`         | Type of the channel option.                                                           |
| `:autocomplete`          | `Proc`                                   | Autocomplete function.                                                                |
| `:range`                 | `Range`                                  | Range of the option. Only valid for numeric options. (`:int`, `:float`)               |
| `:length`                | `Range`                                  | Range of length of the option. Only valid for `:string`.                              |

`choices` should be unspecified if you don't want to use it.
`choices` example:

```ruby
{
  "vocaloid" => {
    required: true,
    description: "The vocaloid which you like.",
    type: :string,
    choices: {
      "Hatsune Miku" => "miku",
      "Kagamine Rin" => "rin",
      "Kagamine Len" => "len",
      "Megurine Luka" => "luka",
      "MEIKO" => "meiko",
      "KAITO" => "kaito",
    }
  }
}

# Note: This aritcle is written in 8/31.
```

The key will be displayed in the user menu, and the value will be used as the argument.

In `type`, You must use one of the following:

| Name       | Description       | Aliases   |
| ---------- | ----------------- | --------- |
| `:string`  | String argument.  | `:str`    |
| `:integer` | Integer argument. | `:int`    |
| `:float`   | Float argument.   | None      |
| `:boolean` | Boolean argument. | `:bool`   |
| `:user`    | User argument.    | `:member` |
| `:channel` | Channel argument. | None      |
| `:role`    | Role argument.    | None      |

The block will receive the options as arguments.

```ruby
client.slash("hello", "Bot greets", {
  "name" => {
    type: :string,
    description: "Name"
  }
}) do |interaction, name|
  interaction.post("Hello, #{name}!", ephemeral: true)
end
```

#### Group Slash Commands

To register a group of slash commands, use {Discorb::ApplicationCommand::Handler#slash_group}.

```ruby
group = client.slash_group("settings", "Set settings of bot.")

group.slash("message_expand", "Whether bot should expand message.", {
  "enabled" => {
    type: :boolean,
    description: "Whether bot should expand message."
  }
}) do |interaction, enabled|
  # ...
end

group.slash("level", "Whether level system is enabled.", {
  "enabled" => {
    type: :boolean,
    description: "Whether level system is enabled."
  }
}) do |interaction, enabled|
  # ...
end

```

Since v0.5.1, You can use block for register commands.

```ruby

client.slash_group("settings", "Set settings of bot.") do |group|
  group.slash("message_expand", "Whether bot should expand message.", {
    "enabled" => {
      type: :boolean,
      description: "Whether bot should expand message."
    }
  }) do |interaction, enabled|
    # ...
  end
  group.slash("bump_alert", "Whether level system is enabled.", {
    "enabled" => {
      type: :boolean,
      description: "Whether level system is enabled."
    }
  }) do |interaction, enabled|
    # ...
  end
end
```

You can make subcommand group by using {Discorb::ApplicationCommand::Command::GroupCommand#group}.

```ruby
group = client.slash_group("permission", "Set/Get command permissions.")

group_user = group.group("user", "Set/Get user's command permissions.")

group_user.slash("set", "Set user's command permissions.", {
  "user_id" => {
      type: :user,
      description: "The user."
  },
  "value" => {
      type: :boolean,
      description: "Whether the user can use the command."
  }
}) do |interaction, user|
  # ...
end

group_user.slash("get", "Set user's command permissions.", {
    "user_id" => {
        type: :user,
        description: "The user."
    },
}) do |interaction, user|
  # ...
end

group_user = group.group("user", "Set/Get user's command permissions.")

group_user.slash("set", "Set user's command permissions.", {
    "user_id" => {
        type: :user,
        description: "The user."
    },
    "value" => {
        type: :boolean,
        description: "Whether the user can use the command."
    }
}) do |interaction, user|
  # ...
end

group_user.slash("get", "Set user's command permissions.", {
    "user_id" => {
        type: :user,
        description: "The user."
    },
}) do |interaction, user|
  # ...
end

group_role = group.group("role", "Set/Get role's command permissions.")

group_role.slash("set", "Set role's command permissions.", {
    "role_id" => {
        type: :role,
        description: "The role."
    },
    "value" => {
        type: :boolean,
        description: "Whether the role can use the command."
    }
}) do |interaction, role|
  # ...
end

group_role.slash("get", "Set role's command permissions.", {
    "role_id" => {
        type: :role,
        description: "The role."
    },
}) do |interaction, role|
  # ...
end

```

Same as above, you can use block for register commands since v0.5.1.

#### Use Auto Completing

Since v0.11.0, you can use auto-completion by setting Proc to `:autocomplete` in options.
The proc will be called with interaction object and the argument.
The proc should return a hash of the autocomplete result.

```ruby
client.slash("hello2", "Greet for you", {
  "target" => {
    type: :string,
    description: "Person to greet",
    autocomplete: ->(interaction, target) {
      {
        "You" => interaction.target.to_s
      }
    },
  },
}) do |interaction, target|
  interaction.post("Hello, #{target}!")
end
```

In the above example, `You` will be displayed in the user menu.
Due to the limitation of Discord API, the proc must return the result in less than 3 second.

### Register User Context Menu Command

```ruby
client.user_command("hello") do |interaction, user|
  interaction.post("Hello, #{user.name}!")
end
```

{Discorb::ApplicationCommand::Handler.user_command} takes 3 arguments:

| Parameter      | Description                                              |
| -------------- | -------------------------------------------------------- |
| `command_name` | The name of the command.                                 |
| `guild_ids`    | The ID of the guild to register the command in.          |
| `block`        | A block that will be called when the command is invoked. |

`block` will be called with two arguments:

| Parameter     | Description             |
| ------------- | ----------------------- |
| `interaction` | The interaction object. |
| `user`        | The user object.        |

### Register Message Context Menu Command

```ruby
client.message_command("Bookmark") do |interaction, message|
  # ...
end
```

{Discorb::ApplicationCommand::Handler.message_command} takes 3 arguments:

| Parameter      | Description                                              |
| -------------- | -------------------------------------------------------- |
| `command_name` | The name of the command.                                 |
| `guild_ids`    | The ID of the guild to register the command in.          |
| `block`        | A block that will be called when the command is invoked. |

`block` will be called with two arguments:

| Parameter     | Description             |
| ------------- | ----------------------- |
| `interaction` | The interaction object. |
| `message`     | The message object.     |

### Localizing command

You can localize commands with passing parameters, or setting Hash to name.
Also, you can change the text by checking `interaction.locale` and `interaction.guild_locale`.

Command name localize example:

```ruby
localizations = {
  localized: {
    text: {
      en: "Hello, %s!",
      ja: "%sさん、こんにちは！",
    },
  },
}

client.slash({
  default: "greet",
  ja: "挨拶",
}, {
  default: "Bot greets. Cute OwO",
  ja: "Botが挨拶します。かわいいね",
}, {
  "name" => {
    name_localizations: {
      ja: "名前",
    },
    description: {
      default: "The name to greet.",
      ja: "挨拶する人の名前。",
    },
    type: :string,
    optional: true,
  },
}) do |interaction, name|
  interaction.post(
    (localizations[:localized][:text][interaction.locale] || localizations[:localized][:text][:en]) % [name || interaction.target.to_s_user],
    ephemeral: true,
  )
end
```

Option localize example:

```ruby
{
  "vocaloid" => {
    name_localizations: {
      ja: "ボカロ",
    },
    required: true,
    description: "The vocaloid which you like.",
    description_localizations: {
      ja: "好きなボカロ。",
    },
    type: :string,
    choices: {
      "Hatsune Miku" => "miku",
      "Kagamine Rin" => "rin",
      "Kagamine Len" => "len",
      "Megurine Luka" => "luka",
      "MEIKO" => "meiko",
      "KAITO" => "kaito",
    },
    choice_localizations: {
      "Hatsune Miku" => {
        ja: "初音ミク",
      },
      "Kagamine Rin" => {
        ja: "鏡音リン",
      },
      "Kagamine Len" => {
        ja: "鏡音レン",
      },
      "Megurine Luka" => {
        ja: "巡音ルカ",
      },
      "MEIKO" => {
        ja: "MEIKO",
      },
      "KAITO" => {
        ja: "KAITO",
      },
    }
  }
}
```