onyxcord 1.1.0

data/lib/onyxcord/commands/parser.rb

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+
+module OnyxCord::Commands
+  # Command that can be called in a chain
+  class Command
+    # @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 = {
+        # The lowest permission level that can use the command
+        permission_level: attributes[:permission_level] || 0,
+
+        # Message to display when a user does not have sufficient permissions to execute a command
+        permission_message: attributes[:permission_message].is_a?(FalseClass) ? nil : (attributes[:permission_message] || "You don't have permission to execute command %name%!"),
+
+        # Discord action permissions required to use this command
+        required_permissions: attributes[:required_permissions] || [],
+
+        # 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,
+
+        # Whether this command is usable in a command chain
+        chain_usable: attributes[:chain_usable].nil? || attributes[:chain_usable],
+
+        # Whether this command should show up in the help command
+        help_available: attributes[:help_available].nil? || attributes[:help_available],
+
+        # Description (for help command)
+        description: attributes[:description] || nil,
+
+        # Usage description (for help command and error messages)
+        usage: attributes[:usage] || nil,
+
+        # Array of arguments (for type-checking)
+        arg_types: attributes[:arg_types] || nil,
+
+        # Parameter list (for help command and error messages)
+        parameters: attributes[:parameters] || nil,
+
+        # Minimum number of arguments
+        min_args: attributes[:min_args] || 0,
+
+        # Maximum number of arguments (-1 for no limit)
+        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 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
+    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.
+    # @param check_permissions [true, false] Whether the user's permission to execute the command (i.e. rate limits)
+    #   should be checked.
+    # @return [String] the result of the execution.
+    def call(event, arguments, chained = false, check_permissions = true)
+      if arguments.length < @attributes[:min_args]
+        response = "Too few arguments for command `#{name}`!"
+        response += "\nUsage: `#{@attributes[:usage]}`" if @attributes[:usage]
+        event.respond(response)
+        return
+      end
+      if @attributes[:max_args] >= 0 && arguments.length > @attributes[:max_args]
+        response = "Too many arguments for command `#{name}`!"
+        response += "\nUsage: `#{@attributes[:usage]}`" if @attributes[:usage]
+        event.respond(response)
+        return
+      end
+      unless @attributes[:chain_usable] && !chained
+        event.respond "Command `#{name}` cannot be used in a command chain!"
+        return
+      end
+
+      if check_permissions
+        rate_limited = event.bot.rate_limited?(@attributes[:bucket], event.author)
+        if @attributes[:bucket] && rate_limited
+          event.respond @attributes[:rate_limit_message].gsub('%time%', rate_limited.round(2).to_s) if @attributes[:rate_limit_message]
+          return
+        end
+      end
+
+      result = @block.call(event, *arguments)
+      event.drain_into(result)
+    rescue LocalJumpError => e # occurs when breaking
+      result = e.exit_value
+      event.drain_into(result)
+    rescue StandardError => e # Something went wrong inside our @block!
+      rescue_value = @attributes[:rescue] || event.bot.attributes[:rescue]
+      if rescue_value
+        event.respond(rescue_value.gsub('%exception%', e.message)) if rescue_value.is_a?(String)
+        rescue_value.call(event, e) if rescue_value.respond_to?(:call)
+      end
+
+      raise e
+    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
+
+  # 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
+      @bot = bot
+      @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
+      result = ''
+      quoted = false
+      escaped = false
+      hacky_delim, hacky_space, hacky_prev, hacky_newline = [0xe001, 0xe002, 0xe003, 0xe004].pack('U*').chars
+
+      @chain.each_char.with_index do |char, index|
+        # Escape character
+        if char == '\\' && !escaped
+          escaped = true
+          next
+        elsif escaped && b_level <= 0
+          result += char
+          escaped = false
+          next
+        end
+
+        if quoted
+          # Quote end
+          if char == @attributes[:quote_end]
+            quoted = false
+            next
+          end
+
+          if b_level <= 0
+            case char
+            when @attributes[:chain_delimiter]
+              result += hacky_delim
+              next
+            when @attributes[:previous]
+              result += hacky_prev
+              next
+            when ' '
+              result += hacky_space
+              next
+            when "\n"
+              result += hacky_newline
+              next
+            end
+          end
+        else
+          case char
+          when @attributes[:quote_start] # Quote begin
+            quoted = true
+            next
+          when @attributes[:sub_chain_start]
+            b_start = index if b_level.zero?
+            b_level += 1
+          end
+        end
+
+        result += char if b_level <= 0
+
+        next unless char == @attributes[:sub_chain_end] && !quoted
+
+        b_level -= 1
+        next unless b_level.zero?
+
+        nested = @chain[(b_start + 1)..(index - 1)]
+        subchain = CommandChain.new(nested, @bot, true)
+        result += subchain.execute(event)
+      end
+
+      event.respond("Your subchains are mismatched! Make sure you don't have any extra #{@attributes[:sub_chain_start]}'s or #{@attributes[:sub_chain_end]}'s") unless b_level.zero?
+
+      @chain = result
+
+      @chain_args, @chain = divide_chain(@chain)
+
+      prev = ''
+
+      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 !@attributes[:chain_delimiter].empty? && chain_to_split.start_with?(@attributes[:chain_delimiter])
+
+      first = true
+      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
+
+        command = command.strip
+
+        # Replace the hacky delimiter that was used inside quotes with actual delimiters
+        command = command.gsub hacky_delim, @attributes[:chain_delimiter]
+
+        first_space = command.index ' '
+        command_name = first_space ? command[0..(first_space - 1)] : command
+        arguments = first_space ? command[(first_space + 1)..] : ''
+
+        # Append a previous sign if none is present
+        arguments += @attributes[:previous] unless arguments.include? @attributes[:previous]
+        arguments = arguments.gsub @attributes[:previous], prev
+
+        # Replace hacky previous signs with actual ones
+        arguments = arguments.gsub hacky_prev, @attributes[:previous]
+
+        arguments = arguments.split ' '
+
+        # Replace the hacky spaces/newlines with actual ones
+        arguments.map! do |elem|
+          elem.gsub(hacky_space, ' ').gsub(hacky_newline, "\n")
+        end
+
+        # 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
+    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'
+      result = execute_bare(event)
+
+      @chain_args ||= []
+
+      @bot.debug "Found chain args #{@chain_args}, preliminary result #{result}"
+
+      @chain_args.each do |arg|
+        case arg.first
+        when 'repeat'
+          new_result = ''
+          executed_chain = divide_chain(old_chain).last
+
+          arg[1].to_i.times do
+            chain_result = CommandChain.new(executed_chain, @bot).execute(event)
+            new_result += chain_result if chain_result
+          end
+
+          result = new_result
+          # TODO: more chain arguments
+        end
+      end
+
+      result
+    end
+
+    private
+
+    def divide_chain(chain)
+      chain_args_index = chain.index(@attributes[:chain_args_delim]) unless @attributes[:chain_args_delim].empty?
+      chain_args = []
+
+      if chain_args_index
+        chain_args = chain[0..chain_args_index].split ','
+
+        # Split up the arguments
+
+        chain_args.map! do |arg|
+          arg.split ' '
+        end
+
+        chain = chain[(chain_args_index + 1)..]
+      end
+
+      [chain_args, chain]
+    end
+  end
+end

