X-Git-Url: https://git.netwichtig.de/gitweb/?a=blobdiff_plain;f=lib%2Frbot%2Fplugins.rb;h=631984c14a85147371f9797bdd718fd777b3f180;hb=1f7b45bcfa05821884ba47d4e42608c8f9b5a6b1;hp=061c6a73b3b7d4d5ce033d65cb0474dd11b1022f;hpb=414734f9872b1d60d2c92951965c0aba0cdf5884;p=user%2Fhenk%2Fcode%2Fruby%2Frbot.git

diff --git a/lib/rbot/plugins.rb b/lib/rbot/plugins.rb
index 061c6a73..631984c1 100644
--- a/lib/rbot/plugins.rb
+++ b/lib/rbot/plugins.rb
@@ -6,23 +6,31 @@
 require 'singleton'
 
 module Irc
-    BotConfig.register BotConfigArrayValue.new('plugins.blacklist',
+class Bot
+    Config.register Config::ArrayValue.new('plugins.blacklist',
       :default => [], :wizard => false, :requires_rescan => true,
       :desc => "Plugins that should not be loaded")
 module Plugins
   require 'rbot/messagemapper'
 
-=begin
-  base class for all rbot plugins
-  certain methods will be called if they are provided, if you define one of
-  the following methods, it will be called as appropriate:
+=begin rdoc
+  BotModule is the base class for the modules that enhance the rbot
+  functionality. Rather than subclassing BotModule, however, one should
+  subclass either CoreBotModule (reserved for system modules) or Plugin
+  (for user plugins).
+
+  A BotModule interacts with Irc events by defining one or more of the following
+  methods, which get called as appropriate when the corresponding Irc event
+  happens.
 
   map(template, options)::
   map!(template, options)::
-     map is the new, cleaner way to respond to specific message formats
-     without littering your plugin code with regexps. The difference
-     between map and map! is that map! will not register the new command
-     as an alternative name for the plugin.
+     map is the new, cleaner way to respond to specific message formats without
+     littering your plugin code with regexps, and should be used instead of
+     #register() and #privmsg() (see below) when possible.
+
+     The difference between map and map! is that map! will not register the new
+     command as an alternative name for the plugin.
 
      Examples:
 
@@ -54,9 +62,11 @@ module Plugins
        plugin.map 'karmastats', :auth => 'karma'
 
        # maps can be restricted to public or private message:
-       plugin.map 'karmastats', :private false,
-       plugin.map 'karmastats', :public false,
-     end
+       plugin.map 'karmastats', :private => false
+       plugin.map 'karmastats', :public => false
+
+     See MessageMapper#map for more information on the template format and the
+     allowed options.
 
   listen(UserMessage)::
                          Called for all messages of any type. To
@@ -72,19 +82,31 @@ module Plugins
                          use message.ctcp_reply, which sends a private NOTICE
                          to the sender.
 
+  message(PrivMessage)::
+                         Called for all PRIVMSG. Hook on this method if you
+                         need to handle PRIVMSGs regardless of whether they are
+                         addressed to the bot or not, and regardless of
+
   privmsg(PrivMessage)::
                          Called for a PRIVMSG if the first word matches one
-                         the plugin register()d for. Use m.plugin to get
+                         the plugin #register()ed for. Use m.plugin to get
                          that word and m.params for the rest of the message,
                          if applicable.
 
   unreplied(PrivMessage)::
                          Called for a PRIVMSG which has not been replied to.
 
+  notice(NoticeMessage)::
+                         Called for all Notices. Please notice that in general
+                         should not be replied to.
+
   kick(KickMessage)::
                          Called when a user (or the bot) is kicked from a
                          channel the bot is in.
 
+  invite(InviteMessage)::
+                         Called when the bot is invited to a channel.
+
   join(JoinMessage)::
                          Called when a user (or the bot) joins a channel
 
@@ -100,7 +122,15 @@ module Plugins
                          Called when a user (or the bot) changes a channel
                          topic
 
-  connect()::            Called when a server is joined successfully, but
+  welcome(WelcomeMessage)::
+                         Called when the welcome message is received on
+                         joining a server succesfully.
+
+  motd(MotdMessage)::
+                         Called when the Message Of The Day is fully
+                         recevied from the server.
+
+  connect::              Called when a server is joined successfully, but
                          before autojoin channels are joined (no params)
 
   set_language(String)::
@@ -116,10 +146,34 @@ module Plugins
 =end
 
   class BotModule
-    attr_reader :bot   # the associated bot
+    # the associated bot
+    attr_reader :bot
+
+    # the plugin registry
+    attr_reader :registry
+
+    # the message map handler
+    attr_reader :handler
 
-    # initialise your bot module. Always call super if you override this method,
-    # as important variables are set up for you
+    # Initialise your bot module. Always call super if you override this method,
+    # as important variables are set up for you:
+    #
+    # @bot::
+    #   the rbot instance
+    # @registry::
+    #   the botmodule's registry, which can be used to store permanent data
+    #   (see Registry::Accessor for additional documentation)
+    #
+    # Other instance variables which are defined and should not be overwritten
+    # byt the user, but aren't usually accessed directly, are:
+    #
+    # @manager::
+    #   the plugins manager instance
+    # @botmodule_triggers::
+    #   an Array of words this plugin #register()ed itself for
+    # @handler::
+    #   the MessageMapper that handles this plugin's maps
+    #
     def initialize
       @manager = Plugins::manager
       @bot = @manager.bot
@@ -127,7 +181,7 @@ module Plugins
       @botmodule_triggers = Array.new
 
       @handler = MessageMapper.new(self)
-      @registry = BotRegistryAccessor.new(@bot, self.class.to_s.gsub(/^.*::/, ""))
+      @registry = Registry::Accessor.new(@bot, self.class.to_s.gsub(/^.*::/, ""))
 
       @manager.add_botmodule(self)
       if self.respond_to?('set_language')
@@ -135,47 +189,76 @@ module Plugins
       end
     end
 
+    # Changing the value of @priority directly will cause problems,
+    # Please use priority=.
+    def priority
+      @priority ||= 1
+    end
+
+    # Returns the symbol :BotModule 
     def botmodule_class
       :BotModule
     end
 
+    # Method called to flush the registry, thus ensuring that the botmodule's permanent
+    # data is committed to disk
+    #
     def flush_registry
       # debug "Flushing #{@registry}"
       @registry.flush
     end
 
+    # Method called to cleanup before the plugin is unloaded. If you overload
+    # this method to handle additional cleanup tasks, remember to call super()
+    # so that the default cleanup actions are taken care of as well.
+    #
     def cleanup
       # debug "Closing #{@registry}"
       @registry.close
     end
 
+    # Handle an Irc::PrivMessage for which this BotModule has a map. The method
+    # is called automatically and there is usually no need to call it
+    # explicitly.
+    #
     def handle(m)
       @handler.handle(m)
     end
 
+    # Signal to other BotModules that an even happened.
+    #
     def call_event(ev, *args)
       @bot.plugins.delegate('event_' + ev.to_s.gsub(/[^\w\?!]+/, '_'), *args)
     end
 
+    # call-seq: map(template, options)
+    #
+    # This is the preferred way to register the BotModule so that it
+    # responds to appropriately-formed messages on Irc.
+    #
     def map(*args)
-      @handler.map(self, *args)
-      # register this map
-      name = @handler.last.items[0]
-      self.register name, :auth => nil
-      unless self.respond_to?('privmsg')
-        def self.privmsg(m)
-          handle(m)
-        end
-      end
+      do_map(false, *args)
     end
 
+    # call-seq: map!(template, options)
+    #
+    # This is the same as map but doesn't register the new command
+    # as an alternative name for the plugin.
+    #
     def map!(*args)
+      do_map(true, *args)
+    end
+
+    # Auxiliary method called by #map and #map!
+    def do_map(silent, *args)
       @handler.map(self, *args)
       # register this map
-      name = @handler.last.items[0]
-      self.register name, :auth => nil, :hidden => true
+      map = @handler.last
+      name = map.items[0]
+      self.register name, :auth => nil, :hidden => silent
+      @manager.register_map(self, map)
       unless self.respond_to?('privmsg')
-        def self.privmsg(m)
+        def self.privmsg(m) #:nodoc:
           handle(m)
         end
       end
@@ -200,23 +283,23 @@ module Plugins
       [name, cmd].compact.join("::")
     end
 
-    # return an identifier for this plugin, defaults to a list of the message
+    # Return an identifier for this plugin, defaults to a list of the message
     # prefixes handled (used for error messages etc)
     def name
       self.class.to_s.downcase.sub(/^#<module:.*?>::/,"").sub(/(plugin|module)?$/,"")
     end
 
-    # just calls name
+    # Just calls name
     def to_s
       name
     end
 
-    # intern the name
+    # Intern the name
     def to_sym
       self.name.to_sym
     end
 
-    # return a help string for your module. for complex modules, you may wish
+    # Return a help string for your module. For complex modules, you may wish
     # to break your help into topics, and return a list of available topics if
     # +topic+ is nil. +plugin+ is passed containing the matching prefix for
     # this message - if your plugin handles multiple prefixes, make sure you
@@ -225,9 +308,14 @@ module Plugins
       "no help"
     end
 
-    # register the plugin as a handler for messages prefixed +name+
-    # this can be called multiple times for a plugin to handle multiple
-    # message prefixes
+    # Register the plugin as a handler for messages prefixed _cmd_.
+    #
+    # This can be called multiple times for a plugin to handle multiple message
+    # prefixes.
+    #
+    # This command is now superceded by the #map() command, which should be used
+    # instead whenever possible.
+    # 
     def register(cmd, opts={})
       raise ArgumentError, "Second argument must be a hash!" unless opts.kind_of?(Hash)
       who = @manager.who_handles?(cmd)
@@ -243,20 +331,41 @@ module Plugins
       @botmodule_triggers << cmd unless opts.fetch(:hidden, false)
     end
 
-    # default usage method provided as a utility for simple plugins. The
+    # Default usage method provided as a utility for simple plugins. The
     # MessageMapper uses 'usage' as its default fallback method.
+    #
     def usage(m, params = {})
       m.reply(_("incorrect usage, ask for help using '%{command}'") % {:command => "#{@bot.nick}: help #{m.plugin}"})
     end
 
+    # Define the priority of the module.  During event delegation, lower 
+    # priority modules will be called first.  Default priority is 1
+    def priority=(prio)
+      if @priority != prio
+        @priority = prio
+        @bot.plugins.mark_priorities_dirty
+      end
+    end
   end
 
+  # A CoreBotModule is a BotModule that provides core functionality.
+  #
+  # This class should not be used by user plugins, as it's reserved for system
+  # plugins such as the ones that handle authentication, configuration and basic
+  # functionality.
+  #
   class CoreBotModule < BotModule
     def botmodule_class
       :CoreBotModule
     end
   end
 
+  # A Plugin is a BotModule that provides additional functionality.
+  #
+  # A user-defined plugin should subclass this, and then define any of the
+  # methods described in the documentation for BotModule to handle interaction
+  # with Irc events.
+  #
   class Plugin < BotModule
     def botmodule_class
       :Plugin
@@ -269,6 +378,17 @@ module Plugins
     include Singleton
     attr_reader :bot
     attr_reader :botmodules
+    attr_reader :maps
+
+    # This is the list of patterns commonly delegated to plugins.
+    # A fast delegation lookup is enabled for them.
+    DEFAULT_DELEGATE_PATTERNS = %r{^(?:
+      connect|names|nick|
+      listen|ctcp_listen|privmsg|unreplied|
+      kick|join|part|quit|
+      save|cleanup|flush_registry|
+      set_.*|event_.*
+    )$}x
 
     def initialize
       @botmodules = {
@@ -278,6 +398,14 @@ module Plugins
 
       @names_hash = Hash.new
       @commandmappers = Hash.new
+      @maps = Hash.new
+
+      # modules will be sorted on first delegate call
+      @sorted_modules = nil
+
+      @delegate_list = Hash.new { |h, k|
+        h[k] = Array.new
+      }
 
       @dirs = []
 
@@ -287,13 +415,28 @@ module Plugins
       bot_associate(nil)
     end
 
+    def inspect
+      ret = self.to_s[0..-2]
+      ret << ' corebotmodules='
+      ret << @botmodules[:CoreBotModule].map { |m|
+        m.name
+      }.inspect
+      ret << ' plugins='
+      ret << @botmodules[:Plugin].map { |m|
+        m.name
+      }.inspect
+      ret << ">"
+    end
+
     # Reset lists of botmodules
     def reset_botmodule_lists
       @botmodules[:CoreBotModule].clear
       @botmodules[:Plugin].clear
       @names_hash.clear
       @commandmappers.clear
+      @maps.clear
       @failures_shown = false
+      mark_priorities_dirty
     end
 
     # Associate with bot _bot_
@@ -319,6 +462,19 @@ module Plugins
       @commandmappers[cmd.to_sym] = {:botmodule => botmodule, :auth => auth_path}
     end
 
+    # Registers botmodule _botmodule_ with map _map_. This adds the map to the #maps hash
+    # which has three keys:
+    #
+    # botmodule:: the associated botmodule
+    # auth:: an array of auth keys checked by the map; the first is the full_auth_path of the map
+    # map:: the actual MessageTemplate object
+    #
+    #
+    def register_map(botmodule, map)
+      raise TypeError, "First argument #{botmodule.inspect} is not of class BotModule" unless botmodule.kind_of?(BotModule)
+      @maps[map.template] = { :botmodule => botmodule, :auth => [map.options[:full_auth_path]], :map => map }
+    end
+
     def add_botmodule(botmodule)
       raise TypeError, "Argument #{botmodule.inspect} is not of class BotModule" unless botmodule.kind_of?(BotModule)
       kl = botmodule.botmodule_class
@@ -332,6 +488,7 @@ module Plugins
       end
       @botmodules[kl] << botmodule
       @names_hash[botmodule.to_sym] = botmodule
+      mark_priorities_dirty
     end
 
     # Returns an array of the loaded plugins
@@ -350,6 +507,12 @@ module Plugins
       @commandmappers
     end
 
+    # Tells the PluginManager that the next time it delegates an event, it
+    # should sort the modules by priority
+    def mark_priorities_dirty
+      @sorted_modules = nil
+    end
+
     # Makes a string of error _err_ by adding text _str_
     def report_error(str, err)
       ([str, err.inspect] + err.backtrace).join("\n")
@@ -416,6 +579,8 @@ module Plugins
     def scan
       @failed.clear
       @ignored.clear
+      @delegate_list.clear
+
       processed = Hash.new
 
       @bot.config['plugins.blacklist'].each { |p|
@@ -460,6 +625,12 @@ module Plugins
         end
       }
       debug "finished loading plugins: #{status(true)}"
+      (core_modules + plugins).each { |p|
+       p.methods.grep(DEFAULT_DELEGATE_PATTERNS).each { |m|
+         @delegate_list[m.intern] << p
+       }
+      }
+      mark_priorities_dirty
     end
 
     # call the save method for each active plugin
@@ -595,9 +766,9 @@ module Plugins
         key = $1
         params = $2
 
-	# Let's see if we can match a plugin by the given name
+        # Let's see if we can match a plugin by the given name
         (core_modules + plugins).each { |p|
-	  next unless p.name == key
+          next unless p.name == key
           begin
             return p.help(key, params)
           rescue Exception => err
@@ -606,7 +777,7 @@ module Plugins
           end
         }
 
-	# Nope, let's see if it's a command, and ask for help at the corresponding botmodule
+        # Nope, let's see if it's a command, and ask for help at the corresponding botmodule
         k = key.to_sym
         if commands.has_key?(k)
           p = commands[k][:botmodule]
@@ -621,17 +792,90 @@ module Plugins
       return false
     end
 
+    def sort_modules
+      @sorted_modules = (core_modules + plugins).sort do |a, b| 
+        a.priority <=> b.priority
+      end || []
+
+      @delegate_list.each_value do |list|
+        list.sort! {|a,b| a.priority <=> b.priority}
+      end
+    end
+
     # see if each plugin handles +method+, and if so, call it, passing
-    # +message+ as a parameter
+    # +message+ as a parameter.  botmodules are called in order of priority
+    # from lowest to highest.
+    #
+    # If the passed +message+ is marked as +#ignored?+, it will only be
+    # delegated to plugins with negative priority. Conversely, if it's
+    # a fake message  (see BotModule#fake_message), it will only be
+    # delegated to plugins with positive priority.
+    #
+    # For delegation with more extensive options, see delegate_event
+    #
     def delegate(method, *args)
+      opts = {:args => args}
+      m = args.first
+      if BasicUserMessage === m
+        # ignored messages should not be delegated
+        # to plugins with positive priority
+        opts[:below] = 0 if m.ignored?
+        # fake messages should not be delegated
+        # to plugins with negative priority
+        opts[:above] = 0 if m.recurse_depth > 0
+      end
+      delegate_event(method, opts)
+    end
+
+    # see if each plugin handles +method+, and if so, call it, passing
+    # +opts[:args]+ as a parameter.  +opts[:above]+ and +opts[:below]+
+    # are used for a threshold of botmodule priorities that will be called.
+    # If :above is defined, only botmodules with a priority above the value
+    # will be called, for example.  botmodules are called in order of
+    # priority from lowest to hightest.
+    def delegate_event(method, o={})
+      # if the priorities order of the delegate list is dirty,
+      # meaning some modules have been added or priorities have been
+      # changed, then the delegate list will need to be sorted before
+      # delegation.  This should always be true for the first delegation.
+      sort_modules unless @sorted_modules
+
+      # set defaults
+      opts = {:args => []}.merge(o)
+
+      above = opts[:above]
+      below = opts[:below]
+      args = opts[:args]
+
       # debug "Delegating #{method.inspect}"
       ret = Array.new
-      [core_modules, plugins].each { |pl|
-        pl.each {|p|
+      if method.match(DEFAULT_DELEGATE_PATTERNS)
+        debug "fast-delegating #{method}"
+        m = method.to_sym
+        debug "no-one to delegate to" unless @delegate_list.has_key?(m)
+        return [] unless @delegate_list.has_key?(m)
+        @delegate_list[m].each { |p|
+          begin
+            prio = p.priority
+            unless (above and above >= prio) or (below and below <= prio)
+              ret.push p.send(method, *(args||[]))
+            end
+          rescue Exception => err
+            raise if err.kind_of?(SystemExit)
+            error report_error("#{p.botmodule_class} #{p.name} #{method}() failed:", err)
+            raise if err.kind_of?(BDB::Fatal)
+          end
+        }
+      else
+        debug "slow-delegating #{method}"
+        @sorted_modules.each { |p|
           if(p.respond_to? method)
             begin
               # debug "#{p.botmodule_class} #{p.name} responds"
-              ret.push p.send(method, *args)
+              prio = p.priority
+              unless (above and above >= prio) or (below and below <= prio)
+                ret.push p.send(method, *(args||[]))
+              end
             rescue Exception => err
               raise if err.kind_of?(SystemExit)
               error report_error("#{p.botmodule_class} #{p.name} #{method}() failed:", err)
@@ -639,7 +883,7 @@ module Plugins
             end
           end
         }
-      }
+      end
       return ret
       # debug "Finished delegating #{method.inspect}"
     end
@@ -647,7 +891,7 @@ module Plugins
     # see if we have a plugin that wants to handle this message, if so, pass
     # it to the plugin and return true, otherwise false
     def privmsg(m)
-      # debug "Delegating privmsg #{m.message.inspect} from #{m.source} to #{m.replyto} with pluginkey #{m.plugin.inspect}"
+      debug "Delegating privmsg #{m.inspect} with pluginkey #{m.plugin.inspect}"
       return unless m.plugin
       k = m.plugin.to_sym
       if commands.has_key?(k)
@@ -655,30 +899,45 @@ module Plugins
         a = commands[k][:auth]
         # We check here for things that don't check themselves
         # (e.g. mapped things)
-        # debug "Checking auth ..."
+        debug "Checking auth ..."
         if a.nil? || @bot.auth.allow?(a, m.source, m.replyto)
-          # debug "Checking response ..."
+          debug "Checking response ..."
           if p.respond_to?("privmsg")
             begin
-              # debug "#{p.botmodule_class} #{p.name} responds"
+              debug "#{p.botmodule_class} #{p.name} responds"
               p.privmsg(m)
             rescue Exception => err
               raise if err.kind_of?(SystemExit)
               error report_error("#{p.botmodule_class} #{p.name} privmsg() failed:", err)
               raise if err.kind_of?(BDB::Fatal)
             end
-            # debug "Successfully delegated #{m.message}"
+            debug "Successfully delegated #{m.inspect}"
             return true
           else
-            # debug "#{p.botmodule_class} #{p.name} is registered, but it doesn't respond to privmsg()"
+            debug "#{p.botmodule_class} #{p.name} is registered, but it doesn't respond to privmsg()"
           end
         else
-          # debug "#{p.botmodule_class} #{p.name} is registered, but #{m.source} isn't allowed to call #{m.plugin.inspect} on #{m.replyto}"
+          debug "#{p.botmodule_class} #{p.name} is registered, but #{m.source} isn't allowed to call #{m.plugin.inspect} on #{m.replyto}"
         end
+      else
+        debug "Command #{k} isn't handled"
       end
-      # debug "Finished delegating privmsg with key #{m.plugin.inspect}" + ( pl.empty? ? "" : " to #{pl.values.first[:botmodule].botmodule_class}s" )
       return false
-      # debug "Finished delegating privmsg with key #{m.plugin.inspect}"
+    end
+
+    # delegate IRC messages, by delegating 'listen' first, and the actual method
+    # afterwards. Delegating 'privmsg' also delegates ctcp_listen and message
+    # as appropriate.
+    def irc_delegate(method, m)
+      delegate('listen', m)
+      if method.to_sym == :privmsg
+        delegate('ctcp_listen', m) if m.ctcp
+        delegate('message', m)
+        privmsg(m) if m.address?
+        delegate('unreplied', m) unless m.replied
+      else
+        delegate(method, m)
+      end
     end
   end
 
@@ -689,3 +948,4 @@ module Plugins
 
 end
 end
+end