grinch 1.0.0

data/lib/cinch/message_queue.rb

@@ -0,0 +1,107 @@
+# -*- coding: utf-8 -*-
+require "cinch/open_ended_queue"
+
+module Cinch
+  # This class manages all outgoing messages, applying rate throttling
+  # and fair distribution.
+  #
+  # @api private
+  class MessageQueue
+    def initialize(socket, bot)
+      @socket = socket
+      @bot    = bot
+
+      @queues            = {:generic => OpenEndedQueue.new}
+      @queues_to_process = Queue.new
+      @queued_queues     = Set.new
+
+      @mutex = Mutex.new
+
+      @time_since_last_send = nil
+
+      @log = []
+    end
+
+    # @return [void]
+    def queue(message)
+      command, target, _ = message.split(" ", 3)
+
+      queue = nil
+      case command
+      when "PRIVMSG", "NOTICE"
+        @mutex.synchronize do
+          # we are assuming that each message has only one target,
+          # which will be true as long as the user does not send raw
+          # messages.
+          #
+          # this assumption is also reflected in the computation of
+          # passed time and processed messages, since our score does
+          # not take weights into account.
+          queue = @queues[target] ||= OpenEndedQueue.new
+        end
+      else
+        queue = @queues[:generic]
+      end
+      queue << message
+
+      @mutex.synchronize do
+        unless @queued_queues.include?(queue)
+          @queued_queues << queue
+          @queues_to_process << queue
+        end
+      end
+    end
+
+    # @return [void]
+    def process!
+      loop do
+        wait
+        process_one
+      end
+    end
+
+    private
+    def wait
+      if @log.size > 1
+        mps            = @bot.config.messages_per_second || @bot.irc.network.default_messages_per_second
+        max_queue_size = @bot.config.server_queue_size   || @bot.irc.network.default_server_queue_size
+
+        time_passed = @log.last - @log.first
+
+        messages_processed = (time_passed * mps).floor
+        effective_size = @log.size - messages_processed
+
+        if effective_size <= 0
+          @log.clear
+        elsif effective_size >= max_queue_size
+          sleep 1.0/mps
+        end
+      end
+    end
+
+    def process_one
+      queue = @queues_to_process.pop
+      message = queue.pop.to_s.each_line.first.chomp
+
+      if queue.empty?
+        @mutex.synchronize do
+          @queued_queues.delete(queue)
+        end
+      else
+        @queues_to_process << queue
+      end
+
+      begin
+        to_send = Cinch::Utilities::Encoding.encode_outgoing(message, @bot.config.encoding)
+        @socket.write(to_send + "\r\n")
+        @log << Time.now
+        @bot.loggers.outgoing(message)
+
+        @time_since_last_send = Time.now
+      rescue IOError
+        @bot.loggers.error "Could not send message (connectivity problems): #{message}"
+      end
+    end
+
+  end # class MessageQueue
+end

data/lib/cinch/mode_parser.rb

