Module: Discordrb::Commands::CommandContainer

Includes:
RateLimiter
Included in:
CommandBot
Defined in:
lib/discordrb/commands/container.rb

Overview

This module holds a collection of commands that can be easily added to by calling the #command function. Other containers can be included into it as well. This allows for modularization of command bots.

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from RateLimiter

#bucket, #clean, #include_buckets, #rate_limited?

Instance Attribute Details

#commands ⇒ Hash<Symbol, Command, CommandAlias> (readonly)

Returns hash of command names and commands this container has.

Returns:

  • (Hash<Symbol, Command, CommandAlias>) —

    hash of command names and commands this container has.



13
14
15
 
# File 'lib/discordrb/commands/container.rb', line 13

def commands
  @commands
end

Instance Method Details

#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.



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# 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

#include!(container) ⇒ Object

Includes another container into this one.

Parameters:

  • container (Module) —

    An EventContainer or CommandContainer that will be included if it can.



98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/discordrb/commands/container.rb', line 98

def include!(container)
  container_modules = container.singleton_class.included_modules

  # If the container is an EventContainer and we can include it, then do that
  include_events(container) if container_modules.include?(Discordrb::EventContainer) && respond_to?(:include_events)

  if container_modules.include? Discordrb::Commands::CommandContainer
    include_commands(container)
    include_buckets(container)
  elsif !container_modules.include? Discordrb::EventContainer
    raise "Could not include! this particular container - ancestors: #{container_modules}"
  end
end

#include_commands(container) ⇒ Object

Adds all commands from another container into this one. Existing commands will be overwritten.

Parameters:



88
89
90
91
92
93
94
 
# File 'lib/discordrb/commands/container.rb', line 88

def include_commands(container)
  handlers = container.instance_variable_get :@commands
  return unless handlers

  @commands ||= {}
  @commands.merge! handlers
end

#remove_command(name) ⇒ Object

Removes a specific command from this container.

Parameters:

  • name (Symbol) —

    The command to remove.



81
82
83
84
 
# File 'lib/discordrb/commands/container.rb', line 81

def remove_command(name)
  @commands ||= {}
  @commands.delete name
end