cinch 1.1.3 → 2.0.0.pre.1

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
+    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 [Number] The `messages per second` value that best suits
+    #   the current network
+    def default_messages_per_second
+      case @network
+      when :freenode
+        0.7
+      else
+        0.5
+      end
+    end
+
+    # @return [Number] The `server queue size` value that best suits
+    #   the current network
+    def default_server_queue_size
+      case @network
+      when :quakenet
+        40
+      else
+        10
+      end
+    end
+  end
+end

data/lib/cinch/{rubyext/queue.rb → open_ended_queue.rb}

@@ -1,5 +1,12 @@
 require "thread"
-class Queue
+
+# 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{

data/lib/cinch/pattern.rb

@@ -1,16 +1,25 @@
 # -*- 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)
+    def self.obj_to_r(obj, anchor = nil)
       case obj
       when Regexp, NilClass
         return obj
       else
-        return Regexp.new(Regexp.escape(obj.to_s))
+        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
 
@@ -22,6 +31,15 @@ module Cinch
       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
@@ -30,14 +48,16 @@ module Cinch
     end
 
     def to_r(msg = nil)
-      prefix  = Pattern.obj_to_r(Pattern.resolve_proc(@prefix, msg))
-      suffix  = Pattern.obj_to_r(Pattern.resolve_proc(@suffix, msg))
       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

data/lib/cinch/plugin.rb

@@ -1,17 +1,167 @@
+# TODO more details in "message dropped" debug output
 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}, {#storage} 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
-      # @api private
-      Match = Struct.new(:pattern, :use_prefix, :use_suffix, :method)
-      # @api private
+      # @return [Hash<Symbol<:pre, :post> => Array<Hook>>] All hooks
+      attr_reader :hooks
+
+      # @return [Array<Symbol<:message, :channel, :private>>] The list of events to react on
+      attr_accessor :reacting_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, :reacting_on)
+
+      # Represents a Listener as created by {#listen_to}.
+      #
+      # @attr [Symbol] event
+      # @attr [Symbol] method
       Listener = Struct.new(:event, :method)
-      # @api private
-      Timer = Struct.new(:interval, :method, :threaded, :registered)
-      # @api private
+
+      # 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 [Number] 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)
 
+      # @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
+          @reacting_on      = :message
+          @required_options = []
+          self.plugin_name  = nil
+        end
+      end
+
+      # Set options.
+      #
+      # Available options:
+      #
+      #   - {#help}
+      #   - {#plugin_name}
+      #   - {#prefix}
+      #   - {#reacting_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
@@ -19,11 +169,19 @@ module Cinch
       # @option options [Boolean] :use_prefix (true) If true, the
       #   plugin prefix will automatically be prepended to the
       #   pattern.
-      # @return [void]
+      # @option options [Boolean] :use_suffix (true) If true, the
+      #   plugin suffix will automatically be appended to the
+      #   pattern.
+      # @option options [Symbol] :group (nil) The group the match belongs to.
+      # @return [Matcher]
+      # @todo Document match/listener grouping
+      # @todo document new options
       def match(pattern, options = {})
-        options = {:use_prefix => true, :use_suffix => true, :method => :execute}.merge(options)
-        @__cinch_matches ||= []
-        @__cinch_matches << Match.new(pattern, options[:use_prefix], options[:use_suffix], options[:method])
+        options = {:use_prefix => true, :use_suffix => true, :method => :execute, :group => nil, :prefix => nil, :suffix => nil, :reacting_on => nil}.merge(options)
+        matcher = Matcher.new(pattern, *options.values_at(:use_prefix, :use_suffix, :method, :group, :prefix, :suffix, :reacting_on))
+        @matchers << matcher
+
+        matcher
       end
 
       # Events to listen to.
@@ -37,72 +195,34 @@ module Cinch
       #       - :message (both channel and private messages)
       #       - :error   (IRC errors)
       #       - :ctcp    (ctcp requests)
+      #       - :action  (actions, aka /me)
       #
       #   @param [Hash] options
       #   @option options [Symbol] :method (:listen) The method to
       #     execute
-      #   @return [void]
+      #   @return [Array<Listener]
       def listen_to(*types)
         options = {:method => :listen}
         if types.last.is_a?(Hash)
           options.merge!(types.pop)
         end
 
-        @__cinch_listeners ||= []
+        listeners = types.map {|type| Listener.new(type, options[:method])}
+        @listeners.concat listeners
 
-        types.each do |type|
-          @__cinch_listeners << Listener.new(type, options[:method])
-        end
+        listeners
       end
 
+      # @version 1.1.1
       def ctcp(command)
