patch from Alexey Froloff:
[rbot] / lib / rbot / plugins.rb
1 module Irc
2 module Plugins
3   require 'rbot/messagemapper'
4
5   # base class for all rbot plugins
6   # certain methods will be called if they are provided, if you define one of
7   # the following methods, it will be called as appropriate:
8   #
9   # map(template, options)::
10   #    map is the new, cleaner way to respond to specific message formats
11   #    without littering your plugin code with regexps. examples:
12   #
13   #      plugin.map 'karmastats', :action => 'karma_stats'
14   #
15   #      # while in the plugin...
16   #      def karma_stats(m, params)
17   #        m.reply "..."
18   #      end
19   #      
20   #      # the default action is the first component
21   #      plugin.map 'karma'
22   #
23   #      # attributes can be pulled out of the match string
24   #      plugin.map 'karma for :key'
25   #      plugin.map 'karma :key'
26   #
27   #      # while in the plugin...
28   #      def karma(m, params)
29   #        item = params[:key]
30   #        m.reply 'karma for #{item}'
31   #      end
32   #      
33   #      # you can setup defaults, to make parameters optional
34   #      plugin.map 'karma :key', :defaults => {:key => 'defaultvalue'}
35   #      
36   #      # the default auth check is also against the first component
37   #      # but that can be changed
38   #      plugin.map 'karmastats', :auth => 'karma'
39   #
40   #      # maps can be restricted to public or private message:
41   #      plugin.map 'karmastats', :private false,
42   #      plugin.map 'karmastats', :public false,
43   #    end
44   #
45   #    To activate your maps, you simply register them
46   #    plugin.register_maps
47   #    This also sets the privmsg handler to use the map lookups for
48   #    handling messages. You can still use listen(), kick() etc methods
49   # 
50   # listen(UserMessage)::
51   #                        Called for all messages of any type. To
52   #                        differentiate them, use message.kind_of? It'll be
53   #                        either a PrivMessage, NoticeMessage, KickMessage,
54   #                        QuitMessage, PartMessage, JoinMessage, NickMessage,
55   #                        etc.
56   #                              
57   # privmsg(PrivMessage)::
58   #                        called for a PRIVMSG if the first word matches one
59   #                        the plugin register()d for. Use m.plugin to get
60   #                        that word and m.params for the rest of the message,
61   #                        if applicable.
62   #
63   # kick(KickMessage)::
64   #                        Called when a user (or the bot) is kicked from a
65   #                        channel the bot is in.
66   #
67   # join(JoinMessage)::
68   #                        Called when a user (or the bot) joins a channel
69   #
70   # part(PartMessage)::
71   #                        Called when a user (or the bot) parts a channel
72   #
73   # quit(QuitMessage)::    
74   #                        Called when a user (or the bot) quits IRC
75   #
76   # nick(NickMessage)::
77   #                        Called when a user (or the bot) changes Nick
78   # topic(TopicMessage)::
79   #                        Called when a user (or the bot) changes a channel
80   #                        topic
81   #
82   # connect()::            Called when a server is joined successfully, but
83   #                        before autojoin channels are joined (no params)
84   # 
85   # save::                 Called when you are required to save your plugin's
86   #                        state, if you maintain data between sessions
87   #
88   # cleanup::              called before your plugin is "unloaded", prior to a
89   #                        plugin reload or bot quit - close any open
90   #                        files/connections or flush caches here
91   class Plugin
92     attr_reader :bot   # the associated bot
93     # initialise your plugin. Always call super if you override this method,
94     # as important variables are set up for you
95     def initialize
96       @bot = Plugins.bot
97       @names = Array.new
98       @handler = MessageMapper.new(self)
99       @registry = BotRegistryAccessor.new(@bot, self.class.to_s.gsub(/^.*::/, ""))
100     end
101
102     def map(*args)
103       @handler.map(*args)
104       # register this map
105       name = @handler.last.items[0]
106       self.register name
107       unless self.respond_to?('privmsg')
108         def self.privmsg(m)
109           @handler.handle(m)
110         end
111       end
112     end
113
114     # return an identifier for this plugin, defaults to a list of the message
115     # prefixes handled (used for error messages etc)
116     def name
117       @names.join("|")
118     end
119     
120     # return a help string for your module. for complex modules, you may wish
121     # to break your help into topics, and return a list of available topics if
122     # +topic+ is nil. +plugin+ is passed containing the matching prefix for
123     # this message - if your plugin handles multiple prefixes, make sure your
124     # return the correct help for the prefix requested
125     def help(plugin, topic)
126       "no help"
127     end
128     
129     # register the plugin as a handler for messages prefixed +name+
130     # this can be called multiple times for a plugin to handle multiple
131     # message prefixes
132     def register(name)
133       return if Plugins.plugins.has_key?(name)
134       Plugins.plugins[name] = self
135       @names << name
136     end
137
138     # default usage method provided as a utility for simple plugins. The
139     # MessageMapper uses 'usage' as its default fallback method.
140     def usage(m, params = {})
141       m.reply "incorrect usage, ask for help using '#{@bot.nick}: help #{m.plugin}'"
142     end
143
144   end
145
146   # class to manage multiple plugins and delegate messages to them for
147   # handling
148   class Plugins
149     # hash of registered message prefixes and associated plugins
150     @@plugins = Hash.new
151     # associated IrcBot class
152     @@bot = nil
153
154     # bot::     associated IrcBot class
155     # dirlist:: array of directories to scan (in order) for plugins
156     #
157     # create a new plugin handler, scanning for plugins in +dirlist+
158     def initialize(bot, dirlist)
159       @@bot = bot
160       @dirs = dirlist
161       scan
162     end
163     
164     # access to associated bot
165     def Plugins.bot
166       @@bot
167     end
168
169     # access to list of plugins
170     def Plugins.plugins
171       @@plugins
172     end
173
174     # load plugins from pre-assigned list of directories
175     def scan
176       processed = Array.new
177       dirs = Array.new
178       dirs << Config::datadir + "/plugins"
179       dirs += @dirs
180       dirs.reverse.each {|dir|
181         if(FileTest.directory?(dir))
182           d = Dir.new(dir)
183           d.sort.each {|file|
184             next if(file =~ /^\./)
185             next if(processed.include?(file))
186             if(file =~ /^(.+\.rb)\.disabled$/)
187               processed << $1
188               next
189             end
190             next unless(file =~ /\.rb$/)
191             tmpfilename = "#{dir}/#{file}"
192
193             # create a new, anonymous module to "house" the plugin
194             # the idea here is to prevent namespace pollution. perhaps there
195             # is another way?
196             plugin_module = Module.new
197             
198             begin
199               plugin_string = IO.readlines(tmpfilename).join("")
200               debug "loading plugin #{tmpfilename}"
201               plugin_module.module_eval(plugin_string)
202               processed << file
203             rescue TimeoutError, StandardError, NameError, LoadError, SyntaxError => err
204               puts "warning: plugin #{tmpfilename} load failed: " + err
205               puts err.backtrace.join("\n")
206             end
207           }
208         end
209       }
210     end
211
212     # call the save method for each active plugin
213     def save
214       delegate 'save'
215     end
216
217     # call the cleanup method for each active plugin
218     def cleanup
219       delegate 'cleanup'
220     end
221
222     # drop all plugins and rescan plugins on disk
223     # calls save and cleanup for each plugin before dropping them
224     def rescan
225       save
226       cleanup
227       @@plugins = Hash.new
228       scan
229     end
230
231     # return list of help topics (plugin names)
232     def helptopics
233       if(@@plugins.length > 0)
234         # return " [plugins: " + @@plugins.keys.sort.join(", ") + "]"
235         return " [#{length} plugins: " + @@plugins.values.uniq.collect{|p| p.name}.sort.join(", ") + "]"
236       else
237         return " [no plugins active]" 
238       end
239     end
240
241     def length
242       @@plugins.values.uniq.length
243     end
244
245     # return help for +topic+ (call associated plugin's help method)
246     def help(topic="")
247       if(topic =~ /^(\S+)\s*(.*)$/)
248         key = $1
249         params = $2
250         if(@@plugins.has_key?(key))
251           begin
252             return @@plugins[key].help(key, params)
253           rescue TimeoutError, StandardError, NameError, SyntaxError => err
254             puts "plugin #{@@plugins[key].name} help() failed: " + err
255             puts err.backtrace.join("\n")
256           end
257         else
258           return false
259         end
260       end
261     end
262     
263     # see if each plugin handles +method+, and if so, call it, passing
264     # +message+ as a parameter
265     def delegate(method, *args)
266       @@plugins.values.uniq.each {|p|
267         if(p.respond_to? method)
268           begin
269             p.send method, *args
270           rescue TimeoutError, StandardError, NameError, SyntaxError => err
271             puts "plugin #{p.name} #{method}() failed: " + err
272             puts err.backtrace.join("\n")
273           end
274         end
275       }
276     end
277
278     # see if we have a plugin that wants to handle this message, if so, pass
279     # it to the plugin and return true, otherwise false
280     def privmsg(m)
281       return unless(m.plugin)
282       if (@@plugins.has_key?(m.plugin) &&
283           @@plugins[m.plugin].respond_to?("privmsg") &&
284           @@bot.auth.allow?(m.plugin, m.source, m.replyto))
285         begin
286           @@plugins[m.plugin].privmsg(m)
287         rescue TimeoutError, StandardError, NameError, SyntaxError => err
288           puts "plugin #{@@plugins[m.plugin].name} privmsg() failed: " + err
289           puts err.backtrace.join("\n")
290         end
291         return true
292       end
293       return false
294     end
295   end
296
297 end
298 end