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)

Consuming Events

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()

Creating events

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.

Refusing events

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.