rbot/plugins.rb

   1 module Irc
   2
   3   # base class for all rbot plugins
   4   # certain methods will be called if they are provided, if you define one of
   5   # the following methods, it will be called as appropriate:
   6   #
   7   # listen(UserMessage)::
   8   #                        Called for all messages of any type. To
   9   #                        differentiate them, use message.kind_of? It'll be
  10   #                        either a PrivMessage, NoticeMessage, KickMessage,
  11   #                        QuitMessage, PartMessage, JoinMessage, NickMessage,
  12   #                        etc.
  13   #
  14   # privmsg(PrivMessage)::
  15   #                        called for a PRIVMSG if the first word matches one
  16   #                        the plugin register()d for. Use m.plugin to get
  17   #                        that word and m.params for the rest of the message,
  18   #                        if applicable.
  19   #
  20   # kick(KickMessage)::
  21   #                        Called when a user (or the bot) is kicked from a
  22   #                        channel the bot is in.
  23   #
  24   # join(JoinMessage)::
  25   #                        Called when a user (or the bot) joins a channel
  26   #
  27   # part(PartMessage)::
  28   #                        Called when a user (or the bot) parts a channel
  29   #
  30   # quit(QuitMessage)::
  31   #                        Called when a user (or the bot) quits IRC
  32   #
  33   # nick(NickMessage)::
  34   #                        Called when a user (or the bot) changes Nick
  35   # topic(TopicMessage)::
  36   #                        Called when a user (or the bot) changes a channel
  37   #                        topic
  38   #
  39   # save::                 Called when you are required to save your plugin's
  40   #                        state, if you maintain data between sessions
  41   #
  42   # cleanup::              called before your plugin is "unloaded", prior to a
  43   #                        plugin reload or bot quit - close any open
  44   #                        files/connections or flush caches here
  45   class Plugin
  46     # initialise your plugin. Always call super if you override this method,
  47     # as important variables are set up for you
  48     def initialize
  49       @bot = Plugins.bot
  50       @names = Array.new
  51       @registry = BotRegistryAccessor.new(@bot, self.class.to_s.gsub(/^.*::/, ""))
  52     end
  53
  54     # return an identifier for this plugin, defaults to a list of the message
  55     # prefixes handled (used for error messages etc)
  56     def name
  57       @names.join("|")
  58     end
  59
  60     # return a help string for your module. for complex modules, you may wish
  61     # to break your help into topics, and return a list of available topics if
  62     # +topic+ is nil. +plugin+ is passed containing the matching prefix for
  63     # this message - if your plugin handles multiple prefixes, make sure your
  64     # return the correct help for the prefix requested
  65     def help(plugin, topic)
  66       "no help"
  67     end
  68
  69     # register the plugin as a handler for messages prefixed +name+
  70     # this can be called multiple times for a plugin to handle multiple
  71     # message prefixes
  72     def register(name)
  73       Plugins.plugins[name] = self
  74       @names << name
  75     end
  76
  77     # is this plugin listening to all messages?
  78     def listen?
  79       @listen
  80     end
  81
  82   end
  83
  84   # class to manage multiple plugins and delegate messages to them for
  85   # handling
  86   class Plugins
  87     # hash of registered message prefixes and associated plugins
  88     @@plugins = Hash.new
  89     # associated IrcBot class
  90     @@bot = nil
  91
  92     # bot::     associated IrcBot class
  93     # dirlist:: array of directories to scan (in order) for plugins
  94     #
  95     # create a new plugin handler, scanning for plugins in +dirlist+
  96     def initialize(bot, dirlist)
  97       @@bot = bot
  98       @dirs = dirlist
  99       scan
 100     end
 101
 102     # access to associated bot
 103     def Plugins.bot
 104       @@bot
 105     end
 106
 107     # access to list of plugins
 108     def Plugins.plugins
 109       @@plugins
 110     end
 111
 112     # load plugins from pre-assigned list of directories
 113     def scan
 114       dirs = Array.new
 115       dirs << File.dirname(__FILE__) + "/plugins"
 116       dirs += @dirs
 117       dirs.each {|dir|
 118         if(FileTest.directory?(dir))
 119           d = Dir.new(dir)
 120           d.each {|file|
 121             next if(file =~ /^\./)
 122             next unless(file =~ /\.rb$/)
 123             @tmpfilename = "#{dir}/#{file}"
 124
 125             # create a new, anonymous module to "house" the plugin
 126             plugin_module = Module.new
 127
 128             begin
 129               plugin_string = IO.readlines(@tmpfilename).join("")
 130               puts "loading module: #{@tmpfilename}"
 131               plugin_module.module_eval(plugin_string)
 132             rescue StandardError, NameError, LoadError, SyntaxError => err
 133               puts "plugin #{@tmpfilename} load failed: " + err
 134               puts err.backtrace.join("\n")
 135             end
 136           }
 137         end
 138       }
 139     end
 140
 141     # call the save method for each active plugin
 142     def save
 143       @@plugins.values.uniq.each {|p|
 144         next unless(p.respond_to?("save"))
 145         begin
 146           p.save
 147         rescue StandardError, NameError, SyntaxError => err
 148           puts "plugin #{p.name} save() failed: " + err
 149           puts err.backtrace.join("\n")
 150         end
 151       }
 152     end
 153
 154     # call the cleanup method for each active plugin
 155     def cleanup
 156       @@plugins.values.uniq.each {|p|
 157         next unless(p.respond_to?("cleanup"))
 158         begin
 159           p.cleanup
 160         rescue StandardError, NameError, SyntaxError => err
 161           puts "plugin #{p.name} cleanup() failed: " + err
 162           puts err.backtrace.join("\n")
 163         end
 164       }
 165     end
 166
 167     # drop all plugins and rescan plugins on disk
 168     # calls save and cleanup for each plugin before dropping them
 169     def rescan
 170       save
 171       cleanup
 172       @@plugins = Hash.new
 173       scan
 174     end
 175
 176     # return list of help topics (plugin names)
 177     def helptopics
 178       if(@@plugins.length > 0)
 179         # return " [plugins: " + @@plugins.keys.sort.join(", ") + "]"
 180         return " [#{length} plugins: " + @@plugins.values.uniq.collect{|p| p.name}.sort.join(", ") + "]"
 181       else
 182         return " [no plugins active]"
 183       end
 184     end
 185
 186     def length
 187       @@plugins.values.uniq.length
 188     end
 189
 190     # return help for +topic+ (call associated plugin's help method)
 191     def help(topic="")
 192       if(topic =~ /^(\S+)\s*(.*)$/)
 193         key = $1
 194         params = $2
 195         if(@@plugins.has_key?(key))
 196           begin
 197             return @@plugins[key].help(key, params)
 198           rescue StandardError, NameError, SyntaxError => err
 199             puts "plugin #{@@plugins[key].name} help() failed: " + err
 200             puts err.backtrace.join("\n")
 201           end
 202         else
 203           return false
 204         end
 205       end
 206     end
 207
 208     # see if each plugin handles +method+, and if so, call it, passing
 209     # +message+ as a parameter
 210     def delegate(method, message)
 211       @@plugins.values.uniq.each {|p|
 212         if(p.respond_to? method)
 213           begin
 214             p.send method, message
 215           rescue StandardError, NameError, SyntaxError => err
 216             puts "plugin #{p.name} #{method}() failed: " + err
 217             puts err.backtrace.join("\n")
 218           end
 219         end
 220       }
 221     end
 222
 223     # see if we have a plugin that wants to handle this message, if so, pass
 224     # it to the plugin and return true, otherwise false
 225     def privmsg(m)
 226       return unless(m.plugin)
 227       if (@@plugins.has_key?(m.plugin) &&
 228           @@plugins[m.plugin].respond_to?("privmsg") &&
 229           @@bot.auth.allow?(m.plugin, m.source, m.replyto))
 230         begin
 231           @@plugins[m.plugin].privmsg(m)
 232         rescue StandardError, NameError, SyntaxError => err
 233           puts "plugin #{@@plugins[m.plugin].name} privmsg() failed: " + err
 234           puts err.backtrace.join("\n")
 235         end
 236         return true
 237       end
 238       return false
 239     end
 240   end
 241
 242 end