require 'singleton'
module Irc
- BotConfig.register BotConfigArrayValue.new('plugins.blacklist',
+class Bot
+ Config.register Config::ArrayValue.new('plugins.blacklist',
:default => [], :wizard => false, :requires_rescan => true,
:desc => "Plugins that should not be loaded")
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:
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
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.
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
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)::
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 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
+ #
def initialize
@manager = Plugins::manager
@bot = @manager.bot
@botmodule_triggers = Array.new
@handler = MessageMapper.new(self)
- @registry = BotRegistryAccessor.new(@bot, self.class.to_s.gsub(/^.*::/, ""))
+ @registry = Registry::Accessor.new(@bot, self.class.to_s.gsub(/^.*::/, ""))
@manager.add_botmodule(self)
if self.respond_to?('set_language')
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)
- handle(m)
- end
- end
+ do_map(false, *args)
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)
+ do_map(true, *args)
+ end
+
+ # Auxiliary method called by #map and #map!
+ def do_map(silent, *args)
@handler.map(self, *args)
# register this map
- name = @handler.last.items[0]
- self.register name, :auth => nil, :hidden => true
+ map = @handler.last
+ name = map.items[0]
+ self.register name, :auth => nil, :hidden => silent
+ @manager.register_map(self, map)
unless self.respond_to?('privmsg')
- def self.privmsg(m)
+ def self.privmsg(m) #:nodoc:
handle(m)
end
end
[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
"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)
@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
include Singleton
attr_reader :bot
attr_reader :botmodules
+ attr_reader :maps
# This is the list of patterns commonly delegated to plugins.
# A fast delegation lookup is enabled for them.
@names_hash = Hash.new
@commandmappers = Hash.new
+ @maps = Hash.new
@delegate_list = Hash.new { |h, k|
h[k] = Array.new
}
bot_associate(nil)
end
+ def inspect
+ ret = self.to_s[0..-2]
+ ret << ' corebotmodules='
+ ret << @botmodules[:CoreBotModule].map { |m|
+ m.name
+ }.inspect
+ ret << ' plugins='
+ ret << @botmodules[:Plugin].map { |m|
+ m.name
+ }.inspect
+ ret << ">"
+ end
+
# Reset lists of botmodules
def reset_botmodule_lists
@botmodules[:CoreBotModule].clear
@botmodules[:Plugin].clear
@names_hash.clear
@commandmappers.clear
+ @maps.clear
@failures_shown = false
end
@commandmappers[cmd.to_sym] = {:botmodule => botmodule, :auth => auth_path}
end
+ # Registers botmodule _botmodule_ with map _map_. This adds the map to the #maps hash
+ # which has three keys:
+ #
+ # botmodule:: the associated botmodule
+ # auth:: an array of auth keys checked by the map; the first is the full_auth_path of the map
+ # map:: the actual MessageTemplate object
+ #
+ #
+ def register_map(botmodule, map)
+ raise TypeError, "First argument #{botmodule.inspect} is not of class BotModule" unless botmodule.kind_of?(BotModule)
+ @maps[map.template] = { :botmodule => botmodule, :auth => [map.options[:full_auth_path]], :map => map }
+ end
+
def add_botmodule(botmodule)
raise TypeError, "Argument #{botmodule.inspect} is not of class BotModule" unless botmodule.kind_of?(BotModule)
kl = botmodule.botmodule_class
key = $1
params = $2
- # Let's see if we can match a plugin by the given name
+ # Let's see if we can match a plugin by the given name
(core_modules + plugins).each { |p|
- next unless p.name == key
+ next unless p.name == key
begin
return p.help(key, params)
rescue Exception => err
end
}
- # Nope, let's see if it's a command, and ask for help at the corresponding botmodule
+ # Nope, let's see if it's a command, and ask for help at the corresponding botmodule
k = key.to_sym
if commands.has_key?(k)
p = commands[k][:botmodule]
end
end
+end
projects / user / henk / code / ruby / rbot.git / blobdiff