discordrb 3.2.1 → 3.3.0

data/lib/discordrb/cache.rb

@@ -15,6 +15,8 @@ module Discordrb
     def init_cache
       @users = {}
 
+      @voice_regions = {}
+
       @servers = {}
 
       @channels = {}
@@ -23,6 +25,18 @@ module Discordrb
       @restricted_channels = []
     end
 
+    # Returns or caches the available voice regions
+    def voice_regions
+      return @voice_regions unless @voice_regions.empty?
+
+      regions = JSON.parse API.voice_regions(token)
+      regions.each do |data|
+        @voice_regions[data['id']] = VoiceRegion.new(data)
+      end
+
+      @voice_regions
+    end
+
     # Gets a channel given its ID. This queries the internal channel cache, and if the channel doesn't
     # exist in there, it will get the data from Discord.
     # @param id [Integer] The channel ID for which to search for.
@@ -83,7 +97,7 @@ module Discordrb
       LOGGER.out("Resolving server #{id}")
       begin
         response = API::Server.resolve(token, id)
-      rescue RestClient::ResourceNotFound
+      rescue Discordrb::Errors::NoPermission
         return nil
       end
       server = Server.new(JSON.parse(response), self)
@@ -173,9 +187,9 @@ module Discordrb
     #
     #    * An {Invite} object
     #    * The code for an invite
-    #    * A fully qualified invite URL (e. g. `https://discordapp.com/invite/0A37aN7fasF7n83q`)
-    #    * A short invite URL with protocol (e. g. `https://discord.gg/0A37aN7fasF7n83q`)
-    #    * A short invite URL without protocol (e. g. `discord.gg/0A37aN7fasF7n83q`)
+    #    * A fully qualified invite URL (e.g. `https://discordapp.com/invite/0A37aN7fasF7n83q`)
+    #    * A short invite URL with protocol (e.g. `https://discord.gg/0A37aN7fasF7n83q`)
+    #    * A short invite URL without protocol (e.g. `discord.gg/0A37aN7fasF7n83q`)
     # @return [String] Only the code for the invite.
     def resolve_invite_code(invite)
       invite = invite.code if invite.is_a? Discordrb::Invite
@@ -214,11 +228,27 @@ module Discordrb
       results
     end
 
-    # Finds a user given its username.
-    # @param username [String] The username to look for.
-    # @return [Array<User>] The array of users that were found. May be empty if none were found.
-    def find_user(username)
-      @users.values.find_all { |e| e.username == username }
+    # Finds a user given its username or username & discriminator.
+    # @overload find_user(username)
+    #   Find all cached users with a certain username.
+    #   @param username [String] The username to look for.
+    #   @return [Array<User>] The array of users that were found. May be empty if none were found.
+    # @overload find_user(username, discrim)
+    #   Find a cached user with a certain username and discriminator.
+    #   Find a user by name and discriminator
+    #   @param username [String] The username to look for.
+    #   @param discrim [String] The user's discriminator
+    #   @return [User, nil] The user that was found, or `nil` if none was found
+    # @note This method only searches through users that have been cached. Users that have not yet been cached
+    #   by the bot but still share a connection with the user (mutual server) will not be found.
+    # @example Find users by name
+    #   bot.find_user('z64') #=> Array<User>
+    # @example Find a user by name and discriminator
+    #   bot.find_user('z64', '2639') #=> User
+    def find_user(username, discrim = nil)
+      users = @users.values.find_all { |e| e.username == username }
+      return users.find { |u| u.discrim == discrim } if discrim
+      users
     end
   end
 end

data/lib/discordrb/commands/command_bot.rb

@@ -16,7 +16,8 @@ module Discordrb::Commands
     # @return [Hash] this bot's attributes.
     attr_reader :attributes
 
-    # @return [String] the prefix commands are triggered with.
+    # @return [String, Array<String>, #call] the prefix commands are triggered with.
+    # @see #initialize
     attr_reader :prefix
 
     include CommandContainer
@@ -54,19 +55,19 @@ module Discordrb::Commands
     # @option attributes [Array<String, Integer, Channel>] :channels The channels this command bot accepts commands on.
     #   Superseded if a command has a 'channels' attribute.
     # @option attributes [String] :previous Character that should designate the result of the previous command in
