Plugin_object

By virtue of inheriting from the callbacks.Plugin class, the supybot plugins get a number of useful methods 'for free' by default. This page will document the built-in plugin methods, as well as other interesting bits of the Plugin architecture.

• Plugin methods
  • doError()
  • doJoin()
  • doKick()
  • doMode()
  • doNick()
  • doPart()
  • doPrivmsg()
  • doQuit()
  • doTopic()
  • Numeric IRC message handlers
  • die()
  • outFilter()
  • inFilter()
  • invalidCommand()
• Plugin attributes
  • Proxy

Plugin methods

doError()

doError(self, irc, msg)

TODO: needs content and example

doJoin()

doJoin(self, irc, msg)

TODO: needs content and example

doKick()

doKick(self, irc, msg)

TODO: needs content and example

doMode()

doMode(self, irc, msg)

TODO: needs content and example

doNick()

doNick(self, irc, msg)

Hook to be called on IRC NICK command (/nick) messages. The user's old nick is in msg.nick, new nick is in msg.args[0].

doPart()

doJoin(self, irc, msg)

TODO: needs content and example

doPrivmsg()

doPrivmsg(self, irc, msg)

TODO: needs content and example

doQuit()

doQuit(self, irc, msg)

TODO: needs content and example

doTopic()

doTopic(self, irc, msg)

Hoop to be called on IRC TOPIC command (/topic) messages. The new topic is in msg.args[1].

Numeric IRC message handlers

Supybot can respond to more messages than just the common named ones. In fact, you can define methods that react to numbered message that comes from the IRC server. There's a full list of the numeric replies in the IRC RFC 1459. You probably won't ever have to use any of these, but here's a quick example. A 376 message is sent at the end of the MOTD, or a 422 is sent if the MOTD is not found. So this will send a message to you when the bot connects to the server (but before the bot joins any channels). Also note that it'll give an error if if the nick doesn't exist, so we include a do401() method (No Such Nick error reply) so that it continues silently if you aren't online at the time.

do376(self, irc, msg):
    irc.queueMsg(ircmsgs.privmsg('yournick', 'Hey!  I just connected to the server!'))

do422 = do376

do401(self, irc, msg):
    pass

See also: irc.queueMsg().

die()

die(self)

Called on supybot exit or plugin unload. This is where you can stick various cleanup routines that need to be executed before your plugin dies, such as closing sockets, flushing files, etc. Make sure not to forget to call the parent's die() method as well.

Here's a simple example. Assume you have defined a method __save_state()_ which saves some plugin state. This is how you'd make sure it gets called on supybot exit or plugin unload:

def die(self):
    self._save_state()
    self.__parent.die()

outFilter()

outFilter(self, irc, msg)

Filter outgoing messages (messages sent by the bot). Expected return value is a [Msg_object].

inFilter()

inFilter(self, irc, msg)

Filter incoming messages as they're coming in. Expected return value is a [Msg_object].

invalidCommand()

invalidCommand(self, irc, msg, tokens)

This method gets called when an invalid command is issued to the bot, giving the plugin an opportunity to intercept it, and carry out its own action. The arguments it receives are irc, the [Irc_object], msg, the [Msg_object], and tokens, the tokenized command string.

If as a result of this function, the [Msg_object] is marked as 'replied to' (see irc.noReply() and irc.queueMsg() for further reference on this), then it will not propagate further. Otherwise the invalid command error will propagate to the next hook in the chain.

As a simple example, let's say you want to swallow the 'invalid command' error if someone issues a nonexistent command 'moo'. Here's what you might put into the invalidCommand method of your plugin:

def invalidCommand(self, irc, msg, tokens):
    if tokens[0] == 'moo':
        irc.noReply()

For more useful examples, see the Factoids and Dunno plugins, among others.

In order to determine the order of precedence of the plugins as far as which one will get the hook first, set the callAfter attribute of the plugin class. For example, this is what the Dunno plugin has:

callAfter = ['MoobotFactoids', 'Factoids', 'Infobot']

See also: irc.noReply(), callbacks.tokenize().

Plugin attributes

Proxy

Proxy is an IRC proxy, allowing you to 'inject' a command into the bot IRC command queue as if it was sent through IRC.

TODO: add more info and example