discorb 0.15.1 → 0.17.1

data/docs/application_command.md

@@ -13,12 +13,13 @@ From: [Discord API docs](https://discord.com/developers/docs/interactions/applic
 ## 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`}. 
+{file:docs/cli/setup.md Learn more about `discorb setup`}.
 
 ### Note
 
@@ -43,41 +44,47 @@ 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. |
+| 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" => {
+  "name" => {
     type: :string,
     required: true,
     description: "The description of the command."
   }
 }
 ```
-| Key | Type | Description |
-| --- | --- | --- |
-| `:description` | `String` | Description of the option. |
-| `:required` | Whether the argument is required. `optional` will be used if not specified. |
-| `:optional` | Whether the argument is optional. `required` will be used if not specified. |
-| `:type` | `Object` | Type of the option. |
-| `:choice` | `Hash{String => String, Integer, Float}` | Choice of the option. |
-| `: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`) |
+
+| 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`)               |
 
 `choices` should be unspecified if you don't want to use it.
-`choices` is hash like this:
+`choices` example:
 
 ```ruby
 {
@@ -103,15 +110,28 @@ The key will be displayed in the user menu, and the value will be used as the ar
 
 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 |
+| 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
 
@@ -277,21 +297,21 @@ 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. |
+| 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 |
-| --- | --- |
+| Parameter     | Description             |
+| ------------- | ----------------------- |
 | `interaction` | The interaction object. |
-| `user` | The user object. |
-
+| `user`        | The user object.        |
 
 ### Register Message Context Menu Command
 
@@ -303,15 +323,104 @@ 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. |
+| 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 |
-| --- | --- |
+| Parameter     | Description             |
+| ------------- | ----------------------- |
 | `interaction` | The interaction object. |
-| `message` | The message 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",
+      },
+    }
+  }
+}
+```

data/docs/cli/irb.md

@@ -6,7 +6,6 @@
 
 This command will start an interactive Ruby shell with connected client.
 
-
 ## Usage
 
 ```
@@ -16,6 +15,7 @@ discorb irb [options]
 ### Load a token
 
 discorb irb will load a token from...
+
 1. the `DISCORD_BOT_TOKEN` environment variable
 2. the `DISCORD_TOKEN` environment variable
 3. `token` file in the current directory(customizable with `-t` option)
@@ -36,4 +36,4 @@ Token file to load.
 
 #### `message`
 
-Last message received.
+Last message received.

data/docs/cli/new.md

@@ -56,16 +56,21 @@ Default to TOKEN.
 Whether to overwrite an existing directory.
 Default to false.
 
+### `--[no-]comment`
+
+Whether to write comment in main.rb.
+Default to true.
+
 ## File structure
 
 The following files will be created:
 
-| File | Description |
-| ---- | ----------- |
-| `.env` | Environment variables. |
-| `main.rb` | Main script. |
-| `.gitignore` | Git ignore file. Won't be created if `--git` is false. |
-| `Gemfile` | Gemfile. Won't be created if `--bundle` is false. |
-| `Gemfile.lock` | Gemfile lock file. Won't be created if `--bundle` is false. |
-| `README.md` | Readme file. Won't be created if `--desc` is false. |
-| `.env.sample` | Sample environment variables. Won't be created if `--desc` is false. |
+| File           | Description                                                          |
+| -------------- | -------------------------------------------------------------------- |
+| `.env`         | Environment variables.                                               |
+| `main.rb`      | Main script.                                                         |
+| `.gitignore`   | Git ignore file. Won't be created if `--git` is false.               |
+| `Gemfile`      | Gemfile. Won't be created if `--bundle` is false.                    |
+| `Gemfile.lock` | Gemfile lock file. Won't be created if `--bundle` is false.          |
+| `README.md`    | Readme file. Won't be created if `--desc` is false.                  |
+| `.env.sample`  | Sample environment variables. Won't be created if `--desc` is false. |

data/docs/cli/run.md

@@ -6,7 +6,6 @@
 
 This command will run a client.
 
-
 ## Usage
 
 ```
@@ -31,12 +30,12 @@ The title of the process.
 Specify the log level.
 Should be one of the following:
 
-* `none`
-* `debug`
-* `info`
-* `warn`
-* `error`
-* `fatal`
+- `none`
+- `debug`
+- `info`
+- `warn`
+- `error`
+- `fatal`
 
 #### `-f`, `--log-file`
 
@@ -47,6 +46,7 @@ You can use `stdout` to write to the standard output, and `stderr` to write to t
 
 Whether to colorize the log output.
 If not specified, the default will be:
+
 - `true` if the file to write logs to is `stdout` or `stderr`.
 - `false` otherwise.
 
@@ -57,7 +57,3 @@ Whether to set up application commands.
 #### `-e`, `--env`
 
 The name of the environment variable to use for token, or just `-t` or `--token` for intractive prompt.
-
-#### `-b`, `--bundler`
-
-Whether to use bundler to load the script.

data/docs/cli.md

@@ -9,20 +9,27 @@ discorb has a CLI tool for developing.
 ## Usage
 
 ```bash
-bundle exec discorb <command> ...
+Usage: discorb [options] [subcommand [options]]
 ```
 
+## Options
+
+### `-b`, `--[no-]bundler`
+
+Whether to use bundler.
+Default to true.
+
 ## Commands
 
 Currently, discorb has the following commands:
 
-| Command | Description |
-|---------|-------------|
-| {file:docs/cli/new.md `new`} | Create a new project. |
-| {file:docs/cli/irb.md `irb`} | Start an interactive Ruby shell with connected client. |
-| {file:docs/cli/run.md `run`} | Run a client. |
-| {file:docs/cli/setup.md `setup`} | Setup application commands. |
-| `show` | Show your environment. (No document) |
-| `about` | Show discorb's information. (No document) |
+| Command                          | Description                                            |
+| -------------------------------- | ------------------------------------------------------ |
+| {file:docs/cli/new.md `new`}     | Create a new project.                                  |
+| {file:docs/cli/irb.md `irb`}     | Start an interactive Ruby shell with connected client. |
+| {file:docs/cli/run.md `run`}     | Run a client.                                          |
+| {file:docs/cli/setup.md `setup`} | Setup application commands.                            |
+| `show`                           | Show your environment. (No document)                   |
+| `about`                          | Show discorb's information. (No document)              |
 
-Click the command name to see the document.
+Click the command name to see the document.