-    #   a command chain (see :advanced_functionality). Default is '~'.
+    #   a command chain (see :advanced_functionality). Default is '~'. Set to an empty string to disable.
     # @option attributes [String] :chain_delimiter Character that should designate that a new command begins in the
-    #   command chain (see :advanced_functionality). Default is '>'.
+    #   command chain (see :advanced_functionality). Default is '>'. Set to an empty string to disable.
     # @option attributes [String] :chain_args_delim Character that should separate the command chain arguments from the
-    #   chain itself (see :advanced_functionality). Default is ':'.
+    #   chain itself (see :advanced_functionality). Default is ':'. Set to an empty string to disable.
     # @option attributes [String] :sub_chain_start Character that should start a sub-chain (see
-    #   :advanced_functionality). Default is '['.
+    #   :advanced_functionality). Default is '['. Set to an empty string to disable.
     # @option attributes [String] :sub_chain_end Character that should end a sub-chain (see
-    #   :advanced_functionality). Default is ']'.
+    #   :advanced_functionality). Default is ']'. Set to an empty string to disable.
     # @option attributes [String] :quote_start Character that should start a quoted string (see
-    #   :advanced_functionality). Default is '"'.
+    #   :advanced_functionality). Default is '"'. Set to an empty string to disable.
     # @option attributes [String] :quote_end Character that should end a quoted string (see
-    #   :advanced_functionality). Default is '"'.
+    #   :advanced_functionality). Default is '"' or the same as :quote_start. Set to an empty string to disable.
     # @option attributes [true, false] :ignore_bots Whether the bot should ignore bot accounts or not. Default is false.
     def initialize(attributes = {})
       super(
@@ -81,7 +82,8 @@ module Discordrb::Commands
         shard_id: attributes[:shard_id],
         num_shards: attributes[:num_shards],
         redact_token: attributes.key?(:redact_token) ? attributes[:redact_token] : true,
-        ignore_bots: attributes[:ignore_bots])
+        ignore_bots: attributes[:ignore_bots],
+        compress_mode: attributes[:compress_mode])
 
       @prefix = attributes[:prefix]
       @attributes = {
@@ -126,7 +128,10 @@ module Discordrb::Commands
         quote_start: attributes[:quote_start] || '"',
 
         # Quoted mode ending character
-        quote_end: attributes[:quote_end] || '"'
+        quote_end: attributes[:quote_end] || attributes[:quote_start] || '"',
+
+        # Default block for handling internal exceptions, or a string to respond with
+        rescue: attributes[:rescue]
       }
 
       @permissions = {
@@ -138,11 +143,20 @@ module Discordrb::Commands
       command(@attributes[:help_command], max_args: 1, description: 'Shows a list of all the commands available or displays help for a specific command.', usage: 'help [command name]') do |event, command_name|
         if command_name
           command = @commands[command_name.to_sym]
+          if command.is_a?(CommandAlias)
+            command = command.aliased_command
+            command_name = command.name
+          end
           return "The command `#{command_name}` does not exist!" unless command
           desc = command.attributes[:description] || '*No description available*'
           usage = command.attributes[:usage]
           parameters = command.attributes[:parameters]
           result = "**`#{command_name}`**: #{desc}"
+          aliases = command_aliases(command_name.to_sym)
+          unless aliases.empty?
+            result += "\nAliases: "
+            result += aliases.map { |a| "`#{a.name}`" }.join(', ')
+          end
           result += "\nUsage: `#{usage}`" if usage
           if parameters
             result += "\nAccepted Parameters:\n```"
@@ -152,7 +166,7 @@ module Discordrb::Commands
           result
         else
           available_commands = @commands.values.reject do |c|
-            !c.attributes[:help_available] || !required_roles?(event.user, c.attributes[:required_roles]) || !required_permissions?(event.user, c.attributes[:required_permissions], event.channel)
+            c.is_a?(CommandAlias) || !c.attributes[:help_available] || !required_roles?(event.user, c.attributes[:required_roles]) || !allowed_roles?(event.user, c.attributes[:allowed_roles]) || !required_permissions?(event.user, c.attributes[:required_permissions], event.channel)
           end
           case available_commands.length
           when 0..5
@@ -171,6 +185,15 @@ module Discordrb::Commands
       end
     end
 
+    # Returns all aliases for the command with the given name
+    # @param name [Symbol] the name of the `Command`
+    # @return [Array<CommandAlias>]
+    def command_aliases(name)
+      commands.values.select do |command|
+        command.is_a?(CommandAlias) && command.aliased_command.name == name
+      end
+    end
+
     # Executes a particular command on the bot. Mostly useful for internal stuff, but one can never know.
     # @param name [Symbol] The command to execute.
     # @param event [CommandEvent] The event to pass to the command.
@@ -184,6 +207,7 @@ module Discordrb::Commands
       debug("Executing command #{name} with arguments #{arguments}")
       return unless @commands
       command = @commands[name]
+      command = command.aliased_command if command.is_a?(CommandAlias)
       return unless !check_permissions || channels?(event.channel, @attributes[:channels]) ||
                     (command && !command.attributes[:channels].nil?)
       unless command
@@ -195,7 +219,8 @@ module Discordrb::Commands
       if (check_permissions &&
          permission?(event.author, command.attributes[:permission_level], event.server) &&
          required_permissions?(event.author, command.attributes[:required_permissions], event.channel) &&
-         required_roles?(event.author, command.attributes[:required_roles])) ||
+         required_roles?(event.author, command.attributes[:required_roles]) &&
+         allowed_roles?(event.author, command.attributes[:allowed_roles])) ||
          !check_permissions
         event.command = command
         result = command.call(event, arguments, chained, check_permissions)
