discordrb 3.1.1 → 3.4.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)
@@ -120,6 +134,7 @@ module Discordrb
     def pm_channel(id)
       id = id.resolve_id
       return @pm_channels[id] if @pm_channels[id]
+
       debug("Creating pm channel with user id #{id}")
       response = API::User.create_pm(token, id)
       channel = Channel.new(JSON.parse(response), self)
@@ -173,9 +188,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://discord.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
@@ -205,7 +220,7 @@ module Discordrb
         return [channel(id)]
       end
 
-      @servers.values.each do |server|
+      @servers.each_value do |server|
         server.channels.each do |channel|
           results << channel if channel.name == channel_name && (server_name || server.name) == server.name && (!type || (channel.type == type))
         end
@@ -214,11 +229,28 @@ 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/colour_rgb.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Discordrb
+  # A colour (red, green and blue values). Used for role colours. If you prefer the American spelling, the alias
+  # {ColorRGB} is also available.
+  class ColourRGB
+    # @return [Integer] the red part of this colour (0-255).
+    attr_reader :red
+
+    # @return [Integer] the green part of this colour (0-255).
+    attr_reader :green
+
+    # @return [Integer] the blue part of this colour (0-255).
+    attr_reader :blue
+
+    # @return [Integer] the colour's RGB values combined into one integer.
+    attr_reader :combined
+    alias_method :to_i, :combined
+
+    # Make a new colour from the combined value.
+    # @param combined [String, Integer] The colour's RGB values combined into one integer or a hexadecimal string
+    # @example Initialize a with a base 10 integer
+    #   ColourRGB.new(7506394) #=> ColourRGB
+    #   ColourRGB.new(0x7289da) #=> ColourRGB
+    # @example Initialize a with a hexadecimal string
+    #   ColourRGB.new('7289da') #=> ColourRGB
+    def initialize(combined)
+      @combined = combined.is_a?(String) ? combined.to_i(16) : combined
+      @red = (@combined >> 16) & 0xFF
+      @green = (@combined >> 8) & 0xFF
+      @blue = @combined & 0xFF
+    end
+
+    # @return [String] the colour as a hexadecimal.
+    def hex
+      @combined.to_s(16)
+    end
+    alias_method :hexadecimal, :hex
+  end
+
+  # Alias for the class {ColourRGB}
+  ColorRGB = ColourRGB
+end

data/lib/discordrb/commands/command_bot.rb

@@ -6,6 +6,7 @@ require 'discordrb/commands/parser'
 require 'discordrb/commands/events'
 require 'discordrb/commands/container'
 require 'discordrb/commands/rate_limiter'
+require 'time'
 
 # Specialized bot to run commands
 
@@ -15,14 +16,15 @@ 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
 
     # Creates a new CommandBot and logs in to Discord.
     # @param attributes [Hash] The attributes to initialize the CommandBot with.
-    # @see {Discordrb::Bot#initialize} for other attributes that should be used to create the underlying regular bot.
+    # @see Discordrb::Bot#initialize Discordrb::Bot#initialize for other attributes that should be used to create the underlying regular bot.
     # @option attributes [String, Array<String>, #call] :prefix The prefix that should trigger this bot's commands. It
     #   can be:
     #
@@ -37,7 +39,7 @@ module Discordrb::Commands
     #     complicated dynamic prefixes (e. g. based on server), or even something else entirely (suffixes, or most
     #     adventurous, infixes).
     # @option attributes [true, false] :advanced_functionality Whether to enable advanced functionality (very powerful
-    #   way to nest commands into chains, see https://github.com/meew0/discordrb/wiki/Commands#command-chain-syntax
+    #   way to nest commands into chains, see https://github.com/shardlab/discordrb/wiki/Commands#command-chain-syntax
     #   for info. Default is false.
     # @option attributes [Symbol, Array<Symbol>, false] :help_command The name of the command that displays info for
     #   other commands. Use an array if you want to have aliases. Default is "help". If none should be created, use
@@ -53,24 +55,24 @@ 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(
         log_mode: attributes[:log_mode],
         token: attributes[:token],
-        application_id: attributes[:application_id],
         client_id: attributes[:client_id],
         type: attributes[:type],
         name: attributes[:name],
@@ -79,7 +81,11 @@ module Discordrb::Commands
         parse_self: attributes[:parse_self],
         shard_id: attributes[:shard_id],
         num_shards: attributes[:num_shards],
-        redact_token: attributes.key?(:redact_token) ? attributes[:redact_token] : true)
+        redact_token: attributes.key?(:redact_token) ? attributes[:redact_token] : true,
+        ignore_bots: attributes[:ignore_bots],
+        compress_mode: attributes[:compress_mode],
+        intents: attributes[:intents]
+      )
 
       @prefix = attributes[:prefix]
       @attributes = {
@@ -124,7 +130,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 = {
@@ -133,14 +142,25 @@ module Discordrb::Commands
       }
 
       return unless @attributes[:help_command]
+
       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```"
@@ -149,7 +169,9 @@ module Discordrb::Commands
           end
           result
         else
-          available_commands = @commands.values.reject { |c| !c.attributes[:help_available] }
+          available_commands = @commands.values.reject do |c|
+            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
             available_commands.reduce "**List of commands:**\n" do |memo, c|
@@ -160,13 +182,22 @@ module Discordrb::Commands
               memo + "`#{c.name}`, "
             end)[0..-3]
           else
