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.
207 @handler.map(self, *args)
209 name = @handler.last.items[0]
210 self.register name, :auth => nil
211 unless self.respond_to?('privmsg')
212 def self.privmsg(m) #:nodoc:
218 # call-seq: map!(template, options)
220 # This is the same as map but doesn't register the new command
221 # as an alternative name for the plugin.
224 @handler.map(self, *args)
226 name = @handler.last.items[0]
227 self.register name, :auth => nil, :hidden => true
228 unless self.respond_to?('privmsg')
229 def self.privmsg(m) #:nodoc:
235 # Sets the default auth for command path _cmd_ to _val_ on channel _chan_:
236 # usually _chan_ is either "*" for everywhere, public and private (in which
237 # case it can be omitted) or "?" for private communications
239 def default_auth(cmd, val, chan="*")
246 Auth::defaultbotuser.set_default_permission(propose_default_path(c), val)
249 # Gets the default command path which would be given to command _cmd_
250 def propose_default_path(cmd)
251 [name, cmd].compact.join("::")
254 # Return an identifier for this plugin, defaults to a list of the message
255 # prefixes handled (used for error messages etc)
257 self.class.to_s.downcase.sub(/^#<module:.*?>::/,"").sub(/(plugin|module)?$/,"")
270 # Return a help string for your module. For complex modules, you may wish
271 # to break your help into topics, and return a list of available topics if
272 # +topic+ is nil. +plugin+ is passed containing the matching prefix for
273 # this message - if your plugin handles multiple prefixes, make sure you
274 # return the correct help for the prefix requested
275 def help(plugin, topic)
279 # Register the plugin as a handler for messages prefixed _cmd_.
281 # This can be called multiple times for a plugin to handle multiple message
284 # This command is now superceded by the #map() command, which should be used
285 # instead whenever possible.
287 def register(cmd, opts={})
288 raise ArgumentError, "Second argument must be a hash!" unless opts.kind_of?(Hash)
289 who = @manager.who_handles?(cmd)
291 raise "Command #{cmd} is already handled by #{who.botmodule_class} #{who}" if who != self
294 if opts.has_key?(:auth)
295 @manager.register(self, cmd, opts[:auth])
297 @manager.register(self, cmd, propose_default_path(cmd))
299 @botmodule_triggers << cmd unless opts.fetch(:hidden, false)
302 # Default usage method provided as a utility for simple plugins. The
303 # MessageMapper uses 'usage' as its default fallback method.
305 def usage(m, params = {})
306 m.reply(_("incorrect usage, ask for help using '%{command}'") % {:command => "#{@bot.nick}: help #{m.plugin}"})
311 # A CoreBotModule is a BotModule that provides core functionality.
313 # This class should not be used by user plugins, as it's reserved for system
314 # plugins such as the ones that handle authentication, configuration and basic
317 class CoreBotModule < BotModule
323 # A Plugin is a BotModule that provides additional functionality.
325 # A user-defined plugin should subclass this, and then define any of the
326 # methods described in the documentation for BotModule to handle interaction
329 class Plugin < BotModule
335 # Singleton to manage multiple plugins and delegate messages to them for
337 class PluginManagerClass
340 attr_reader :botmodules
342 # This is the list of patterns commonly delegated to plugins.
343 # A fast delegation lookup is enabled for them.
344 DEFAULT_DELEGATE_PATTERNS = %r{^(?:
346 listen|ctcp_listen|privmsg|unreplied|
348 save|cleanup|flush_registry|
354 :CoreBotModule => [],
358 @names_hash = Hash.new
359 @commandmappers = Hash.new
360 @delegate_list = Hash.new { |h, k|
372 # Reset lists of botmodules
373 def reset_botmodule_lists
374 @botmodules[:CoreBotModule].clear
375 @botmodules[:Plugin].clear
377 @commandmappers.clear
378 @failures_shown = false
381 # Associate with bot _bot_
382 def bot_associate(bot)
383 reset_botmodule_lists
387 # Returns the botmodule with the given _name_
389 @names_hash[name.to_sym]
392 # Returns +true+ if _cmd_ has already been registered as a command
393 def who_handles?(cmd)
394 return nil unless @commandmappers.has_key?(cmd.to_sym)
395 return @commandmappers[cmd.to_sym][:botmodule]
398 # Registers botmodule _botmodule_ with command _cmd_ and command path _auth_path_
399 def register(botmodule, cmd, auth_path)
400 raise TypeError, "First argument #{botmodule.inspect} is not of class BotModule" unless botmodule.kind_of?(BotModule)
401 @commandmappers[cmd.to_sym] = {:botmodule => botmodule, :auth => auth_path}
404 def add_botmodule(botmodule)
405 raise TypeError, "Argument #{botmodule.inspect} is not of class BotModule" unless botmodule.kind_of?(BotModule)
406 kl = botmodule.botmodule_class
407 if @names_hash.has_key?(botmodule.to_sym)
408 case self[botmodule].botmodule_class
410 raise "#{kl} #{botmodule} already registered!"
412 raise "#{self[botmodule].botmodule_class} #{botmodule} already registered, cannot re-register as #{kl}"
415 @botmodules[kl] << botmodule
416 @names_hash[botmodule.to_sym] = botmodule
419 # Returns an array of the loaded plugins
421 @botmodules[:CoreBotModule]
424 # Returns an array of the loaded plugins
429 # Returns a hash of the registered message prefixes and associated
435 # Makes a string of error _err_ by adding text _str_
436 def report_error(str, err)
437 ([str, err.inspect] + err.backtrace).join("\n")
440 # This method is the one that actually loads a module from the
443 # _desc_ is a simple description of what we are loading (plugin/botmodule/whatever)
445 # It returns the Symbol :loaded on success, and an Exception
448 def load_botmodule_file(fname, desc=nil)
449 # create a new, anonymous module to "house" the plugin
450 # the idea here is to prevent namespace pollution. perhaps there
452 plugin_module = Module.new
454 desc = desc.to_s + " " if desc
457 plugin_string = IO.readlines(fname).join("")
458 debug "loading #{desc}#{fname}"
459 plugin_module.module_eval(plugin_string, fname)
461 rescue Exception => err
462 # rescue TimeoutError, StandardError, NameError, LoadError, SyntaxError => err
463 error report_error("#{desc}#{fname} load failed", err)
464 bt = err.backtrace.select { |line|
465 line.match(/^(\(eval\)|#{fname}):\d+/)
468 el.gsub(/^\(eval\)(:\d+)(:in `.*')?(:.*)?/) { |m|
472 msg = err.to_str.gsub(/^\(eval\)(:\d+)(:in `.*')?(:.*)?/) { |m|
475 newerr = err.class.new(msg)
476 newerr.set_backtrace(bt)
480 private :load_botmodule_file
482 # add one or more directories to the list of directories to
483 # load botmodules from
485 # TODO find a way to specify necessary plugins which _must_ be loaded
487 def add_botmodule_dir(*dirlist)
489 debug "Botmodule loading path: #{@dirs.join(', ')}"
492 def clear_botmodule_dirs
494 debug "Botmodule loading path cleared"
497 # load plugins from pre-assigned list of directories
505 @bot.config['plugins.blacklist'].each { |p|
507 processed[pn.intern] = :blacklisted
512 if(FileTest.directory?(dir))
516 next if(file =~ /^\./)
518 if processed.has_key?(file.intern)
519 @ignored << {:name => file, :dir => dir, :reason => processed[file.intern]}
523 if(file =~ /^(.+\.rb)\.disabled$/)
524 # GB: Do we want to do this? This means that a disabled plugin in a directory
525 # will disable in all subsequent directories. This was probably meant
526 # to be used before plugins.blacklist was implemented, so I think
527 # we don't need this anymore
528 processed[$1.intern] = :disabled
529 @ignored << {:name => $1, :dir => dir, :reason => processed[$1.intern]}
533 next unless(file =~ /\.rb$/)
535 did_it = load_botmodule_file("#{dir}/#{file}", "plugin")
538 processed[file.intern] = did_it
540 @failed << { :name => file, :dir => dir, :reason => did_it }
546 debug "finished loading plugins: #{status(true)}"
547 (core_modules + plugins).each { |p|
548 p.methods.grep(DEFAULT_DELEGATE_PATTERNS).each { |m|
549 @delegate_list[m.intern] << p
554 # call the save method for each active plugin
556 delegate 'flush_registry'
560 # call the cleanup method for each active plugin
563 reset_botmodule_lists
566 # drop all plugins and rescan plugins on disk
567 # calls save and cleanup for each plugin before dropping them
574 def status(short=false)
576 if self.core_length > 0
578 output << n_("%{count} core module loaded", "%{count} core modules loaded",
579 self.core_length) % {:count => self.core_length}
581 output << n_("%{count} core module: %{list}",
582 "%{count} core modules: %{list}", self.core_length) %
583 { :count => self.core_length,
584 :list => core_modules.collect{ |p| p.name}.sort.join(", ") }
587 output << _("no core botmodules loaded")
589 # Active plugins first
592 output << n_("%{count} plugin loaded", "%{count} plugins loaded",
593 self.length) % {:count => self.length}
595 output << n_("%{count} plugin: %{list}",
596 "%{count} plugins: %{list}", self.length) %
597 { :count => self.length,
598 :list => plugins.collect{ |p| p.name}.sort.join(", ") }
601 output << "no plugins active"
603 # Ignored plugins next
604 unless @ignored.empty? or @failures_shown
606 output << n_("%{highlight}%{count} plugin ignored%{highlight}",
607 "%{highlight}%{count} plugins ignored%{highlight}",
609 { :count => @ignored.length, :highlight => Underline }
611 output << n_("%{highlight}%{count} plugin ignored%{highlight}: use %{bold}%{command}%{bold} to see why",
612 "%{highlight}%{count} plugins ignored%{highlight}: use %{bold}%{command}%{bold} to see why",
614 { :count => @ignored.length, :highlight => Underline,
615 :bold => Bold, :command => "help ignored plugins"}
618 # Failed plugins next
619 unless @failed.empty? or @failures_shown
621 output << n_("%{highlight}%{count} plugin failed to load%{highlight}",
622 "%{highlight}%{count} plugins failed to load%{highlight}",
624 { :count => @failed.length, :highlight => Reverse }
626 output << n_("%{highlight}%{count} plugin failed to load%{highlight}: use %{bold}%{command}%{bold} to see why",
627 "%{highlight}%{count} plugins failed to load%{highlight}: use %{bold}%{command}%{bold} to see why",
629 { :count => @failed.length, :highlight => Reverse,
630 :bold => Bold, :command => "help failed plugins"}
636 # return list of help topics (plugin names)
639 @failures_shown = true
651 # return help for +topic+ (call associated plugin's help method)
654 when /fail(?:ed)?\s*plugins?.*(trace(?:back)?s?)?/
655 # debug "Failures: #{@failed.inspect}"
656 return _("no plugins failed to load") if @failed.empty?
657 return @failed.collect { |p|
658 _('%{highlight}%{plugin}%{highlight} in %{dir} failed with error %{exception}: %{reason}') % {
659 :highlight => Bold, :plugin => p[:name], :dir => p[:dir],
660 :exception => p[:reason].class, :reason => p[:reason],
661 } + if $1 && !p[:reason].backtrace.empty?
662 _('at %{backtrace}') % {:backtrace => p[:reason].backtrace.join(', ')}
667 when /ignored?\s*plugins?/
668 return _('no plugins were ignored') if @ignored.empty?
672 reason = p[:loaded] ? _('overruled by previous') : _(p[:reason].to_s)
673 ((tmp[p[:dir]] ||= Hash.new)[reason] ||= Array.new).push(p[:name])
676 return tmp.map do |dir, reasons|
677 # FIXME get rid of these string concatenations to make gettext easier
678 s = reasons.map { |r, list|
679 list.map { |_| _.sub(/\.rb$/, '') }.join(', ') + " (#{r})"
683 when /^(\S+)\s*(.*)$/
687 # Let's see if we can match a plugin by the given name
688 (core_modules + plugins).each { |p|
689 next unless p.name == key
691 return p.help(key, params)
692 rescue Exception => err
693 #rescue TimeoutError, StandardError, NameError, SyntaxError => err
694 error report_error("#{p.botmodule_class} #{p.name} help() failed:", err)
698 # Nope, let's see if it's a command, and ask for help at the corresponding botmodule
700 if commands.has_key?(k)
701 p = commands[k][:botmodule]
703 return p.help(key, params)
704 rescue Exception => err
705 #rescue TimeoutError, StandardError, NameError, SyntaxError => err
706 error report_error("#{p.botmodule_class} #{p.name} help() failed:", err)
713 # see if each plugin handles +method+, and if so, call it, passing
714 # +message+ as a parameter
715 def delegate(method, *args)
716 # debug "Delegating #{method.inspect}"
718 if method.match(DEFAULT_DELEGATE_PATTERNS)
719 debug "fast-delegating #{method}"
721 debug "no-one to delegate to" unless @delegate_list.has_key?(m)
722 return [] unless @delegate_list.has_key?(m)
723 @delegate_list[m].each { |p|
725 ret.push p.send(method, *args)
726 rescue Exception => err
727 raise if err.kind_of?(SystemExit)
728 error report_error("#{p.botmodule_class} #{p.name} #{method}() failed:", err)
729 raise if err.kind_of?(BDB::Fatal)
733 debug "slow-delegating #{method}"
734 (core_modules + plugins).each { |p|
735 if(p.respond_to? method)
737 # debug "#{p.botmodule_class} #{p.name} responds"
738 ret.push p.send(method, *args)
739 rescue Exception => err
740 raise if err.kind_of?(SystemExit)
741 error report_error("#{p.botmodule_class} #{p.name} #{method}() failed:", err)
742 raise if err.kind_of?(BDB::Fatal)
748 # debug "Finished delegating #{method.inspect}"
751 # see if we have a plugin that wants to handle this message, if so, pass
752 # it to the plugin and return true, otherwise false
754 # debug "Delegating privmsg #{m.message.inspect} from #{m.source} to #{m.replyto} with pluginkey #{m.plugin.inspect}"
755 return unless m.plugin
757 if commands.has_key?(k)
758 p = commands[k][:botmodule]
759 a = commands[k][:auth]
760 # We check here for things that don't check themselves
761 # (e.g. mapped things)
762 # debug "Checking auth ..."
763 if a.nil? || @bot.auth.allow?(a, m.source, m.replyto)
764 # debug "Checking response ..."
765 if p.respond_to?("privmsg")
767 # debug "#{p.botmodule_class} #{p.name} responds"
769 rescue Exception => err
770 raise if err.kind_of?(SystemExit)
771 error report_error("#{p.botmodule_class} #{p.name} privmsg() failed:", err)
772 raise if err.kind_of?(BDB::Fatal)
774 # debug "Successfully delegated #{m.message}"
777 # debug "#{p.botmodule_class} #{p.name} is registered, but it doesn't respond to privmsg()"
780 # debug "#{p.botmodule_class} #{p.name} is registered, but #{m.source} isn't allowed to call #{m.plugin.inspect} on #{m.replyto}"
783 # debug "Finished delegating privmsg with key #{m.plugin.inspect}" + ( pl.empty? ? "" : " to #{pl.values.first[:botmodule].botmodule_class}s" )
785 # debug "Finished delegating privmsg with key #{m.plugin.inspect}"
789 # Returns the only PluginManagerClass instance
791 return PluginManagerClass.instance