@@ -283,7 +308,7 @@ module Discordrb::Commands
             nil
           end
         else
-          raise ArgumentError, "#{type} doesn't implement from_argument"
+          raise ArgumentError, "#{types[i]} doesn't implement from_argument"
         end
       end
     end
@@ -329,6 +354,30 @@ module Discordrb::Commands
       [@permissions[:users][user.id] || 0, determined_level].max >= level
     end
 
+    # @see CommandBot#update_channels
+    def channels=(channels)
+      update_channels(channels)
+    end
+
+    # Update the list of channels the bot accepts commands from.
+    # @param channels [Array<String, Integer, Channel>] The channels this command bot accepts commands on.
+    def update_channels(channels = [])
+      @attributes[:channels] = Array(channels)
+    end
+
+    # Add a channel to the list of channels the bot accepts commands from.
+    # @param channel [String, Integer, Channel] The channel name, integer ID, or `Channel` object to be added
+    def add_channel(channel)
+      return if @attributes[:channels].find { |c| channel.resolve_id == c.resolve_id }
+      @attributes[:channels] << channel
+    end
+
+    # Remove a channel from the list of channels the bot accepts commands from.
+    # @param channel [String, Integer, Channel] The channel name, integer ID, or `Channel` object to be removed
+    def remove_channel(channel)
+      @attributes[:channels].delete_if { |c| channel.resolve_id == c.resolve_id }
+    end
+
     private
 
     # Internal handler for MESSAGE_CREATE that is overwritten to allow for command handling
@@ -387,27 +436,33 @@ module Discordrb::Commands
     end
 
     def required_roles?(member, required)
-      return (required.nil? || required.empty?) if member.webhook? || member.is_a?(Discordrb::Recipient)
-      if required.is_a? Array
+      return true if member.webhook? || member.is_a?(Discordrb::Recipient) || required.nil? || required.empty?
+      required.is_a?(Array) ? check_multiple_roles(member, required) : member.role?(role)
+    end
+
+    def allowed_roles?(member, required)
+      return true if member.webhook? || member.is_a?(Discordrb::Recipient) || required.nil? || required.empty?
+      required.is_a?(Array) ? check_multiple_roles(member, required, false) : member.role?(role)
+    end
+
+    def check_multiple_roles(member, required, all_roles = true)
+      if all_roles
         required.all? do |role|
           member.role?(role)
         end
       else
-        member.role?(role)
+        required.any? do |role|
+          member.role?(role)
+        end
       end
     end
 
     def channels?(channel, channels)
       return true if channels.nil? || channels.empty?
       channels.any? do |c|
