-
Notifications
You must be signed in to change notification settings - Fork 38
Cardinal Events
Cardinal supports events as of version 2.0. The following core IRC events are built-in:
-
irc.raw
- 2 arguments (command, message) -- Available since v2.2.0 -
irc.invite
- 2 arguments (inviter, channel) -
irc.privmsg
- 3 arguments (sender, channel, message) -
irc.notice
- 3 arguments (sender, channel, message) -
irc.nick
- 2 arguments (changer, new nick) -
irc.mode
- 3 arguments(setter, channel, mode) -
irc.join
- 2 arguments (joiner, channel) -
irc.part
- 3 arguments (leaver, channel, message) -
irc.kick
- 4 arguments (kicker, channel, kicked nick, message) -
irc.quit
- 2 arguments (quitter, message)
Use the cardinal.decorators.event(event_name)
decorator to register an event listener. The listener will be invoked with cardinal
as the first argument followed by the event-specific arguments.
Except for "new nick" sent by the irc.nick
event and "kicked nick" sent by the irc.kick
event, the user arguments are the same as for commands: A cardinal.bot.user_info
tuple: (nick, user, vhost)
.
from cardinal.decorators import event
class InviteJoinPlugin(object):
@event('irc.invite')
def join_channel(self, cardinal, user, channel):
cardinal.join(channel)
def setup(cardinal):
return InviteJoinPlugin()
Registering events is easy too. Simply call EventManager.register()
(accessible from within an event handler or command method as cardinal.event_manager.register()
with the name of your event, and the number of parameters that will be passed in when you fire the event. Preferably, your event should be prefixed with the name of your plugin, followed by a period. For example urls.match
for a urls
plugin that found a matching URL. For example:
class URLsPlugin(object):
def __init__(self, cardinal):
"""Register our event"""
cardinal.event_manager.register('urls.match', 1)
def close(self, cardinal):
"Remove the event"""
cardinal.event_manager.remove('urls.match')
It is important to remove the event in the close
method of your plugin. If you don't, and your plugin is reloaded, you will not be able to re-register the event.
Once the event is registered, you may call cardinal.event_manager.fire(name, *params)
, passing the name of your event as the first parameter, followed by your event-specific parameters.
cardinal.plugins.EventManager.fire()
returns a boolean denoting whether an event listener picked up the event. Listeners which raise cardinal.exceptions.EventRejectedMessage
will not be counted. This behavior is used by the urls
plugin to determine whether a service-specific URL handler has picked up the message, for example.