data/lib/onyxcord/commands/rate_limiter.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module OnyxCord::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)
+      raise 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 [String, 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, increment: 1)
+      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: increment
+        }
+
+        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] + 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)
+
+        # 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
+
+      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] += increment
+        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)
+
+      raise 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 [String, 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, increment: 1)
+      # Check whether the bucket actually exists
+      return false unless @buckets && @buckets[key]
+
+      @buckets[key].rate_limited?(thing, increment: increment)
+    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

data/lib/onyxcord/configuration.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+# Top-level namespace for the OnyxCord Discord framework.
+module OnyxCord
+  # Runtime defaults for OnyxCord bots.
+  class Configuration
+    MODES = %i[raw hybrid object].freeze
+    EXECUTORS = %i[pool inline].freeze
+
+    CACHE_PRESETS = {
+      none: {
+        users: false,
+        voice_regions: false,
+        servers: false,
+        channels: false,
+        pm_channels: false,
+        thread_members: false,
+        server_previews: false,
+        members: false,
+        messages: false
+      },
+      minimal: {
+        users: false,
+        voice_regions: false,
+        servers: true,
+        channels: true,
+        pm_channels: false,
+        thread_members: false,
+        server_previews: false,
+        members: false,
+        messages: false
+      },
+      full: {
+        users: true,
+        voice_regions: true,
+        servers: true,
+        channels: true,
+        pm_channels: true,
+        thread_members: true,
+        server_previews: true,
+        members: true,
+        messages: true
+      }
+    }.freeze
+
+    attr_accessor :mode, :cache, :event_executor, :event_workers
+
+    def initialize
+      @mode = :raw
+      @cache = :none
+      @event_executor = :pool
+      @event_workers = 4
+    end
+
+    def dup
+      copy = self.class.new
+      copy.mode = @mode
+      copy.cache = @cache.is_a?(Hash) ? @cache.dup : @cache
+      copy.event_executor = @event_executor
+      copy.event_workers = @event_workers
+      copy
+    end
+
+    def normalize_mode(value = @mode)
+      mode = (value || @mode).to_sym
+      return mode if MODES.include?(mode)
+
+      raise ArgumentError, "Unknown OnyxCord mode: #{value.inspect}"
+    end
+
+    def normalize_event_executor(value = @event_executor)
+      executor = (value || @event_executor).to_sym
+      return executor if EXECUTORS.include?(executor)
+
+      raise ArgumentError, "Unknown event executor: #{value.inspect}"
+    end
+
+    def normalize_event_workers(value = @event_workers)
+      workers = Integer(value || @event_workers)
+      raise ArgumentError, 'event_workers must be greater than zero' unless workers.positive?
+
+      workers
+    end
+
+    def normalize_cache(value = @cache)
+      cache = value.nil? ? @cache : value
+
+      case cache
+      when Hash
+        CACHE_PRESETS[:none].merge(cache.transform_keys(&:to_sym))
+      else
+        preset = cache.to_sym
+        raise ArgumentError, "Unknown cache preset: #{cache.inspect}" unless CACHE_PRESETS[preset]
+
+        CACHE_PRESETS[preset].dup
+      end
+    end
+
+    class << self
+      def current
+        @current ||= new
+      end
+
+      def configure
+        yield current
+      end
+
+      def reset!
+        @current = new
+      end
+    end
+  end
+
+  def self.configuration
+    Configuration.current
+  end
+
+  def self.configure(&block)
+    Configuration.configure(&block)
+  end
+
+  def self.reset_configuration!
+    Configuration.reset!
+  end
+end