4 # :title: rbot plugin management
10 Config.register Config::ArrayValue.new('plugins.blacklist',
11 :default => [], :wizard => false, :requires_rescan => true,
12 :desc => "Plugins that should not be loaded")
14 require 'rbot/messagemapper'
17 BotModule is the base class for the modules that enhance the rbot
18 functionality. Rather than subclassing BotModule, however, one should
19 subclass either CoreBotModule (reserved for system modules) or Plugin
22 A BotModule interacts with Irc events by defining one or more of the following
23 methods, which get called as appropriate when the corresponding Irc event
26 map(template, options)::
27 map!(template, options)::
28 map is the new, cleaner way to respond to specific message formats without
29 littering your plugin code with regexps, and should be used instead of
30 #register() and #privmsg() (see below) when possible.
32 The difference between map and map! is that map! will not register the new
33 command as an alternative name for the plugin.
37 plugin.map 'karmastats', :action => 'karma_stats'
39 # while in the plugin...
40 def karma_stats(m, params)
44 # the default action is the first component
47 # attributes can be pulled out of the match string
48 plugin.map 'karma for :key'
49 plugin.map 'karma :key'
51 # while in the plugin...
54 m.reply 'karma for #{item}'
57 # you can setup defaults, to make parameters optional
58 plugin.map 'karma :key', :defaults => {:key => 'defaultvalue'}
60 # the default auth check is also against the first component
61 # but that can be changed
62 plugin.map 'karmastats', :auth => 'karma'
64 # maps can be restricted to public or private message:
65 plugin.map 'karmastats', :private => false
66 plugin.map 'karmastats', :public => false
68 See MessageMapper#map for more information on the template format and the
72 Called for all messages of any type. To
73 differentiate them, use message.kind_of? It'll be
74 either a PrivMessage, NoticeMessage, KickMessage,
75 QuitMessage, PartMessage, JoinMessage, NickMessage,
78 ctcp_listen(UserMessage)::
79 Called for all messages that contain a CTCP command.
80 Use message.ctcp to get the CTCP command, and
81 message.message to get the parameter string. To reply,
82 use message.ctcp_reply, which sends a private NOTICE
85 privmsg(PrivMessage)::
86 Called for a PRIVMSG if the first word matches one
87 the plugin #register()ed for. Use m.plugin to get
88 that word and m.params for the rest of the message,
91 unreplied(PrivMessage)::
92 Called for a PRIVMSG which has not been replied to.
95 Called when a user (or the bot) is kicked from a
96 channel the bot is in.
99 Called when a user (or the bot) joins a channel
102 Called when a user (or the bot) parts a channel
105 Called when a user (or the bot) quits IRC
108 Called when a user (or the bot) changes Nick
109 topic(TopicMessage)::
110 Called when a user (or the bot) changes a channel
113 connect:: Called when a server is joined successfully, but
114 before autojoin channels are joined (no params)
116 set_language(String)::
117 Called when the user sets a new language
118 whose name is the given String
120 save:: Called when you are required to save your plugin's
121 state, if you maintain data between sessions
123 cleanup:: called before your plugin is "unloaded", prior to a
124 plugin reload or bot quit - close any open
125 files/connections or flush caches here
129 attr_reader :bot # the associated bot
131 # Initialise your bot module. Always call super if you override this method,
132 # as important variables are set up for you:
137 # the botmodule's registry, which can be used to store permanent data
138 # (see Registry::Accessor for additional documentation)
140 # Other instance variables which are defined and should not be overwritten
141 # byt the user, but aren't usually accessed directly, are:
144 # the plugins manager instance
145 # @botmodule_triggers::
146 # an Array of words this plugin #register()ed itself for
148 # the MessageMapper that handles this plugin's maps
151 @manager = Plugins::manager
154 @botmodule_triggers = Array.new
156 @handler = MessageMapper.new(self)
157 @registry = Registry::Accessor.new(@bot, self.class.to_s.gsub(/^.*::/, ""))
159 @manager.add_botmodule(self)
160 if self.respond_to?('set_language')
161 self.set_language(@bot.lang.language)
165 # Returns the symbol :BotModule
170 # Method called to flush the registry, thus ensuring that the botmodule's permanent
171 # data is committed to disk
174 # debug "Flushing #{@registry}"
178 # Method called to cleanup before the plugin is unloaded. If you overload
179 # this method to handle additional cleanup tasks, remember to call super()
180 # so that the default cleanup actions are taken care of as well.
183 # debug "Closing #{@registry}"
187 # Handle an Irc::PrivMessage for which this BotModule has a map. The method
188 # is called automatically and there is usually no need to call it
195 # Signal to other BotModules that an even happened.
197 def call_event(ev, *args)
198 @bot.plugins.delegate('event_' + ev.to_s.gsub(/[^\w\?!]+/, '_'), *args)
201 # call-seq: map(template, options)
203 # This is the preferred way to register the BotModule so that it
204 # responds to appropriately-formed messages on Irc.
210 # call-seq: map!(template, options)
212 # This is the same as map but doesn't register the new command
213 # as an alternative name for the plugin.
219 # Auxiliary method called by #map and #map!
220 def do_map(silent, *args)
221 @handler.map(self, *args)
223 name = @handler.last.items[0]
224 self.register name, :auth => nil, :hidden => silent
225 unless self.respond_to?('privmsg')
226 def self.privmsg(m) #:nodoc:
232 # Sets the default auth for command path _cmd_ to _val_ on channel _chan_:
233 # usually _chan_ is either "*" for everywhere, public and private (in which
234 # case it can be omitted) or "?" for private communications
236 def default_auth(cmd, val, chan="*")
243 Auth::defaultbotuser.set_default_permission(propose_default_path(c), val)
246 # Gets the default command path which would be given to command _cmd_
247 def propose_default_path(cmd)
248 [name, cmd].compact.join("::")
251 # Return an identifier for this plugin, defaults to a list of the message
252 # prefixes handled (used for error messages etc)
254 self.class.to_s.downcase.sub(/^#<module:.*?>::/,"").sub(/(plugin|module)?$/,"")
267 # Return a help string for your module. For complex modules, you may wish
268 # to break your help into topics, and return a list of available topics if
269 # +topic+ is nil. +plugin+ is passed containing the matching prefix for
270 # this message - if your plugin handles multiple prefixes, make sure you
271 # return the correct help for the prefix requested
272 def help(plugin, topic)
276 # Register the plugin as a handler for messages prefixed _cmd_.
278 # This can be called multiple times for a plugin to handle multiple message
281 # This command is now superceded by the #map() command, which should be used
282 # instead whenever possible.
284 def register(cmd, opts={})
285 raise ArgumentError, "Second argument must be a hash!" unless opts.kind_of?(Hash)
286 who = @manager.who_handles?(cmd)
288 raise "Command #{cmd} is already handled by #{who.botmodule_class} #{who}" if who != self
291 if opts.has_key?(:auth)
292 @manager.register(self, cmd, opts[:auth])
294 @manager.register(self, cmd, propose_default_path(cmd))
296 @botmodule_triggers << cmd unless opts.fetch(:hidden, false)
299 # Default usage method provided as a utility for simple plugins. The
300 # MessageMapper uses 'usage' as its default fallback method.
302 def usage(m, params = {})
303 m.reply(_("incorrect usage, ask for help using '%{command}'") % {:command => "#{@bot.nick}: help #{m.plugin}"})
308 # A CoreBotModule is a BotModule that provides core functionality.
310 # This class should not be used by user plugins, as it's reserved for system
311 # plugins such as the ones that handle authentication, configuration and basic
314 class CoreBotModule < BotModule
320 # A Plugin is a BotModule that provides additional functionality.
322 # A user-defined plugin should subclass this, and then define any of the
323 # methods described in the documentation for BotModule to handle interaction
326 class Plugin < BotModule
332 # Singleton to manage multiple plugins and delegate messages to them for
334 class PluginManagerClass
337 attr_reader :botmodules
339 # This is the list of patterns commonly delegated to plugins.
340 # A fast delegation lookup is enabled for them.
341 DEFAULT_DELEGATE_PATTERNS = %r{^(?:
343 listen|ctcp_listen|privmsg|unreplied|
345 save|cleanup|flush_registry|
351 :CoreBotModule => [],
355 @names_hash = Hash.new
356 @commandmappers = Hash.new
357 @delegate_list = Hash.new { |h, k|
370 ret = self.to_s[0..-2]
371 ret << ' corebotmodules='
372 ret << @botmodules[:CoreBotModule].map { |m|
376 ret << @botmodules[:Plugin].map { |m|
382 # Reset lists of botmodules
383 def reset_botmodule_lists
384 @botmodules[:CoreBotModule].clear
385 @botmodules[:Plugin].clear
387 @commandmappers.clear
388 @failures_shown = false
391 # Associate with bot _bot_
392 def bot_associate(bot)
393 reset_botmodule_lists
397 # Returns the botmodule with the given _name_
399 @names_hash[name.to_sym]
402 # Returns +true+ if _cmd_ has already been registered as a command
403 def who_handles?(cmd)
404 return nil unless @commandmappers.has_key?(cmd.to_sym)
405 return @commandmappers[cmd.to_sym][:botmodule]
408 # Registers botmodule _botmodule_ with command _cmd_ and command path _auth_path_
409 def register(botmodule, cmd, auth_path)
410 raise TypeError, "First argument #{botmodule.inspect} is not of class BotModule" unless botmodule.kind_of?(BotModule)
411 @commandmappers[cmd.to_sym] = {:botmodule => botmodule, :auth => auth_path}
414 def add_botmodule(botmodule)
415 raise TypeError, "Argument #{botmodule.inspect} is not of class BotModule" unless botmodule.kind_of?(BotModule)
416 kl = botmodule.botmodule_class
417 if @names_hash.has_key?(botmodule.to_sym)
418 case self[botmodule].botmodule_class
420 raise "#{kl} #{botmodule} already registered!"
422 raise "#{self[botmodule].botmodule_class} #{botmodule} already registered, cannot re-register as #{kl}"
425 @botmodules[kl] << botmodule
426 @names_hash[botmodule.to_sym] = botmodule
429 # Returns an array of the loaded plugins
431 @botmodules[:CoreBotModule]
434 # Returns an array of the loaded plugins
439 # Returns a hash of the registered message prefixes and associated
445 # Makes a string of error _err_ by adding text _str_
446 def report_error(str, err)
447 ([str, err.inspect] + err.backtrace).join("\n")
450 # This method is the one that actually loads a module from the
453 # _desc_ is a simple description of what we are loading (plugin/botmodule/whatever)
455 # It returns the Symbol :loaded on success, and an Exception
458 def load_botmodule_file(fname, desc=nil)
459 # create a new, anonymous module to "house" the plugin
460 # the idea here is to prevent namespace pollution. perhaps there
462 plugin_module = Module.new
464 desc = desc.to_s + " " if desc
467 plugin_string = IO.readlines(fname).join("")
468 debug "loading #{desc}#{fname}"
469 plugin_module.module_eval(plugin_string, fname)
471 rescue Exception => err
472 # rescue TimeoutError, StandardError, NameError, LoadError, SyntaxError => err
473 error report_error("#{desc}#{fname} load failed", err)
474 bt = err.backtrace.select { |line|
475 line.match(/^(\(eval\)|#{fname}):\d+/)
478 el.gsub(/^\(eval\)(:\d+)(:in `.*')?(:.*)?/) { |m|
482 msg = err.to_str.gsub(/^\(eval\)(:\d+)(:in `.*')?(:.*)?/) { |m|
485 newerr = err.class.new(msg)
486 newerr.set_backtrace(bt)
490 private :load_botmodule_file
492 # add one or more directories to the list of directories to
493 # load botmodules from
495 # TODO find a way to specify necessary plugins which _must_ be loaded
497 def add_botmodule_dir(*dirlist)
499 debug "Botmodule loading path: #{@dirs.join(', ')}"
502 def clear_botmodule_dirs
504 debug "Botmodule loading path cleared"
507 # load plugins from pre-assigned list of directories
515 @bot.config['plugins.blacklist'].each { |p|
517 processed[pn.intern] = :blacklisted
522 if(FileTest.directory?(dir))
526 next if(file =~ /^\./)
528 if processed.has_key?(file.intern)
529 @ignored << {:name => file, :dir => dir, :reason => processed[file.intern]}
533 if(file =~ /^(.+\.rb)\.disabled$/)
534 # GB: Do we want to do this? This means that a disabled plugin in a directory
535 # will disable in all subsequent directories. This was probably meant
536 # to be used before plugins.blacklist was implemented, so I think
537 # we don't need this anymore
538 processed[$1.intern] = :disabled
539 @ignored << {:name => $1, :dir => dir, :reason => processed[$1.intern]}
543 next unless(file =~ /\.rb$/)
545 did_it = load_botmodule_file("#{dir}/#{file}", "plugin")
548 processed[file.intern] = did_it
550 @failed << { :name => file, :dir => dir, :reason => did_it }
556 debug "finished loading plugins: #{status(true)}"
557 (core_modules + plugins).each { |p|
558 p.methods.grep(DEFAULT_DELEGATE_PATTERNS).each { |m|
559 @delegate_list[m.intern] << p
564 # call the save method for each active plugin
566 delegate 'flush_registry'
570 # call the cleanup method for each active plugin
573 reset_botmodule_lists
576 # drop all plugins and rescan plugins on disk
577 # calls save and cleanup for each plugin before dropping them
584 def status(short=false)
586 if self.core_length > 0
588 output << n_("%{count} core module loaded", "%{count} core modules loaded",
589 self.core_length) % {:count => self.core_length}
591 output << n_("%{count} core module: %{list}",
592 "%{count} core modules: %{list}", self.core_length) %
593 { :count => self.core_length,
594 :list => core_modules.collect{ |p| p.name}.sort.join(", ") }
597 output << _("no core botmodules loaded")
599 # Active plugins first
602 output << n_("%{count} plugin loaded", "%{count} plugins loaded",
603 self.length) % {:count => self.length}
605 output << n_("%{count} plugin: %{list}",
606 "%{count} plugins: %{list}", self.length) %
607 { :count => self.length,
608 :list => plugins.collect{ |p| p.name}.sort.join(", ") }
611 output << "no plugins active"
613 # Ignored plugins next
614 unless @ignored.empty? or @failures_shown
616 output << n_("%{highlight}%{count} plugin ignored%{highlight}",
617 "%{highlight}%{count} plugins ignored%{highlight}",
619 { :count => @ignored.length, :highlight => Underline }
621 output << n_("%{highlight}%{count} plugin ignored%{highlight}: use %{bold}%{command}%{bold} to see why",
622 "%{highlight}%{count} plugins ignored%{highlight}: use %{bold}%{command}%{bold} to see why",
624 { :count => @ignored.length, :highlight => Underline,
625 :bold => Bold, :command => "help ignored plugins"}
628 # Failed plugins next
629 unless @failed.empty? or @failures_shown
631 output << n_("%{highlight}%{count} plugin failed to load%{highlight}",
632 "%{highlight}%{count} plugins failed to load%{highlight}",
634 { :count => @failed.length, :highlight => Reverse }
636 output << n_("%{highlight}%{count} plugin failed to load%{highlight}: use %{bold}%{command}%{bold} to see why",
637 "%{highlight}%{count} plugins failed to load%{highlight}: use %{bold}%{command}%{bold} to see why",
639 { :count => @failed.length, :highlight => Reverse,
640 :bold => Bold, :command => "help failed plugins"}
646 # return list of help topics (plugin names)
649 @failures_shown = true
661 # return help for +topic+ (call associated plugin's help method)
664 when /fail(?:ed)?\s*plugins?.*(trace(?:back)?s?)?/
665 # debug "Failures: #{@failed.inspect}"
666 return _("no plugins failed to load") if @failed.empty?
667 return @failed.collect { |p|
668 _('%{highlight}%{plugin}%{highlight} in %{dir} failed with error %{exception}: %{reason}') % {
669 :highlight => Bold, :plugin => p[:name], :dir => p[:dir],
670 :exception => p[:reason].class, :reason => p[:reason],
671 } + if $1 && !p[:reason].backtrace.empty?
672 _('at %{backtrace}') % {:backtrace => p[:reason].backtrace.join(', ')}
677 when /ignored?\s*plugins?/
678 return _('no plugins were ignored') if @ignored.empty?
682 reason = p[:loaded] ? _('overruled by previous') : _(p[:reason].to_s)
683 ((tmp[p[:dir]] ||= Hash.new)[reason] ||= Array.new).push(p[:name])
686 return tmp.map do |dir, reasons|
687 # FIXME get rid of these string concatenations to make gettext easier
688 s = reasons.map { |r, list|
689 list.map { |_| _.sub(/\.rb$/, '') }.join(', ') + " (#{r})"
693 when /^(\S+)\s*(.*)$/
697 # Let's see if we can match a plugin by the given name
698 (core_modules + plugins).each { |p|
699 next unless p.name == key
701 return p.help(key, params)
702 rescue Exception => err
703 #rescue TimeoutError, StandardError, NameError, SyntaxError => err
704 error report_error("#{p.botmodule_class} #{p.name} help() failed:", err)
708 # Nope, let's see if it's a command, and ask for help at the corresponding botmodule
710 if commands.has_key?(k)
711 p = commands[k][:botmodule]
713 return p.help(key, params)
714 rescue Exception => err
715 #rescue TimeoutError, StandardError, NameError, SyntaxError => err
716 error report_error("#{p.botmodule_class} #{p.name} help() failed:", err)
723 # see if each plugin handles +method+, and if so, call it, passing
724 # +message+ as a parameter
725 def delegate(method, *args)
726 # debug "Delegating #{method.inspect}"
728 if method.match(DEFAULT_DELEGATE_PATTERNS)
729 debug "fast-delegating #{method}"
731 debug "no-one to delegate to" unless @delegate_list.has_key?(m)
732 return [] unless @delegate_list.has_key?(m)
733 @delegate_list[m].each { |p|
735 ret.push p.send(method, *args)
736 rescue Exception => err
737 raise if err.kind_of?(SystemExit)
738 error report_error("#{p.botmodule_class} #{p.name} #{method}() failed:", err)
739 raise if err.kind_of?(BDB::Fatal)
743 debug "slow-delegating #{method}"
744 (core_modules + plugins).each { |p|
745 if(p.respond_to? method)
747 # debug "#{p.botmodule_class} #{p.name} responds"
748 ret.push p.send(method, *args)
749 rescue Exception => err
750 raise if err.kind_of?(SystemExit)
751 error report_error("#{p.botmodule_class} #{p.name} #{method}() failed:", err)
752 raise if err.kind_of?(BDB::Fatal)
758 # debug "Finished delegating #{method.inspect}"
761 # see if we have a plugin that wants to handle this message, if so, pass
762 # it to the plugin and return true, otherwise false
764 # debug "Delegating privmsg #{m.message.inspect} from #{m.source} to #{m.replyto} with pluginkey #{m.plugin.inspect}"
765 return unless m.plugin
767 if commands.has_key?(k)
768 p = commands[k][:botmodule]
769 a = commands[k][:auth]
770 # We check here for things that don't check themselves
771 # (e.g. mapped things)
772 # debug "Checking auth ..."
773 if a.nil? || @bot.auth.allow?(a, m.source, m.replyto)
774 # debug "Checking response ..."
775 if p.respond_to?("privmsg")
777 # debug "#{p.botmodule_class} #{p.name} responds"
779 rescue Exception => err
780 raise if err.kind_of?(SystemExit)
781 error report_error("#{p.botmodule_class} #{p.name} privmsg() failed:", err)
782 raise if err.kind_of?(BDB::Fatal)
784 # debug "Successfully delegated #{m.message}"
787 # debug "#{p.botmodule_class} #{p.name} is registered, but it doesn't respond to privmsg()"
790 # debug "#{p.botmodule_class} #{p.name} is registered, but #{m.source} isn't allowed to call #{m.plugin.inspect} on #{m.replyto}"
793 # debug "Finished delegating privmsg with key #{m.plugin.inspect}" + ( pl.empty? ? "" : " to #{pl.values.first[:botmodule].botmodule_class}s" )
795 # debug "Finished delegating privmsg with key #{m.plugin.inspect}"
799 # Returns the only PluginManagerClass instance
801 return PluginManagerClass.instance