Class | Irc::Bot::Plugins::BotModule |
In: |
lib/rbot/plugins.rb
|
Parent: | Object |
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, 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: plugin.map 'karmastats', :action => 'karma_stats' # while in the plugin... def karma_stats(m, params) m.reply "..." end # the default action is the first component plugin.map 'karma' # attributes can be pulled out of the match string plugin.map 'karma for :key' plugin.map 'karma :key' # while in the plugin... def karma(m, params) item = params[:key] m.reply 'karma for #{item}' end # you can setup defaults, to make parameters optional plugin.map 'karma :key', :defaults => {:key => 'defaultvalue'} # the default auth check is also against the first component # but that can be changed plugin.map 'karmastats', :auth => 'karma' # maps can be restricted to public or private message: 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 differentiate them, use message.kind_of? It‘ll be either a PrivMessage, NoticeMessage, KickMessage, QuitMessage, PartMessage, JoinMessage, NickMessage, etc. |
ctcp_listen(UserMessage): | Called for all messages that contain a CTCP command. Use message.ctcp to get the CTCP command, and message.message to get the parameter string. To reply, 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()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 |
part(PartMessage): | Called when a user (or the bot) parts a channel |
quit(QuitMessage): | Called when a user (or the bot) quits IRC |
nick(NickMessage): | Called when a user (or the bot) changes Nick |
modechange(ModeChangeMessage): | Called when a User or Channel mode is changed |
topic(TopicMessage): | Called when a user (or the bot) changes a channel topic |
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): | Called when the user sets a new language whose name is the given String |
save: | Called when you are required to save your plugin‘s state, if you maintain data between sessions |
cleanup: | called before your plugin is "unloaded", prior to a plugin reload or bot quit - close any open files/connections or flush caches here |
bot | [R] | the associated bot |
handler | [R] | the message map handler |
registry | [R] | the plugin registry |
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 |
# File lib/rbot/plugins.rb, line 182 182: def initialize 183: @manager = Plugins::manager 184: @bot = @manager.bot 185: @priority = nil 186: 187: @botmodule_triggers = Array.new 188: 189: @handler = MessageMapper.new(self) 190: @registry = Registry::Accessor.new(@bot, self.class.to_s.gsub(/^.*::/, "")) 191: 192: @manager.add_botmodule(self) 193: if self.respond_to?('set_language') 194: self.set_language(@bot.lang.language) 195: end 196: end
Signal to other BotModules that an even happened.
# File lib/rbot/plugins.rb, line 236 236: def call_event(ev, *args) 237: @bot.plugins.delegate('event_' + ev.to_s.gsub(/[^\w\?!]+/, '_'), *(args.push Hash.new)) 238: 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.
# File lib/rbot/plugins.rb, line 221 221: def cleanup 222: # debug "Closing #{@registry}" 223: @registry.close 224: end
Sets the default auth for command path cmd to val on channel chan: usually chan is either "*" for everywhere, public and private (in which case it can be omitted) or "?" for private communications
# File lib/rbot/plugins.rb, line 277 277: def default_auth(cmd, val, chan="*") 278: case cmd 279: when "*", "" 280: c = nil 281: else 282: c = cmd 283: end 284: Auth::defaultbotuser.set_default_permission(propose_default_path(c), val) 285: end
Auxiliary method called by map and map!
# File lib/rbot/plugins.rb, line 259 259: def do_map(silent, *args) 260: @handler.map(self, *args) 261: # register this map 262: map = @handler.last 263: name = map.items[0] 264: self.register name, :auth => nil, :hidden => silent 265: @manager.register_map(self, map) 266: unless self.respond_to?('privmsg') 267: def self.privmsg(m) #:nodoc: 268: handle(m) 269: end 270: end 271: end
Method called to flush the registry, thus ensuring that the botmodule‘s permanent data is committed to disk
# File lib/rbot/plugins.rb, line 212 212: def flush_registry 213: # debug "Flushing #{@registry}" 214: @registry.flush 215: 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.
# File lib/rbot/plugins.rb, line 230 230: def handle(m) 231: @handler.handle(m) 232: end
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 return the correct help for the prefix requested
# File lib/rbot/plugins.rb, line 313 313: def help(plugin, topic) 314: "no help" 315: end
Return an identifier for this plugin, defaults to a list of the message prefixes handled (used for error messages etc)
# File lib/rbot/plugins.rb, line 294 294: def name 295: self.class.to_s.downcase.sub(/^#<module:.*?>::/,"").sub(/(plugin|module)?$/,"") 296: end
Gets the default command path which would be given to command cmd
# File lib/rbot/plugins.rb, line 288 288: def propose_default_path(cmd) 289: [name, cmd].compact.join("::") 290: end
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.
# File lib/rbot/plugins.rb, line 325 325: def register(cmd, opts={}) 326: raise ArgumentError, "Second argument must be a hash!" unless opts.kind_of?(Hash) 327: who = @manager.who_handles?(cmd) 328: if who 329: raise "Command #{cmd} is already handled by #{who.botmodule_class} #{who}" if who != self 330: return 331: end 332: if opts.has_key?(:auth) 333: @manager.register(self, cmd, opts[:auth]) 334: else 335: @manager.register(self, cmd, propose_default_path(cmd)) 336: end 337: @botmodule_triggers << cmd unless opts.fetch(:hidden, false) 338: end
Default usage method provided as a utility for simple plugins. The MessageMapper uses ‘usage’ as its default fallback method.
# File lib/rbot/plugins.rb, line 343 343: def usage(m, params = {}) 344: if params[:failures].respond_to? :find 345: friendly = params[:failures].find do |f| 346: f.kind_of? MessageMapper::FriendlyFailure 347: end 348: if friendly 349: m.reply friendly.friendly 350: return 351: end 352: end 353: m.reply(_("incorrect usage, ask for help using '%{command}'") % {:command => "#{@bot.nick}: help #{m.plugin}"}) 354: end