-        (@__cinch_ctcps ||= []) << command.to_s.upcase
-      end
-
-      # Define a help message which will be returned on "&lt;prefix&gt;help
-      # &lt;pluginname&gt;".
-      #
-      # @param [String] message
-      # @return [void]
-      def help(message)
-        @__cinch_help_message = message
-      end
-
-      # Set the plugin prefix.
-      #
-      # @param [String] prefix
-      # @return [void]
-      def prefix(prefix = nil, &block)
-        raise ArgumentError if prefix.nil? && block.nil?
-        @__cinch_prefix = prefix || block
-      end
-
-      # Set the plugin suffix.
-      #
-      # @param [String] suffix
-      # @return [void]
-      def suffix(suffix = nil, &block)
-        raise ArgumentError if suffix.nil? && block.nil?
-        @__cinch_suffix = suffix || block
+        @ctcps << command.to_s.upcase
       end
 
-
-
-      # Set which kind of messages to react on (i.e. call {#execute})
-      #
-      # @param [Symbol<:message, :channel, :private>] target React to all,
-      #   only public or only private messages?
+      # Set which kind of messages to react on for matchers.
+      # @param [Symbol<:message, :channel, :private>] event Which event to react on
       # @return [void]
-      def react_on(target)
-        @__cinch_react_on = target
-      end
-
-      # Define the plugin name.
-      #
-      # @param [String] name
-      # @return [void]
-      def plugin(name)
-        @__cinch_name = name
+      def react_on(event)
+        self.reacting_on = event
       end
 
       # @example
@@ -110,14 +230,27 @@ module Cinch
       #   def some_method
       #     Channel("#cinch-bots").send(Time.now.to_s)
       #   end
+      #
       # @param [Number] interval Interval in seconds
-      # @option options [Symbol] :method (:timer) Method to call
-      # @option options [Boolean] :threaded (true) Call method in a thread?
-      # @return [void]
+      # @option options [Symbol] :method (:timer) Method to call (only
+      #   if no proc is provided)
+      # @option options [Number] :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)
-        @__cinch_timers ||= []
-        @__cinch_timers << Timer.new(interval, options[:method], options[:threaded], false)
+        timer = Timer.new(interval, options, false)
+        @timers << timer
+
+        timer
       end
 
       # Defines a hook which will be run before or after a handler is
@@ -128,27 +261,23 @@ module Cinch
       # @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 (true) The method to execute.
-      # @return [void]
+      # @return [Hook]
+      # @since 1.1.0
       def hook(type, options = {})
         options = {:for => [:match, :listen_to, :ctcp], :method => :hook}.merge(options)
-        __hooks(type) << Hook.new(type, options[:for], options[:method])
-      end
+        hook = Hook.new(type, options[:for], options[:method])
+        __hooks(type) << hook
 
-      # @return [String]
-      # @api private
-      def __plugin_name
-        @__cinch_name || self.name.split("::").last.downcase
+        hook
       end
 
       # @return [Hash]
       # @api private
       def __hooks(type = nil, events = nil)
-        @__cinch_hooks ||= Hash.new{|h,k| h[k] = []}
-
         if type.nil?
-          hooks = @__cinch_hooks
+          hooks = @hooks
         else
-          hooks = @__cinch_hooks[type]
+          hooks = @hooks[type]
         end
 
         if events.nil?
@@ -162,133 +291,178 @@ module Cinch
         end
       end
 
-      # @return [void]
+      # @return [Boolean] True if processing should continue
       # @api private
-      def __register_with_bot(bot, instance)
-        plugin_name = __plugin_name
-
-        (@__cinch_listeners || []).each do |listener|
-          bot.debug "[plugin] #{plugin_name}: Registering listener for type `#{listener.event}`"
-          bot.on(listener.event, [], instance) do |message, plugin, *args|
-            if plugin.respond_to?(listener.method)
-              plugin.class.__hooks(:pre, :listen_to).each {|hook| plugin.__send__(hook.method, message)}
-              plugin.__send__(listener.method, message, *args)
-              plugin.class.__hooks(:post, :listen_to).each {|hook| plugin.__send__(hook.method, message)}
-            end
-          end
-        end
+      def call_hooks(type, event, instance, args)
+        stop = __hooks(type, event).find { |hook|
+          # stop after the first hook that returns false
+          instance.__send__(hook.method, *args) == false
+        }
 
-        if (@__cinch_matches ||= []).empty?
-          @__cinch_matches << Match.new(plugin_name, true, true, :execute)
-        end
+        !stop
+      end
 