-        if c.is_a? String
-          # Make sure to remove the "#" from channel names in case it was specified
-          c.delete('#') == channel.name
-        elsif c.is_a? Integer
-          c == channel.id
-        else
-          c == channel
-        end
+        # if c is string, make sure to remove the "#" from channel names in case it was specified
+        return true if c.is_a?(String) && c.delete('#') == channel.name
+        c.resolve_id == channel.resolve_id
       end
     end
 

data/lib/discordrb/commands/container.rb

@@ -22,7 +22,10 @@ module Discordrb::Commands
     #   the message by setting this option to false.
     # @option attributes [Array<Symbol>] :required_permissions Discord action permissions (e.g. `:kick_members`) that
     #   should be required to use this command. See {Discordrb::Permissions::Flags} for a list.
-    # @option attributes [Array<Role>, Array<#resolve_id>] :required_roles Roles that user should have to use this command.
+    # @option attributes [Array<Role>, Array<#resolve_id>] :required_roles Roles that user must have to use this command
+    #   (user must have all of them).
+    # @option attributes [Array<Role>, Array<#resolve_id>] :allowed_roles Roles that user should have to use this command
+    #   (user should have at least one of them).
     # @option attributes [Array<String, Integer, Channel>] :channels 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.
     # @option attributes [true, false] :chain_usable Whether this command is able to be used inside of a command chain
@@ -44,9 +47,16 @@ module Discordrb::Commands
     #   command will be available again.
     # @option attributes [Symbol] :bucket The rate limit bucket that should be used for rate limiting. No rate limiting
     #   will be done if unspecified or nil.
+    # @option attributes [String, #call] :rescue 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`.
     # @yield The block is executed when the command is executed.
     # @yieldparam event [CommandEvent] The event of the message that contained the command.
+    # @note `LocalJumpError`s are rescued from internally, giving bots the opportunity to use `return` or `break` in
+    #   their blocks without propagating an exception.
     # @return [Command] The command that was added.
+    # @deprecated The command name argument will no longer support arrays in the next release.
+    #   Use the `aliases` attribute instead.
     def command(name, attributes = {}, &block)
       @commands ||= {}
       if name.is_a? Array
@@ -59,7 +69,11 @@ module Discordrb::Commands
 
         new_command
       else
-        @commands[name] = Command.new(name, attributes, &block)
+        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
     end
 

data/lib/discordrb/commands/parser.rb

@@ -22,9 +22,12 @@ module Discordrb::Commands
         # Discord action permissions required to use this command
         required_permissions: attributes[:required_permissions] || [],
 
-        # Roles required to use this command
+        # Roles required to use this command (all? comparison)
         required_roles: attributes[:required_roles] || [],
 
+        # Roles allowed to use this command (any? comparison)
+        allowed_roles: attributes[:allowed_roles] || [],
+
         # Channels this command can be used on
         channels: attributes[:channels] || nil,
 
@@ -57,7 +60,13 @@ module Discordrb::Commands
         rate_limit_message: attributes[:rate_limit_message],
 
         # Rate limiting bucket (nil for no rate limiting)
-        bucket: attributes[:bucket]
+        bucket: attributes[:bucket],
+
+        # Block for handling internal exceptions, or a string to respond with
+        rescue: attributes[:rescue],
+
+        # A list of aliases that reference this command
+        aliases: attributes[:aliases] || []
       }
 
       @block = block
@@ -100,8 +109,31 @@ module Discordrb::Commands
 
       result = @block.call(event, *arguments)
       event.drain_into(result)
-    rescue LocalJumpError # occurs when breaking
-      nil
+    rescue LocalJumpError => ex # occurs when breaking
+      result = ex.exit_value
+      event.drain_into(result)
+    rescue => exception # Something went wrong inside our @block!
+      rescue_value = @attributes[:rescue] || event.bot.attributes[:rescue]
+      if rescue_value
+        event.respond(rescue_value.gsub('%exception%', exception.message)) if rescue_value.is_a?(String)
+        rescue_value.call(event, exception) if rescue_value.respond_to?(:call)
+      end
+
+      raise exception
+    end
+  end
+
+  # A command that references another command
+  class CommandAlias
+    # @return [Symbol] the name of this alias
+    attr_reader :name
+
+    # @return [Command] the command this alias points to
+    attr_reader :aliased_command
+
+    def initialize(name, aliased_command)
+      @name = name
+      @aliased_command = aliased_command
     end
   end
 
