discordrb 1.6.6 → 1.7.0

data/lib/discordrb/commands/command_bot.rb

@@ -2,18 +2,56 @@ require 'discordrb/bot'
 require 'discordrb/data'
 require 'discordrb/commands/parser'
 require 'discordrb/commands/events'
+require 'discordrb/commands/container'
+require 'discordrb/commands/rate_limiter'
 
 # Specialized bot to run commands
 
 module Discordrb::Commands
   # Bot that supports commands and command chains
   class CommandBot < Discordrb::Bot
-    attr_reader :attributes, :prefix
-
+    # @return [Hash] this bot's attributes.
+    attr_reader :attributes
+
+    # @return [String] the prefix commands are triggered with.
+    attr_reader :prefix
+
+    include CommandContainer
+
+    # Creates a new CommandBot and logs in to Discord.
+    # @param email [String] The email to use to log in.
+    # @param password [String] The password corresponding to the email.
+    # @param prefix [String] The prefix that should trigger this bot's commands. Can be any string (including the empty
+    #   string), but note that it will be literal - if the prefix is "hi" then the corresponding trigger string for
+    #   a command called "test" would be "hitest". Don't forget to put spaces in if you need them!
+    # @param attributes [Hash] The attributes to initialize the CommandBot with.
+    # @param debug [true, false] Whether or not debug mode should be used - debug mode logs tons of extra stuff to the
+    #   console that may be useful in development.
+    # @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
+    #   for info. Default is true.
+    # @option attributes [Symbol, Array<Symbol>] :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".
+    # @option attributes [String] :command_doesnt_exist_message The message that should be displayed if a user attempts
+    #   to use a command that does not exist. If none is specified, no message will be displayed. In the message, you
+    #   can use the string '%command%' that will be replaced with the name of the command.
+    # @option attributes [String] :previous Character that should designate the result of the previous command in
+    #   a command chain (see :advanced_functionality). Default is '~'.
+    # @option attributes [String] :chain_delimiter Character that should designate that a new command begins in the
+    #   command chain (see :advanced_functionality). Default is '>'.
+    # @option attributes [String] :chain_args_delim Character that should separate the command chain arguments from the
+    #   chain itself (see :advanced_functionality). Default is ':'.
+    # @option attributes [String] :sub_chain_start Character that should start a sub-chain (see
+    #   :advanced_functionality). Default is '['.
+    # @option attributes [String] :sub_chain_end Character that should end a sub-chain (see
+    #   :advanced_functionality). Default is ']'.
+    # @option attributes [String] :quote_start Character that should start a quoted string (see
+    #   :advanced_functionality). Default is '"'.
+    # @option attributes [String] :quote_end Character that should end a quoted string (see
+    #   :advanced_functionality). Default is '"'.
     def initialize(email, password, prefix, attributes = {}, debug = false)
       super(email, password, debug)
       @prefix = prefix
