Trait teloxide::utils::command::BotCommands

pub trait BotCommands: Sized {
    fn parse(s: &str, bot_username: &str) -> Result<Self, ParseError>;
    fn descriptions() -> CommandDescriptions<'static>;
    fn bot_commands() -> Vec<BotCommand>;

    fn ty() -> PhantomData<Self> { ... }
}

An enumeration of bot’s commands.

Example

use teloxide::utils::command::BotCommands;

type UnitOfTime = u8;

#[derive(BotCommands, PartialEq, Debug)]
#[command(rename_rule = "lowercase", parse_with = "split")]
enum AdminCommand {
    Mute(UnitOfTime, char),
    Ban(UnitOfTime, char),
}

let command = AdminCommand::parse("/ban 5 h", "bot_name").unwrap();
assert_eq!(command, AdminCommand::Ban(5, 'h'));

Enum attributes

1. #[command(rename_rule = "rule")] Rename all commands by rule. Allowed rules are lowercase, UPPERCASE, PascalCase, camelCase, snake_case, SCREAMING_SNAKE_CASE, kebab-case, and SCREAMING-KEBAB-CASE.

2. #[command(prefix = "prefix")] Change a prefix for all commands (the default is /).

3. #[command(description = "description")] Add a sumary description of commands before all commands.

4. #[command(parse_with = "parser")] Change the parser of arguments. Possible values:

• default - the same as the unspecified parser. It only puts all text after the first space into the first argument, which must implement FromStr.

Example

use teloxide::utils::command::BotCommands;

#[derive(BotCommands, PartialEq, Debug)]
#[command(rename_rule = "lowercase")]
enum Command {
    Text(String),
}

let command = Command::parse("/text hello my dear friend!", "").unwrap();
assert_eq!(command, Command::Text("hello my dear friend!".to_string()));

• split - separates a messsage by a given separator (the default is the space character) and parses each part into the corresponding arguments, which must implement FromStr.

Example

use teloxide::utils::command::BotCommands;

#[derive(BotCommands, PartialEq, Debug)]
#[command(rename_rule = "lowercase", parse_with = "split")]
enum Command {
    Nums(u8, u16, i32),
}

let command = Command::parse("/nums 1 32 -5", "").unwrap();
assert_eq!(command, Command::Nums(1, 32, -5));

5. #[command(separator = "sep")] Specify separator used by the split parser. It will be ignored when accompanied by another type of parsers.

Example

use teloxide::utils::command::BotCommands;

#[derive(BotCommands, PartialEq, Debug)]
#[command(rename_rule = "lowercase", parse_with = "split", separator = "|")]
enum Command {
    Nums(u8, u16, i32),
}

let command = Command::parse("/nums 1|32|5", "").unwrap();
assert_eq!(command, Command::Nums(1, 32, 5));

Variant attributes

All variant attributes override the corresponding enum attributes.

1. #[command(rename_rule = "rule")] Rename one command by a rule. Allowed rules are lowercase, UPPERCASE, PascalCase, camelCase, snake_case, SCREAMING_SNAKE_CASE, kebab-case, SCREAMING-KEBAB-CASE.

2. #[command(rename = "name")] Rename one command to name (literal renaming; do not confuse with rename_rule).

3. #[command(description = "description")] Give your command a description. Write "off" for "description" to hide a command.

4. #[command(parse_with = "parser")] Parse arguments of one command with a given parser. parser must be a function of the signature fn(String) -> Result<Tuple, ParseError>, where Tuple corresponds to the variant’s arguments.

Example

use teloxide::utils::command::{BotCommands, ParseError};

fn accept_two_digits(input: String) -> Result<(u8,), ParseError> {
    match input.len() {
        2 => {
            let num = input.parse::<u8>().map_err(|e| ParseError::IncorrectFormat(e.into()))?;
            Ok((num,))
        }
        len => Err(ParseError::Custom(format!("Only 2 digits allowed, not {}", len).into())),
    }
}

#[derive(BotCommands, PartialEq, Debug)]
#[command(rename_rule = "lowercase")]
enum Command {
    #[command(parse_with = accept_two_digits)]
    Num(u8),
}

let command = Command::parse("/num 12", "").unwrap();
assert_eq!(command, Command::Num(12));
let command = Command::parse("/num 333", "");
assert!(command.is_err());

5. #[command(prefix = "prefix")]
6. #[command(separator = "sep")]

These attributes just override the corresponding enum attributes for a specific variant.

Required Methods

fn parse(s: &str, bot_username: &str) -> Result<Self, ParseError>

Parses a command.

bot_username is required to parse commands like /cmd@username_of_the_bot.

fn descriptions() -> CommandDescriptions<'static>

Returns descriptions of the commands suitable to be shown to the user (for example when /help command is used).

fn bot_commands() -> Vec<BotCommand>

Returns a vector of BotCommand that can be used with set_my_commands.

Provided Methods

fn ty() -> PhantomData<Self>

Returns PhantomData<Self> that is used as a param of commands_repl

Examples found in repository

examples/command.rs (line 10)

async fn main() {
    pretty_env_logger::init();
    log::info!("Starting command bot...");

    let bot = Bot::from_env();

    teloxide::commands_repl(bot, answer, Command::ty()).await;
}

examples/admin.rs (line 63)

async fn main() {
    pretty_env_logger::init();
    log::info!("Starting admin bot...");

    let bot = teloxide::Bot::from_env();

    teloxide::commands_repl(bot, action, Command::ty()).await;
}

Implementors