@@ -0,0 +1,76 @@
+require "cinch/exceptions"
+
+module Cinch
+  # @api private
+  # @since 1.1.0
+  module ModeParser
+    ErrEmptyString = "Empty mode string"
+    MalformedError = Struct.new(:modes)
+    EmptySequenceError = Struct.new(:modes)
+    NotEnoughParametersError = Struct.new(:op)
+    TooManyParametersError = Struct.new(:modes, :params)
+
+    # @param [String] modes The mode string as sent by the server
+    # @param [Array<String>] params Parameters belonging to the modes
+    # @param [Hash{:add, :remove => Array<String>}] param_modes
+    #   A mapping describing which modes require parameters
+    # @return [(Array<(Symbol<:add, :remove>, String<char>, String<param>), foo)]
+    def self.parse_modes(modes, params, param_modes = {})
+      if modes.size == 0
+        return nil, ErrEmptyString
+        # raise Exceptions::InvalidModeString, 'Empty mode string'
+      end
+
+      if modes[0] !~ /[+-]/
+        return nil, MalformedError.new(modes)
+        # raise Exceptions::InvalidModeString, "Malformed modes string: %s" % modes
+      end
+
+      changes = []
+
+      direction = nil
+      count = -1
+
+      modes.each_char do |ch|
+        if ch =~ /[+-]/
+          if count == 0
+            return changes, EmptySequenceError.new(modes)
+            # raise Exceptions::InvalidModeString, 'Empty mode sequence: %s' % modes
+          end
+
+          direction = case ch
+                      when "+"
+                        :add
+                      when "-"
+                        :remove
+                      end
+          count = 0
+        else
+          param = nil
+          if param_modes.has_key?(direction) && param_modes[direction].include?(ch)
+            if params.size > 0
+              param = params.shift
+            else
+              return changes, NotEnoughParametersError.new(ch)
+              # raise Exceptions::InvalidModeString, 'Not enough parameters: %s' % ch.inspect
+            end
+          end
+          changes << [direction, ch, param]
+          count += 1
+        end
+      end
+
+      if params.size > 0
+        return changes, TooManyParametersError.new(modes, params)
+        # raise Exceptions::InvalidModeString, 'Too many parameters: %s %s' % [modes, params]
+      end
+
+      if count == 0
+        return changes, EmptySequenceError.new(modes)
+        # raise Exceptions::InvalidModeString, 'Empty mode sequence: %s' % modes
+      end
+
+      return changes, nil
+    end
+  end
+end

data/lib/cinch/network.rb

@@ -0,0 +1,104 @@
+module Cinch
+  # This class allows querying the IRC network for its name and used
+  # server software as well as certain non-standard behaviour.
+  #
+  # @since 2.0.0
+  class Network
+    # @return [Symbol] The name of the network. `:unknown` if the
+    #   network couldn't be detected.
+    attr_reader :name
+
+    # @api private
+    attr_writer :name
+
+    # @return [Symbol] The server software used by the network.
+    #   `:unknown` if the software couldn't be detected.
+    attr_reader :ircd
+
+    # @api private
+    attr_writer :ircd
+
+    # @return [Array<Symbol>] All client capabilities supported by the
+    # network.
+    attr_reader :capabilities
+
+    # @api private
+    attr_writer :capabilities
+
+    # @param [Symbol] name
+    # @param [Symbol] ircd
+    # @api private
+    # @note The user should not create instances of this class but use
+    #   {IRC#network} instead.
+    def initialize(name, ircd)
+      @name         = name
+      @ircd         = ircd
+      @capabilities = []
+    end
+
+    # @return [String, nil] The mode used for getting the list of
+    #   channel owners, if any
+    def owner_list_mode
+      return "q" if @ircd == :unreal || @ircd == :inspircd
+    end
+
+    # @return [String, nil] The mode used for getting the list of
+    #   channel quiets, if any
+    def quiet_list_mode
+      return "q" if @ircd == :"ircd-seven"
+    end
+
+    # @return [Boolean] Does WHOIS only support one argument?
+    def whois_only_one_argument?
+      @name == :jtv
+    end
+
+    # @return [Boolean] True if connected to NgameTV
+    def ngametv?
+      @name == :ngametv
+    end
+
+    # @return [Boolean] True if connected to JTV
+    def jtv?
+      @name == :jtv
+    end
+
+    # @return [Boolean] True if we do not know which network we are
+    #   connected to
+    def unknown_network?
+      @name == :unknown
+    end
+
+    # @return [Boolean] True if we do not know which software the
+    #   server is running
+    def unknown_ircd?
+      @ircd == :unknown
+    end
+
+    # Note for the default_* methods: Always make sure to return a
+    # value for when no network/ircd was detected so that MessageQueue
+    # doesn't break.
+
+    # @return [Numeric] The `messages per second` value that best suits
+    #   the current network
+    def default_messages_per_second
+      case @name
+      when :freenode
+        0.7
+      else
+        0.5
+      end
+    end
+
+    # @return [Integer] The `server queue size` value that best suits
+    #   the current network
+    def default_server_queue_size
+      case @name
+      when :quakenet
+        40
+      else
+        10
+      end
+    end
+  end
+end