-      @commands = {}
       @attributes = {
         # Whether advanced functionality such as command chains are enabled
         advanced_functionality: attributes[:advanced_functionality].nil? ? true : attributes[:advanced_functionality],
@@ -81,16 +119,13 @@ module Discordrb::Commands
       end
     end
 
-    def command(name, attributes = {}, &block)
-      if name.is_a? Array
-        new_command = Command.new(name[0], attributes, &block)
-        name.each { |n| @commands[n] = new_command }
-        new_command
-      else
-        @commands[name] = Command.new(name, attributes, &block)
-      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.
+    # @param arguments [Array<String>] The arguments to pass to the command.
+    # @param chained [true, false] Whether or not it should be executed as part of a command chain. If this is false,
+    #   commands that have chain_usable set to false will not work.
+    # @return [String, nil] the command's result, if there is any.
     def execute_command(name, event, arguments, chained = false)
       debug("Executing command #{name} with arguments #{arguments}")
       command = @commands[name]
@@ -107,12 +142,45 @@ module Discordrb::Commands
       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
 
+    # Sets the permission level of a user
+    # @param id [Integer] the ID of the user whose level to set
+    # @param level [Integer] the level to set the permission to
+    def set_user_permission(id, level)
+      @permissions[:users][id] = level
+    end
+
+    # Sets the permission level of a role - this applies to all users in the role
+    # @param id [Integer] the ID of the role whose level to set
+    # @param level [Integer] the level to set the permission to
+    def set_role_permission(id, level)
+      @permissions[:roles][id] = level
+    end
+
+    # Check if a user has permission to do something
+    # @param user [User] The user to check
+    # @param level [Integer] The minimum permission level the user should have (inclusive)
+    # @param server [Server] The server on which to check
+    # @return [true, false] whether or not the user has the given permission
+    def permission?(user, level, server)
+      determined_level = server.nil? ? 0 : user.roles[server.id].each.reduce(0) do |memo, role|
+        [@permissions[:roles][role.id] || 0, memo].max
+      end
+      [@permissions[:users][user.id] || 0, determined_level].max >= level
+    end
+
+    private
+
+    # Internal handler for MESSAGE_CREATE that is overwritten to allow for command handling
     def create_message(data)
       message = Discordrb::Message.new(data, self)
       event = CommandEvent.new(message, self)
@@ -144,20 +212,5 @@ module Discordrb::Commands
         end
       end
     end
-
-    def set_user_permission(id, level)
-      @permissions[:users][id] = level
-    end
-
-    def set_role_permission(id, level)
-      @permissions[:roles][id] = level
-    end
-
-    def permission?(user, level, server)
-      determined_level = server.nil? ? 0 : user.roles[server.id].each.reduce(0) do |memo, role|
-        [@permissions[:roles][role.id] || 0, memo].max
-      end
-      [@permissions[:users][user.id] || 0, determined_level].max >= level
-    end
   end
 end

data/lib/discordrb/commands/container.rb

@@ -0,0 +1,78 @@
+require 'discordrb/container'
+require 'discordrb/commands/rate_limiter'
+
+module Discordrb::Commands
+  # This module holds a collection of commands that can be easily added to by calling the {CommandContainer#command}
+  # function. Other containers can be included into it as well. This allows for modularization of command bots.
+  module CommandContainer
+    include RateLimiter
+
+    # Adds a new command to the container.
+    # @param name [Symbol] The name of the command to add.
+    # @param attributes [Hash] The attributes to initialize the command with.
+    # @option attributes [Integer] :permission_level The minimum permission level that can use this command, inclusive.
+    #   See {CommandBot#set_user_permission} and {CommandBot#set_role_permission}.
+    # @option attributes [true, false] :chain_usable 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.
+    # @option attributes [true, false] :help_available Whether this command is visible in the help command. See the
+    #   :help_command attribute of {CommandBot#initialize}.
+    # @option attributes [String] :description A short description of what this command does. Will be shown in the help
+    #   command if the user asks for it.
+    # @option attributes [String] :usage A short description of how this command should be used. Will be displayed in
+    #   the help command or if the user uses it wrong.
+    # @option attributes [Integer] :min_args 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.
+    # @option attributes [Integer] :max_args The maximum number of arguments the command should have.
+    # @option attributes [String] :rate_limit_message 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.
+    # @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.
+    # @yield The block is executed when the command is executed.
+    # @yieldparam event [CommandEvent] The event of the message that contained the command.
+    # @return [Command] The command that was added.
+    def command(name, attributes = {}, &block)
+      @commands ||= {}
+      if name.is_a? Array
+        new_command = Command.new(name[0], attributes, &block)
+        name.each { |n| @commands[n] = new_command }
+        new_command
+      else
+        @commands[name] = Command.new(name, attributes, &block)
+      end
+    end
+
+    # Removes a specific command from this container.
+    # @param name [Symbol] The command to remove.
+    def remove_command(name)
+      @commands ||= {}
+      @commands.delete name
+    end
+
+    # Adds all commands from another container into this one. Existing commands will be overwritten.
+    # @param container [Module] A module that `extend`s {CommandContainer} from which the commands will be added.
+    def include_commands(container)
+      handlers = container.instance_variable_get '@commands'
+      @commands ||= {}
+      @commands.merge! handlers
+    end
+
+    # Includes another container into this one.
+    # @param container [Module] An EventContainer or CommandContainer that will be included if it can.
+    def include!(container)
+      container_modules = container.singleton_class.included_modules
+
+      # If the container is an EventContainer and we can include it, then do that
+      if container_modules.include?(Discordrb::EventContainer) && respond_to?(:include_events)
+        include_events(container)
+      end
+
+      if container_modules.include? Discordrb::Commands::CommandContainer
+        include_commands(container)
+        include_buckets(container)
+      elsif !container_modules.include? Discordrb::EventContainer
+        fail "Could not include! this particular container - ancestors: #{container_modules}"
+      end
+    end
+  end
+end

data/lib/discordrb/commands/events.rb

@@ -1,19 +1,9 @@
 require 'discordrb/events/message'
 
 module Discordrb::Commands
-  # Extension of MessageEvent for commands that contains the command called, makes the bot readable and adds a message to be saved
+  # Extension of MessageEvent for commands that contains the command called and makes the bot readable
   class CommandEvent < Discordrb::Events::MessageEvent
-    attr_reader :bot, :saved_message
+    attr_reader :bot
     attr_accessor :command
-
-    def initialize(message, bot)
-      super(message, bot)
-      @saved_message = ''
-    end
-
-    def <<(message)
-      @saved_message += "#{message}\n"
-      nil
-    end
   end
 end

data/lib/discordrb/commands/parser.rb

@@ -1,8 +1,13 @@
 module Discordrb::Commands
   # Command that can be called in a chain
   class Command
-    attr_reader :attributes, :name
+    # @return [Hash] the attributes the command was initialized with
+    attr_reader :attributes
 
+    # @return [Symbol] the name of this command
+    attr_reader :name
+
+    # @!visibility private
     def initialize(name, attributes = {}, &block)
       @name = name
       @attributes = {
@@ -25,12 +30,24 @@ module Discordrb::Commands
         min_args: attributes[:min_args] || 0,
 
         # Maximum number of arguments (-1 for no limit)
-        max_args: attributes[:max_args] || -1
+        max_args: attributes[:max_args] || -1,
+
+        # Message to display upon rate limiting (%time% in the message for the remaining time until the next possible
+        # request, nil for no message)
+        rate_limit_message: attributes[:rate_limit_message],
+
+        # Rate limiting bucket (nil for no rate limiting)
+        bucket: attributes[:bucket]
       }
 
       @block = block
     end
 
+    # Calls this command and executes the code inside.
+    # @param event [CommandEvent] The event to call the command with.
+    # @param arguments [Array<String>] The attributes for the command.
+    # @param chained [true, false] Whether or not this command is part of a command chain.
+    # @return [String] the result of the execution.
     def call(event, arguments, chained = false)
       if arguments.length < @attributes[:min_args]
         event.respond "Too few arguments for command `#{name}`!"
@@ -48,12 +65,26 @@ module Discordrb::Commands
           return
         end
       end
+
+      rate_limited = event.bot.rate_limited?(@attributes[:bucket], event.author)
+      if @attributes[:bucket] && rate_limited
+        if @attributes[:rate_limit_message]
+          event.respond @attributes[:rate_limit_message].gsub('%time%', rate_limited.round(2).to_s)
+        end
+        return
+      end
+
       @block.call(event, *arguments)
+    rescue LocalJumpError # occurs when breaking
+      nil
     end
   end
 
   # Command chain, may have multiple commands, nested and commands
   class CommandChain
+    # @param chain [String] The string the chain should be parsed from.
+    # @param bot [CommandBot] The bot that executes this command chain.
+    # @param subchain [true, false] Whether this chain is a sub chain of another chain.
     def initialize(chain, bot, subchain = false)
       @attributes = bot.attributes
       @chain = chain
@@ -61,6 +92,10 @@ module Discordrb::Commands
       @subchain = subchain
     end
 
+    # Parses the command chain itself, including sub-chains, and executes it. Executes only the command chain, without
+    # its chain arguments.
+    # @param event [CommandEvent] The event to execute the chain with.
+    # @return [String] the result of the execution.
     def execute_bare(event)
       b_start = -1
       b_level = 0
@@ -160,6 +195,9 @@ module Discordrb::Commands
       prev
     end
 
+    # Divides the command chain into chain arguments and command chain, then executes them both.
+    # @param event [CommandEvent] The event to execute the command with.
+    # @return [String] the result of the command chain execution.
     def execute(event)
       old_chain = @chain
       @bot.debug 'Executing bare chain'
@@ -181,8 +219,6 @@ module Discordrb::Commands
 
           result = new_result
           # TODO: more chain arguments
-        else
-          # ignore
         end
       end
 

data/lib/discordrb/commands/rate_limiter.rb

@@ -0,0 +1,141 @@
+module Discordrb::Commands
+  # This class represents a bucket for rate limiting - it keeps track of how many requests have been made and when
+  # exactly the user should be rate limited.
+  class Bucket
+    # Makes a new bucket
+    # @param limit [Integer, nil] How many requests the user may perform in the given time_span, or nil if there should be no limit.
+    # @param time_span [Integer, nil] The time span after which the request count is reset, in seconds, or nil if the bucket should never be reset. (If this is nil, limit should be nil too)
+    # @param delay [Integer, nil] The delay for which the user has to wait after performing a request, in seconds, or nil if the user shouldn't have to wait.
+    def initialize(limit, time_span, delay)
+      fail ArgumentError, '`limit` and `time_span` have to either both be set or both be nil!' if !limit != !time_span
+
+      @limit = limit
+      @time_span = time_span
+      @delay = delay
+
+      @bucket = {}
+    end
+
+    # Cleans the bucket, removing all elements that aren't necessary anymore
+    # @param rate_limit_time [Time] The time to base the cleaning on, only useful for testing.
+    def clean(rate_limit_time = nil)
+      rate_limit_time ||= Time.now
+
+      @bucket.delete_if do |_, limit_hash|
+        # Time limit has not run out
+        return false if @time_span && rate_limit_time < (limit_hash[:set_time] + @time_span)
+
+        # Delay has not run out
+        return false if @delay && rate_limit_time < (limit_hash[:last_time] + @delay)
+
+        true
+      end
+    end
+
+    # 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.
+    # @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)
+      key = resolve_key thing
+      limit_hash = @bucket[key]
+
+      # First case: limit_hash doesn't exist yet
+      unless limit_hash
+        @bucket[key] = {
+          last_time: Time.now,
+          set_time: Time.now,
+          count: 1
+        }
+
+        return false
+      end
+
+      # 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 @time_span && rate_limit_time < (limit_hash[:set_time] + @time_span)
+          # 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
+        else
+          # Third case: Count is over the limit but the time has run out
+          # Don't return anything here because there may still be delay-based limiting
+          limit_hash[:set_time] = rate_limit_time
+          limit_hash[:count] = 0
+        end
+      end
+
+      if @delay && rate_limit_time < (limit_hash[:last_time] + @delay)
+        # Fourth case: we're being delayed
+        (limit_hash[:last_time] + @delay) - rate_limit_time
+      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
+        false
+      end
+    end
+
+    private
+
+    def resolve_key(thing)
+      return thing.resolve_id if thing.respond_to?(:resolve_id) && !thing.is_a?(String)
+      return thing if thing.is_a?(Integer) || thing.is_a?(Symbol)
+      fail ArgumentError, "Cannot use a #{thing.class} as a rate limiting key!"
+    end
+  end
+
+  # Represents a collection of {Bucket}s.
+  module RateLimiter
+    # Defines a new bucket for this rate limiter.
+    # @param key [Symbol] The name for this new bucket.
+    # @param attributes [Hash] The attributes to initialize the bucket with.
+    # @option attributes [Integer] :limit The limit of requests to perform in the given time span.
+    # @option attributes [Integer] :time_span How many seconds until the limit should be reset.
+    # @option attributes [Integer] :delay How many seconds the user has to wait after each request.
+    # @see Bucket#initialize
+    # @return [Bucket] the created bucket.
+    def bucket(key, attributes)
+      @buckets ||= {}
+      @buckets[key] = Bucket.new(attributes[:limit], attributes[:time_span], attributes[:delay])
+    end
+
+    # 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.
+    # @see Bucket#rate_limited?
+    # @return [Integer, false] How much time to wait or false if the request succeeded.
+    def rate_limited?(key, thing)
+      # Check whether the bucket actually exists
+      return false unless @buckets && @buckets[key]
+
+      @buckets[key].rate_limited?(thing)
+    end
+
+    # Cleans all buckets
+    # @see Bucket#clean
+    def clean
+      @buckets.each(&:clean)
+    end
+
+    # Adds all the buckets from another RateLimiter onto this one.
+    # @param limiter [Module] Another {RateLimiter} module
+    def include_buckets(limiter)
+      buckets = limiter.instance_variable_get('@buckets') || {}
+      @buckets ||= {}
+      @buckets.merge! buckets
+    end
+  end
+
+  # This class provides a convenient way to do rate-limiting on non-command events.
+  # @see RateLimiter
+  class SimpleRateLimiter
+    include RateLimiter
+
+    # Makes a new rate limiter
+    def initialize
+      @buckets = {}
+    end
+  end
+end