Method: Discordrb::Commands::CommandContainer#command

Defined in:

lib/discordrb/commands/container.rb

#command(name, attributes = {}) {|event| ... } ⇒ Command

Note:

LocalJumpErrors are rescued from internally, giving bots the opportunity to use return or break in their blocks without propagating an exception.

Adds a new command to the container.

Parameters:

• name (Symbol) —

  The name of the command to add.

• attributes (Hash) (defaults to: {}) —

  The attributes to initialize the command with.

Options Hash (attributes):

• :aliases (Array<Symbol>) —

  A list of additional names for this command. This in effect creates Discordrb::Commands::CommandAlias objects in the container (#commands) that refer to the newly created command. Additionally, the default help command will identify these command names as an alias where applicable.

• :permission_level (Integer) —

  The minimum permission level that can use this command, inclusive. See Discordrb::Commands::CommandBot#set_user_permission and Discordrb::Commands::CommandBot#set_role_permission.

• :permission_message (String, false) —

  Message to display when a user does not have sufficient permissions to execute a command. %name% in the message will be replaced with the name of the command. Disable the message by setting this option to false.

• :required_permissions (Array<Symbol>) —

  Discord action permissions (e.g. :kick_members) that should be required to use this command. See Permissions::FLAGS for a list.

• :required_roles (Array<Role>, Array<String, Integer>) —

  Roles, or their IDs, that user must have to use this command (user must have all of them).

• :allowed_roles (Array<Role>, Array<String, Integer>) —

  Roles, or their IDs, that user should have to use this command (user should have at least one of them).

• :channels (Array<String, Integer, Channel>) —

  The channels that this command can be used on. An empty array indicates it can be used on any channel. Supersedes the command bot attribute.

• :chain_usable (true, false) —

  Whether this command is able to be used inside of a command chain or sub-chain. Typically used for administrative commands that shouldn't be done carelessly.

• :help_available (true, false) —

  Whether this command is visible in the help command. See the :help_command attribute of Discordrb::Commands::CommandBot#initialize.

• :description (String) —

  A short description of what this command does. Will be shown in the help command if the user asks for it.

• :usage (String) —

  A short description of how this command should be used. Will be displayed in the help command or if the user uses it wrong.

• :arg_types (Array<Class>) —

  An array of argument classes which will be used for type-checking. Hard-coded for some native classes, but can be used with any class that implements static method from_argument.

• :min_args (Integer) —

  The minimum number of arguments this command should have. If a user attempts to call the command with fewer arguments, the usage information will be displayed, if it exists.

• :max_args (Integer) —

  The maximum number of arguments the command should have.

• :rate_limit_message (String) —

  The message that should be displayed if the command hits a rate limit. None if unspecified or nil. %time% in the message will be replaced with the time in seconds when the command will be available again.

• :bucket (Symbol) —

  The rate limit bucket that should be used for rate limiting. No rate limiting will be done if unspecified or nil.

• :rescue (String, #call) —

  A string to respond with, or a block to be called in the event an exception is raised internally. If given a String, %exception% will be substituted with the exception's #message. If given a Proc, it will be passed the CommandEvent along with the Exception.

Yields:

• The block is executed when the command is executed.

Yield Parameters:

• event (CommandEvent) —

  The event of the message that contained the command.

Returns:

• (Command) —

  The command that was added.

# File 'lib/discordrb/commands/container.rb', line 61

def command(name, attributes = {}, &block)
  @commands ||= {}

  # TODO: Remove in 4.0
  if name.is_a?(Array)
    name, *aliases = name
    attributes[:aliases] = aliases if attributes[:aliases].nil?
    Discordrb::LOGGER.warn("While registering command #{name.inspect}")
    Discordrb::LOGGER.warn('Arrays for command aliases is removed. Please use `aliases` argument instead.')
  end

  new_command = Command.new(name, attributes, &block)
  new_command.attributes[:aliases].each do |aliased_name|
    @commands[aliased_name] = CommandAlias.new(aliased_name, new_command)
  end
  @commands[name] = new_command
end