data/lib/cinch/open_ended_queue.rb

@@ -0,0 +1,26 @@
+require "thread"
+
+# Like Ruby's Queue class, but allowing both pushing and unshifting
+# objects.
+#
+# @api private
+class OpenEndedQueue < Queue
+  # @param [Object] obj
+  # @return [void]
+  def unshift(obj)
+    t = nil
+    @mutex.synchronize{
+      @que.unshift obj
+      begin
+        t = @waiting.shift
+        t.wakeup if t
+      rescue ThreadError
+        retry
+      end
+    }
+    begin
+      t.run if t
+    rescue ThreadError
+    end
+  end
+end

data/lib/cinch/pattern.rb

@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+module Cinch
+  # @api private
+  # @since 1.1.0
+  class Pattern
+    # @param [String, Regexp, NilClass, Proc, #to_s] obj The object to
+    #   convert to a regexp
+    # @return [Regexp, nil]
+    def self.obj_to_r(obj, anchor = nil)
+      case obj
+      when Regexp, NilClass
+        return obj
+      else
+        escaped = Regexp.escape(obj.to_s)
+        case anchor
+        when :start
+          return Regexp.new("^" + escaped)
+        when :end
+          return Regexp.new(escaped + "$")
+        when nil
+          return Regexp.new(Regexp.escape(obj.to_s))
+        end
+      end
+    end
+
+    def self.resolve_proc(obj, msg = nil)
+      if obj.is_a?(Proc)
+        return resolve_proc(obj.call(msg), msg)
+      else
+        return obj
+      end
+    end
+
+    def self.generate(type, argument)
+      case type
+      when :ctcp
+        Pattern.new(/^/, /#{Regexp.escape(argument.to_s)}(?:$| .+)/, nil)
+      else
+        raise ArgumentError, "Unsupported type: #{type.inspect}"
+      end
+    end
+
+    attr_reader :prefix
+    attr_reader :suffix
+    attr_reader :pattern
+    def initialize(prefix, pattern, suffix)
+      @prefix, @pattern, @suffix = prefix, pattern, suffix
+    end
+
+    def to_r(msg = nil)
+      pattern = Pattern.resolve_proc(@pattern, msg)
+
+      case pattern
+      when Regexp, NilClass
+        prefix  = Pattern.obj_to_r(Pattern.resolve_proc(@prefix, msg), :start)
+        suffix  = Pattern.obj_to_r(Pattern.resolve_proc(@suffix, msg), :end)
+        /#{prefix}#{pattern}#{suffix}/
+      else
+        prefix  = Pattern.obj_to_r(Pattern.resolve_proc(@prefix, msg))
+        suffix  = Pattern.obj_to_r(Pattern.resolve_proc(@suffix, msg))
+        /^#{prefix}#{Pattern.obj_to_r(pattern)}#{suffix}$/
+      end
+    end
+  end
+end

data/lib/cinch/plugin.rb

@@ -0,0 +1,515 @@
+require "cinch/helpers"
+
+module Cinch
+  # This class represents the core of the plugin functionality of
+  # Cinch. It provides both the methods for users to write their own
+  # plugins as well as for the Cinch framework to use them.
+  #
+  # The {ClassMethods} module, which will get included automatically
+  # in all classes that include `Cinch::Plugin`, includes all class
+  # methods that the user will use for creating plugins.
+  #
+  # Most of the instance methods are for use by the Cinch framework
+  # and part of the private API, but some will also be used by plugin
+  # authors, mainly {#config}, {#synchronize} and {#bot}.
+  module Plugin
+    include Helpers
+
+    # The ClassMethods module includes all methods that the user will
+    # need for creating plugins for the Cinch framework: Setting
+    # options (see {#set} and the attributes) as well as methods for
+    # configuring the actual pattern matching ({#match}, {#listen_to}).
+    #
+    # Furthermore, the attributes allow for programmatically
+    # inspecting plugins.
+    #
+    # @attr plugin_name
+    module ClassMethods
+      # @return [Hash{:pre, :post => Array<Hook>}] All hooks
+      attr_reader :hooks
+
+      # @return [Array<:message, :channel, :private>] The list of events to react on
+      attr_accessor :react_on
+
+      # The name of the plugin.
+      # @overload plugin_name
+      #   @return [String, nil]
+      # @overload plugin_name=(new_name)
+      #   @param [String, nil] new_name
+      #   @return [String]
+      # @return [String, nil] The name of the plugin
+      attr_reader :plugin_name
+
+      # @return [String]
+      def plugin_name=(new_name)
+        if new_name.nil? && self.name
+          @plugin_name = self.name.split("::").last.downcase
+        else
+          @plugin_name = new_name
+        end
+      end
+
+      # @return [Array<Matcher>] All matchers
+      attr_reader   :matchers
+
+      # @return [Array<Listener>] All listeners
+      attr_reader   :listeners
+
+      # @return [Array<Timer>] All timers
+      attr_reader   :timers
+
+      # @return [Array<String>] All CTCPs
+      attr_reader   :ctcps
+
+      # @return [String, nil] The help message
+      attr_accessor :help
+
+      # @return [String, Regexp, Proc] The prefix
+      attr_accessor :prefix
+
+      # @return [String, Regexp, Proc] The suffix
+      attr_accessor :suffix
+
+      # @return [Array<Symbol>] Required plugin options
+      attr_accessor :required_options
+
+      # Represents a Matcher as created by {#match}.
+      #
+      # @attr [String, Regexp, Proc] pattern
+      # @attr [Boolean] use_prefix
+      # @attr [Boolean] use_suffix
+      # @attr [Symbol] method
+      # @attr [Symbol] group
+      Matcher = Struct.new(:pattern,
+                           :use_prefix,
+                           :use_suffix,
+                           :method,
+                           :group,
+                           :prefix,
+                           :suffix,
+                           :react_on,
+                           :strip_colors)
+
+      # Represents a Listener as created by {#listen_to}.
+      #
+      # @attr [Symbol] event
+      # @attr [Symbol] method
+      Listener = Struct.new(:event, :method)
+
+      # Represents a Timer as created by {#timer}.
+      #
+      # @note This is not the same as a {Cinch::Timer} object, which
+      #   will allow controlling and inspecting actually running
+      #   timers. This class only describes a Timer that still has to
+      #   be created.
+      #
+      # @attr [Numeric] interval
+      # @attr [Symbol] method
+      # @attr [Hash] options
+      # @attr [Boolean] registered
+      Timer = Struct.new(:interval, :options, :registered)
+
+      # Represents a Hook as created by {#hook}.
+      #
+      # @attr [Symbol] type
+      # @attr [Array<Symbol>] for
+      # @attr [Symbol] method
+      Hook = Struct.new(:type, :for, :method, :group)
+
+      # @api private
+      def self.extended(by)
+        by.instance_exec do
+          @matchers         = []
+          @ctcps            = []
+          @listeners        = []
+          @timers           = []
+          @help             = nil
+          @hooks            = Hash.new{|h, k| h[k] = []}
+          @prefix           = nil
+          @suffix           = nil
+          @react_on         = :message
+          @required_options = []
+          self.plugin_name  = nil
+        end
+      end
+
+      # Set options.
+      #
+      # Available options:
+      #
+      #   - {#help}
+      #   - {#plugin_name}
+      #   - {#prefix}
+      #   - {#react_on}
+      #   - {#required_options}
+      #   - {#suffix}
+      #
+      # @overload set(key, value)
+      #   @param [Symbol] key The option's name
+      #   @param [Object] value
+      #   @return [void]
+      # @overload set(options)
+      #   @param [Hash{Symbol => Object}] options The options, as key => value associations
+      #   @return [void]
+      #   @example
+      #     set(:help   => "the help message",
+      #         :prefix => "^")
+      # @return [void]
+      # @since 2.0.0
+      def set(*args)
+        case args.size
+        when 1
+          # {:key => value, ...}
+          args.first.each do |key, value|
+            self.send("#{key}=", value)
+          end
+        when 2
+          # key, value
+          self.send("#{args.first}=", args.last)
+        else
+          raise ArgumentError # TODO proper error message
+        end
+      end
+
+      # Set a match pattern.
+      #
+      # @param [Regexp, String] pattern A pattern
+      # @option options [Symbol] :method (:execute) The method to execute
+      # @option options [Boolean] :use_prefix (true) If true, the
+      #   plugin prefix will automatically be prepended to the
+      #   pattern.
+      # @option options [Boolean] :use_suffix (true) If true, the
+      #   plugin suffix will automatically be appended to the
+      #   pattern.
+      # @option options [String, Regexp, Proc] prefix (nil) A prefix
+      #   overwriting the per-plugin prefix.
+      # @option options [String, Regexp, Proc] suffix (nil) A suffix
+      #   overwriting the per-plugin suffix.
+      # @option options [Symbol, Fixnum] react_on (:message) The
+      #   {file:docs/events.md event} to react on.
+      # @option options [Symbol] :group (nil) The group the match belongs to.
+      # @option options [Boolean] :strip_colors (false) Strip colors
+      #   from message before attempting match
+      # @return [Matcher]
+      # @todo Document match/listener grouping
+      def match(pattern, options = {})
+        options = {
+          :use_prefix => true,
+          :use_suffix => true,
+          :method => :execute,
+          :group => nil,
+          :prefix => nil,
+          :suffix => nil,
+          :react_on => nil,
+          :strip_colors => false,
+        }.merge(options)
+        if options[:react_on]
+          options[:react_on] = options[:react_on].to_s.to_sym
+        end
+        matcher = Matcher.new(pattern, *options.values_at(:use_prefix,
+                                                          :use_suffix,
+                                                          :method,
+                                                          :group,
+                                                          :prefix,
+                                                          :suffix,
+                                                          :react_on,
+                                                          :strip_colors))
+        @matchers << matcher
+
+        matcher
+      end
+
+      # Events to listen to.
+      # @overload listen_to(*types, options = {})
+      #   @param [String, Symbol, Integer] *types Events to listen to. Available
+      #     events are all IRC commands in lowercase as symbols, all numeric
+      #     replies and all events listed in the {file:docs/events.md list of events}.
+      #   @param [Hash] options
+      #   @option options [Symbol] :method (:listen) The method to
+      #     execute
+      #   @return [Array<Listener>]
+      def listen_to(*types)
+        options = {:method => :listen}
+        if types.last.is_a?(Hash)
+          options.merge!(types.pop)
+        end
+
+        listeners = types.map {|type| Listener.new(type.to_s.to_sym, options[:method])}
+        @listeners.concat listeners
+
+        listeners
+      end
+
+      # @version 1.1.1
+      def ctcp(command)
+        @ctcps << command.to_s.upcase
+      end
+
+      # @example
+      #   timer 5, method: :some_method
+      #   def some_method
+      #     Channel("#cinch-bots").send(Time.now.to_s)
+      #   end
+      #
+      # @param [Numeric] interval Interval in seconds
+      # @option options [Symbol] :method (:timer) Method to call (only
+      #   if no proc is provided)
+      # @option options [Integer] :shots (Float::INFINITY) How often
+      #   should the timer fire?
+      # @option options [Boolean] :threaded (true) Call method in a
+      #   thread?
+      # @option options [Boolean] :start_automatically (true) If true,
+      #   the timer will automatically start after the bot finished
+      #   connecting.
+      # @option options [Boolean] :stop_automaticall (true) If true,
+      #   the timer will automatically stop when the bot disconnects.
+      # @return [Timer]
+      # @since 1.1.0
+      def timer(interval, options = {})
+        options = {:method => :timer, :threaded => true}.merge(options)
+        timer = Timer.new(interval, options, false)
+        @timers << timer
+
+        timer
+      end
+
+      # Defines a hook which will be run before or after a handler is
+      # executed, depending on the value of `type`.
+      #
+      # @param [:pre, :post] type Run the hook before or after
+      #   a handler?
+      # @option options [Array<:match, :listen_to, :ctcp>] :for ([:match, :listen_to, :ctcp])
+      #   Which kinds of events to run the hook for.
+      # @option options [Symbol] :method (:hook) The method to execute.
+      # @option options [Symbol] :group (nil) The match group to
+      #   execute the hook for. Hooks belonging to the `nil` group
+      #   will execute for all matches.
+      # @return [Hook]
+      # @since 1.1.0
+      def hook(type, options = {})
+        options = {:for => [:match, :listen_to, :ctcp], :method => :hook, :group => nil}.merge(options)
+        hook = Hook.new(type, options[:for], options[:method], options[:group])
+        __hooks(type) << hook
+
+        hook
+      end
+
+      # @return [Hash]
+      # @api private
+      def __hooks(type = nil, events = nil, group = nil)
+        if type.nil?
+          hooks = @hooks
+        else
+          hooks = @hooks[type]
+        end
+
+        if events.nil?
+          return hooks
+        else
+          events = [*events]
+          if hooks.is_a?(Hash)
+            hooks = hooks.map { |k, v| v }
+          end
+          hooks = hooks.select { |hook| (events & hook.for).size > 0 }
+        end
+
+        return hooks.select { |hook| hook.group.nil? || hook.group == group }
+      end
+
+      # @return [Boolean] True if processing should continue
+      # @api private
+      def call_hooks(type, event, group, instance, args)
+        stop = __hooks(type, event, group).find { |hook|
+          # stop after the first hook that returns false
+          if hook.method.respond_to?(:call)
+            instance.instance_exec(*args, &hook.method) == false
+          else
+            instance.__send__(hook.method, *args) == false
+          end
+        }
+
+        !stop
+      end
+
+      # @param [Bot] bot
+      # @return [Array<Symbol>, nil]
+      # @since 2.0.0
+      # @api private
+      def check_for_missing_options(bot)
+        @required_options.select { |option|
+          !bot.config.plugins.options[self].has_key?(option)
+        }
+      end
+    end
+
+    def __register_listeners
+      self.class.listeners.each do |listener|
+        @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Registering listener for type `#{listener.event}`"
+        new_handler = Handler.new(@bot, listener.event, Pattern.new(nil, //, nil)) do |message, *args|
+          if self.class.call_hooks(:pre, :listen_to, nil, self, [message])
+            __send__(listener.method, message, *args)
+            self.class.call_hooks(:post, :listen_to, nil, self, [message])
+          else
+            @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Dropping message due to hook"
+          end
+        end
+
+        @handlers << new_handler
+        @bot.handlers.register(new_handler)
+      end
+    end
+    private :__register_listeners
+
+    def __register_ctcps
+      self.class.ctcps.each do |ctcp|
+        @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Registering CTCP `#{ctcp}`"
+        new_handler = Handler.new(@bot, :ctcp, Pattern.generate(:ctcp, ctcp)) do |message, *args|
+          if self.class.call_hooks(:pre, :ctcp, nil, self, [message])
+            __send__("ctcp_#{ctcp.downcase}", message, *args)
+            self.class.call_hooks(:post, :ctcp, nil, self, [message])
+          else
+            @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Dropping message due to hook"
+          end
+        end
+
+        @handlers << new_handler
+        @bot.handlers.register(new_handler)
+      end
+    end
+    private :__register_ctcps
+
+    def __register_timers
+      @timers = self.class.timers.map {|timer_struct|
+        @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Registering timer with interval `#{timer_struct.interval}` for method `#{timer_struct.options[:method]}`"
+
+        block = self.method(timer_struct.options[:method])
+        options = timer_struct.options.merge(interval: timer_struct.interval)
+        Cinch::Timer.new(@bot, options, &block)
+      }
+    end
+    private :__register_timers
+
+    def __register_matchers
+      prefix = self.class.prefix || @bot.config.plugins.prefix
+      suffix = self.class.suffix || @bot.config.plugins.suffix
+
+      self.class.matchers.each do |matcher|
+        _prefix = matcher.use_prefix ? matcher.prefix || prefix : nil
+        _suffix = matcher.use_suffix ? matcher.suffix || suffix : nil
+
+        pattern_to_register = Pattern.new(_prefix, matcher.pattern, _suffix)
+        react_on = matcher.react_on || self.class.react_on || :message
+
+        @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Registering executor with pattern `#{pattern_to_register.inspect}`, reacting on `#{react_on}`"
+
+        new_handler = Handler.new(@bot,
+                                  react_on,
+                                  pattern_to_register,
+                                  group: matcher.group,
+                                  strip_colors: matcher.strip_colors) do |message, *args|
+          method = method(matcher.method)
+          arity = method.arity - 1
+          if arity > 0
+            args = args[0..arity - 1]
+          elsif arity == 0
+            args = []
+          end
+          if self.class.call_hooks(:pre, :match, matcher.group, self, [message])
+            method.call(message, *args)
+            self.class.call_hooks(:post, :match, matcher.group, self, [message])
+          else
+            @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Dropping message due to hook"
+          end
+        end
+        @handlers << new_handler
+        @bot.handlers.register(new_handler)
+      end
+    end
+    private :__register_matchers
+
+    def __register_help
+      prefix = self.class.prefix || @bot.config.plugins.prefix
+      suffix = self.class.suffix || @bot.config.plugins.suffix
+      if self.class.help
+        @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Registering help message"
+        help_pattern = Pattern.new(prefix, "help #{self.class.plugin_name}", suffix)
+        new_handler = Handler.new(@bot, :message, help_pattern) do |message|
+          message.reply(self.class.help)
+        end
+
+        @handlers << new_handler
+        @bot.handlers.register(new_handler)
+      end
+    end
+    private :__register_help
+
+    # @return [void]
+    # @api private
+    def __register
+      missing = self.class.check_for_missing_options(@bot)
+      unless missing.empty?
+        @bot.loggers.warn "[plugin] #{self.class.plugin_name}: Could not register plugin because the following options are not set: #{missing.join(", ")}"
+        return
+      end
+
+      __register_listeners
+      __register_matchers
+      __register_ctcps
+      __register_timers
+      __register_help
+    end
+
+    # @return [Bot]
+    attr_reader :bot
+
+    # @return [Array<Handler>] handlers
+    attr_reader :handlers
+
+    # @return [Array<Cinch::Timer>]
+    attr_reader :timers
+
+    # @api private
+    def initialize(bot)
+      @bot = bot
+      @handlers = []
+      @timers   = []
+      __register
+    end
+
+    # @since 2.0.0
+    def unregister
+      @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Unloading plugin"
+      @timers.each do |timer|
+        timer.stop
+      end
+
+      handlers.each do |handler|
+        handler.stop
+        handler.unregister
+      end
+    end
+
+    # (see Bot#synchronize)
+    def synchronize(name, &block)
+      @bot.synchronize(name, &block)
+    end
+
+    # Provides access to plugin-specific options.
+    #
+    # @return [Hash] A hash of options
+    def config
+      @bot.config.plugins.options[self.class] || {}
+    end
+
+    def shared
+      @bot.config.shared
+    end
+
+    # @api private
+    def self.included(by)
+      by.extend ClassMethods
+    end
+  end
+end
+
+# TODO more details in "message dropped" debug output