-            event.user.pm(available_commands.reduce("**List of commands:**\n") { |a, e| a + "`#{e.name}`, " })[0..-3]
-            'Sending list in PM!'
+            event.user.pm(available_commands.reduce("**List of commands:**\n") { |m, e| m + "`#{e.name}`, " }[0..-3])
+            event.channel.pm? ? '' : 'Sending list in PM!'
           end
         end
       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.
@@ -179,18 +210,24 @@ module Discordrb::Commands
     def execute_command(name, event, arguments, chained = false, check_permissions = true)
       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
         event.respond @attributes[:command_doesnt_exist_message].gsub('%command%', name.to_s) if @attributes[:command_doesnt_exist_message]
         return
       end
       return unless !check_permissions || channels?(event.channel, command.attributes[:channels])
+
+      arguments = arg_check(arguments, command.attributes[:arg_types], event.server) if check_permissions
       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)
@@ -204,12 +241,94 @@ module Discordrb::Commands
       raise
     end
 
+    # Transforms an array of string arguments based on types array.
+    # For example, `['1', '10..14']` with types `[Integer, Range]` would turn into `[1, 10..14]`.
+    def arg_check(args, types = nil, server = nil)
+      return args unless types
+
+      args.each_with_index.map do |arg, i|
+        next arg if types[i].nil? || types[i] == String
+
+        if types[i] == Integer
+          begin
+            Integer(arg, 10)
+          rescue ArgumentError
+            nil
+          end
+        elsif types[i] == Float
+          begin
+            Float(arg)
+          rescue ArgumentError
+            nil
+          end
+        elsif types[i] == Time
+          begin
+            Time.parse arg
+          rescue ArgumentError
+            nil
+          end
+        elsif types[i] == TrueClass || types[i] == FalseClass
+          if arg.casecmp('true').zero? || arg.downcase.start_with?('y')
+            true
+          elsif arg.casecmp('false').zero? || arg.downcase.start_with?('n')
+            false
+          end
+        elsif types[i] == Symbol
+          arg.to_sym
+        elsif types[i] == Encoding
+          begin
+            Encoding.find arg
+          rescue ArgumentError
+            nil
+          end
+        elsif types[i] == Regexp
+          begin
+            Regexp.new arg
+          rescue ArgumentError
+            nil
+          end
+        elsif types[i] == Rational
+          begin
+            Rational(arg)
+          rescue ArgumentError
+            nil
+          end
+        elsif types[i] == Range
+          begin
+            if arg.include? '...'
+              Range.new(*arg.split('...').map(&:to_i), true)
+            elsif arg.include? '..'
+              Range.new(*arg.split('..').map(&:to_i))
+            end
+          rescue ArgumentError
+            nil
+          end
+        elsif types[i] == NilClass
+          nil
+        elsif [Discordrb::User, Discordrb::Role, Discordrb::Emoji].include? types[i]
+          result = parse_mention arg, server
+          result if result.instance_of? types[i]
+        elsif types[i] == Discordrb::Invite
+          resolve_invite_code arg
+        elsif types[i].respond_to?(:from_argument)
+          begin
+            types[i].from_argument arg
+          rescue StandardError
+            nil
+          end
+        else
+          raise ArgumentError, "#{types[i]} doesn't implement from_argument"
+        end
+      end
+    end
+
     # Executes a command in a simple manner, without command chains or permissions.
     # @param chain [String] The command with its arguments separated by spaces.
     # @param event [CommandEvent] The event to pass to the command.
     # @return [String, nil] the command's result, if there is any.
     def simple_execute(chain, event)
       return nil if chain.empty?
+
       args = chain.split(' ')
       execute_command(args[0].to_sym, event, args[1..-1])
     end
@@ -245,6 +364,31 @@ 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
@@ -285,7 +429,7 @@ module Discordrb::Commands
       if @prefix.is_a? String
         standard_prefix_trigger(message.content, @prefix)
       elsif @prefix.is_a? Array
-        @prefix.map { |e| standard_prefix_trigger(message.content, e) }.reduce { |a, e| a || e }
+        @prefix.map { |e| standard_prefix_trigger(message.content, e) }.reduce { |m, e| m || e }
       elsif @prefix.respond_to? :call
         @prefix.call(message)
       end
@@ -293,37 +437,48 @@ module Discordrb::Commands
 
     def standard_prefix_trigger(message, prefix)
       return nil unless message.start_with? prefix
+
       message[prefix.length..-1]
     end
 
     def required_permissions?(member, required, channel = nil)
       required.reduce(true) do |a, action|
-        a && !member.webhook? && member.permission?(action, channel)
+        a && !member.webhook? && !member.is_a?(Discordrb::Recipient) && member.permission?(action, channel)
       end
     end
 
     def required_roles?(member, required)
-      return (required.nil? || required.empty?) if member.webhook?
-      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? Fixnum
-          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
 
@@ -341,7 +496,7 @@ module Discordrb::Commands
           else
             event.respond result unless result.nil? || result.empty?
           end
-        rescue => e
+        rescue StandardError => e
           log_exception(e)
         ensure
           @event_threads.delete(t)