- # base class for all rbot plugins
- # certain methods will be called if they are provided, if you define one of
- # the following methods, it will be called as appropriate:
- #
- # map(template, options)::
- # map is the new, cleaner way to respond to specific message formats
- # without littering your plugin code with regexps. 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,
- # end
- #
- # To activate your maps, you simply register them
- # plugin.register_maps
- # This also sets the privmsg handler to use the map lookups for
- # handling messages. You can still use listen(), kick() etc methods
- #
- # 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.
- #
- # privmsg(PrivMessage)::
- # called for a PRIVMSG if the first word matches one
- # the plugin register()d for. Use m.plugin to get
- # that word and m.params for the rest of the message,
- # if applicable.
- #
- # kick(KickMessage)::
- # Called when a user (or the bot) is kicked from a
- # channel the bot is in.
- #
- # 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
- # topic(TopicMessage)::
- # Called when a user (or the bot) changes a channel
- # topic
- #
- # connect():: Called when a server is joined successfully, but
- # before autojoin channels are joined (no params)
- #
- # 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
- class Plugin
- attr_reader :bot # the associated bot
- # initialise your plugin. Always call super if you override this method,
- # as important variables are set up for you
+=begin rdoc
+ 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
+=end
+
+ class BotModule
+ # the associated bot
+ attr_reader :bot
+
+ # the plugin registry
+ attr_reader :registry
+
+ # the message map handler
+ attr_reader :handler
+
+ # 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
+ #