summaryrefslogtreecommitdiff
path: root/lib/rbot
diff options
context:
space:
mode:
authorGiuseppe Bilotta <giuseppe.bilotta@gmail.com>2007-09-12 17:31:03 +0000
committerGiuseppe Bilotta <giuseppe.bilotta@gmail.com>2007-09-12 17:31:03 +0000
commit9dc851fd90cd6657a5f1c1f89e968a61f4c07a0f (patch)
treea2014bf0c29868c19c00cf310c98ad513bbedd27 /lib/rbot
parentb28d910db82ac1e8933bf6a7b0f52d28a293fbb6 (diff)
rdocument Irc::Plugins::BotModule
Diffstat (limited to 'lib/rbot')
-rw-r--r--lib/rbot/plugins.rb118
1 files changed, 93 insertions, 25 deletions
diff --git a/lib/rbot/plugins.rb b/lib/rbot/plugins.rb
index 7bec55ae..96f61efc 100644
--- a/lib/rbot/plugins.rb
+++ b/lib/rbot/plugins.rb
@@ -12,17 +12,24 @@ module Irc
module Plugins
require 'rbot/messagemapper'
-=begin
- 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:
+=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. The difference
- between map and map! is that map! will not register the new command
- as an alternative name for the plugin.
+ 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:
@@ -54,9 +61,11 @@ module Plugins
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
+ 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
@@ -74,7 +83,7 @@ module Plugins
privmsg(PrivMessage)::
Called for a PRIVMSG if the first word matches one
- the plugin register()d for. Use m.plugin to get
+ the plugin #register()ed for. Use m.plugin to get
that word and m.params for the rest of the message,
if applicable.
@@ -100,7 +109,7 @@ module Plugins
Called when a user (or the bot) changes a channel
topic
- connect():: Called when a server is joined successfully, but
+ connect:: Called when a server is joined successfully, but
before autojoin channels are joined (no params)
set_language(String)::
@@ -118,8 +127,25 @@ module Plugins
class BotModule
attr_reader :bot # the associated bot
- # initialise your bot module. Always call super if you override this method,
- # as important variables are set up for you
+ # 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 BotRegistryAccessor 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
+ #
def initialize
@manager = Plugins::manager
@bot = @manager.bot
@@ -135,47 +161,71 @@ module Plugins
end
end
+ # Returns the symbol :BotModule
def botmodule_class
:BotModule
end
+ # Method called to flush the registry, thus ensuring that the botmodule's permanent
+ # data is committed to disk
+ #
def flush_registry
# debug "Flushing #{@registry}"
@registry.flush
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.
+ #
def cleanup
# debug "Closing #{@registry}"
@registry.close
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.
+ #
def handle(m)
@handler.handle(m)
end
+ # Signal to other BotModules that an even happened.
+ #
def call_event(ev, *args)
@bot.plugins.delegate('event_' + ev.to_s.gsub(/[^\w\?!]+/, '_'), *args)
end
+ # call-seq: map(template, options)
+ #
+ # This is the preferred way to register the BotModule so that it
+ # responds to appropriately-formed messages on Irc.
+ #
def map(*args)
@handler.map(self, *args)
# register this map
name = @handler.last.items[0]
self.register name, :auth => nil
unless self.respond_to?('privmsg')
- def self.privmsg(m)
+ def self.privmsg(m) #:nodoc:
handle(m)
end
end
end
+ # call-seq: map!(template, options)
+ #
+ # This is the same as map but doesn't register the new command
+ # as an alternative name for the plugin.
+ #
def map!(*args)
@handler.map(self, *args)
# register this map
name = @handler.last.items[0]
self.register name, :auth => nil, :hidden => true
unless self.respond_to?('privmsg')
- def self.privmsg(m)
+ def self.privmsg(m) #:nodoc:
handle(m)
end
end
@@ -200,23 +250,23 @@ module Plugins
[name, cmd].compact.join("::")
end
- # return an identifier for this plugin, defaults to a list of the message
+ # Return an identifier for this plugin, defaults to a list of the message
# prefixes handled (used for error messages etc)
def name
self.class.to_s.downcase.sub(/^#<module:.*?>::/,"").sub(/(plugin|module)?$/,"")
end
- # just calls name
+ # Just calls name
def to_s
name
end
- # intern the name
+ # Intern the name
def to_sym
self.name.to_sym
end
- # return a help string for your module. for complex modules, you may wish
+ # 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
@@ -225,9 +275,14 @@ module Plugins
"no help"
end
- # register the plugin as a handler for messages prefixed +name+
- # this can be called multiple times for a plugin to handle multiple
- # message prefixes
+ # 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.
+ #
def register(cmd, opts={})
raise ArgumentError, "Second argument must be a hash!" unless opts.kind_of?(Hash)
who = @manager.who_handles?(cmd)
@@ -243,20 +298,33 @@ module Plugins
@botmodule_triggers << cmd unless opts.fetch(:hidden, false)
end
- # default usage method provided as a utility for simple plugins. The
+ # Default usage method provided as a utility for simple plugins. The
# MessageMapper uses 'usage' as its default fallback method.
+ #
def usage(m, params = {})
m.reply(_("incorrect usage, ask for help using '%{command}'") % {:command => "#{@bot.nick}: help #{m.plugin}"})
end
end
+ # A CoreBotModule is a BotModule that provides core functionality.
+ #
+ # This class should not be used by user plugins, as it's reserved for system
+ # plugins such as the ones that handle authentication, configuration and basic
+ # functionality.
+ #
class CoreBotModule < BotModule
def botmodule_class
:CoreBotModule
end
end
+ # A Plugin is a BotModule that provides additional functionality.
+ #
+ # A user-defined plugin should subclass this, and then define any of the
+ # methods described in the documentation for BotModule to handle interaction
+ # with Irc events.
+ #
class Plugin < BotModule
def botmodule_class
:Plugin