@@ -195,10 +227,14 @@ module Discordrb::Commands
       chain_to_split = @chain
 
       # Don't break if a command is called the same thing as the chain delimiter
-      chain_to_split = chain_to_split.slice(1..-1) if chain_to_split.start_with?(@attributes[:chain_delimiter])
+      chain_to_split = chain_to_split.slice(1..-1) if !@attributes[:chain_delimiter].empty? && chain_to_split.start_with?(@attributes[:chain_delimiter])
 
       first = true
-      split_chain = chain_to_split.split(@attributes[:chain_delimiter])
+      split_chain = if @attributes[:chain_delimiter].empty?
+                      [chain_to_split]
+                    else
+                      chain_to_split.split(@attributes[:chain_delimiter])
+                    end
       split_chain.each do |command|
         command = @attributes[:chain_delimiter] + command if first && @chain.start_with?(@attributes[:chain_delimiter])
         first = false
@@ -228,6 +264,9 @@ module Discordrb::Commands
 
         # Finally execute the command
         prev = @bot.execute_command(command_name.to_sym, event, arguments, split_chain.length > 1 || @subchain)
+
+        # Stop chain if execute_command failed (maybe the command doesn't exist, or permissions failed, etc.)
+        break unless prev
       end
 
       prev
@@ -267,7 +306,7 @@ module Discordrb::Commands
     private
 
     def divide_chain(chain)
-      chain_args_index = chain.index @attributes[:chain_args_delim]
+      chain_args_index = chain.index(@attributes[:chain_args_delim]) unless @attributes[:chain_args_delim].empty?
       chain_args = []
 
       if chain_args_index

data/lib/discordrb/commands/rate_limiter.rb

@@ -37,8 +37,9 @@ module Discordrb::Commands
     # Performs a rate limiting request
     # @param thing [#resolve_id, Integer, Symbol] The particular thing that should be rate-limited (usually a user/channel, but you can also choose arbitrary integers or symbols)
     # @param rate_limit_time [Time] The time to base the rate limiting on, only useful for testing.
+    # @param increment [Integer] How much to increment the rate-limit counter. Default is 1.
     # @return [Integer, false] the waiting time until the next request, in seconds, or false if the request succeeded
-    def rate_limited?(thing, rate_limit_time = nil)
+    def rate_limited?(thing, rate_limit_time = nil, increment: 1)
       key = resolve_key thing
       limit_hash = @bucket[key]
 
@@ -47,7 +48,7 @@ module Discordrb::Commands
         @bucket[key] = {
           last_time: Time.now,
           set_time: Time.now,
-          count: 1
+          count: increment
         }
 
         return false
@@ -56,7 +57,7 @@ module Discordrb::Commands
       # Define the time at which we're being rate limited once so it doesn't get inaccurate
       rate_limit_time ||= Time.now
 
-      if @limit && (limit_hash[:count] + 1) > @limit
+      if @limit && (limit_hash[:count] + increment) > @limit
         # Second case: Count is over the limit and the time has not run out yet
         return (limit_hash[:set_time] + @time_span) - rate_limit_time if @time_span && rate_limit_time < (limit_hash[:set_time] + @time_span)
 
@@ -72,7 +73,7 @@ module Discordrb::Commands
       else
         # Fifth case: no rate limiting at all! Increment the count, set the last_time, and return false
         limit_hash[:last_time] = rate_limit_time
-        limit_hash[:count] += 1
+        limit_hash[:count] += increment
         false
       end
     end
@@ -104,13 +105,14 @@ module Discordrb::Commands
     # Performs a rate limit request.
     # @param key [Symbol] Which bucket to perform the request for.
     # @param thing [#resolve_id, Integer, Symbol] What should be rate-limited.
+    # @param increment (see Bucket#rate_limited?)
     # @see Bucket#rate_limited?
     # @return [Integer, false] How much time to wait or false if the request succeeded.
-    def rate_limited?(key, thing)
+    def rate_limited?(key, thing, increment: 1)
       # Check whether the bucket actually exists
       return false unless @buckets && @buckets[key]
 
-      @buckets[key].rate_limited?(thing)
+      @buckets[key].rate_limited?(thing, increment: increment)
     end
 
     # Cleans all buckets