-        prefix = @__cinch_prefix || bot.config.plugins.prefix
-        suffix = @__cinch_suffix || bot.config.plugins.suffix
-
-        @__cinch_matches.each do |pattern|
-          _prefix = pattern.use_prefix ? prefix : nil
-          _suffix = pattern.use_suffix ? suffix : nil
-
-          pattern_to_register = Pattern.new(_prefix, pattern.pattern, _suffix)
-          react_on = @__cinch_react_on || :message
-
-          bot.debug "[plugin] #{plugin_name}: Registering executor with pattern `#{pattern_to_register.inspect}`, reacting on `#{react_on}`"
-
-          bot.on(react_on, pattern_to_register, instance, pattern) do |message, plugin, pattern, *args|
-            if plugin.respond_to?(pattern.method)
-              method = plugin.method(pattern.method)
-              arity = method.arity - 1
-              if arity > 0
-                args = args[0..arity - 1]
-              elsif arity == 0
-                args = []
-              end
-              plugin.class.__hooks(:pre, :match).each {|hook| plugin.__send__(hook.method, message)}
-              method.call(message, *args)
-              plugin.class.__hooks(:post, :match).each {|hook| plugin.__send__(hook.method, message)}
-            end
-          end
-        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
 
-        (@__cinch_ctcps || []).each do |ctcp|
-          bot.debug "[plugin] #{plugin_name}: Registering CTCP `#{ctcp}`"
-          bot.on(:ctcp, ctcp, instance, ctcp) do |message, plugin, ctcp, *args|
-            plugin.class.__hooks(:pre, :ctcp).each {|hook| plugin.__send__(hook.method, message)}
-            plugin.__send__("ctcp_#{ctcp.downcase}", message, *args)
-            plugin.class.__hooks(:post, :ctcp).each {|hook| plugin.__send__(hook.method, message)}
+    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, self, [message])
+            __send__(listener.method, message, *args)
+            self.class.call_hooks(:post, :listen_to, self, [message])
+          else
+            @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Dropping message due to hook"
           end
         end
 
-        (@__cinch_timers || []).each do |timer|
-          bot.debug "[plugin] #{__plugin_name}: Registering timer with interval `#{timer.interval}` for method `#{timer.method}`"
-          bot.on :connect do
-            next if timer.registered
-            timer.registered = true
-            Thread.new do
-              bot.debug "registering timer..."
-              loop do
-                sleep timer.interval
-                if instance.respond_to?(timer.method)
-                  l = lambda {
-                    begin
-                      instance.__send__(timer.method)
-                    rescue => e
-                      bot.logger.log_exception(e)
-                    end
-                  }
-
-                  if timer.threaded
-                    Thread.new do
-                      l.call
-                    end
-                  else
-                    l.call
-                  end
-                end
-              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, self, [message])
+            __send__("ctcp_#{ctcp.downcase}", message, *args)
+            self.class.call_hooks(:post, :ctcp, self, [message])
+          else
+            @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Dropping message due to hook"
           end
         end
 
-        if @__cinch_help_message
-          bot.debug "[plugin] #{plugin_name}: Registering help message"
-          help_pattern = Pattern.new(prefix, "help #{plugin_name}", suffix)
-          bot.on(:message, help_pattern, @__cinch_help_message) do |message, help_message|
-            message.reply(help_message)
+        @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.reacting_on || self.class.reacting_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) 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, self, [message])
+            method.call(message, *args)
+            self.class.call_hooks(:post, :match, 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
+
+    # @return [Storage] The per-plugin persistent storage
+    attr_reader :storage
+
     # @api private
     def initialize(bot)
       @bot = bot
-      self.class.__register_with_bot(bot, self)
+      @handlers = []
+      @timers   = []
+      @storage  = bot.config.storage.backend.new(@bot.config.storage, self)
+      __register
     end
 
-    # (see Bot#synchronize)
-    def synchronize(*args, &block)
-      @bot.synchronize(*args, &block)
-    end
+    # @since 2.0.0
+    def unregister
+      @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Unloading plugin"
+      @timers.each do |timer|
+        timer.stop
+      end
 
-    # This method will be executed whenever an event the plugin
-    # {Plugin::ClassMethods#listen_to listens to} occurs.
-    #
-    # @abstract
-    # @return [void]
-    # @see Plugin::ClassMethods#listen_to
-    def listen(*args)
+      handlers.each do |handler|
+        handler.stop
+        handler.unregister
+      end
     end
 
-    # This method will be executed whenever a message matches the
-    # {Plugin::ClassMethods#match match pattern} of the plugin.
-    #
-    # @abstract
-    # @return [void]
-    # @see Plugin::ClassMethods#match
-    def execute(*args)
+    # (see Bot#synchronize)
+    def synchronize(*args, &block)
+      @bot.synchronize(*args, &block)
     end
 
     # Provides access to plugin-specific options.
@@ -298,6 +472,7 @@ module Cinch
       @bot.config.plugins.options[self.class] || {}
     end
 
+    # @api private
     def self.included(by)
       by.extend ClassMethods
     end