Jokbot plugins -------------- There are two types of plugins for jokbot. The first is a prompted plugin, which responds to a command given it by another IRC user, like "jokbot: help". The second is an unprompted plugin, where jokbot watches the world for something to happen and then tells the channel its in about that without being prompted. Both are simple to write. Base structure -------------- All plugins must start with "from plugin import *". To install a plugin, put it in the plugins/ directory and call it something.py. (You can therefore temporarily disable a plugin by naming the file without a .py extension: see downloadmsg.py.disabled in the jokbot distribution for an example plugin which is disabled). If jokbot is running, you can reload the plugins by sending it a HUP signal: find its PID and use "kill -HUP ". Prompted plugins ---------------- A prompted plugin responds when it hears a "trigger word". Define the trigger word with the trigger_word() function, which takes as parameters the trigger word and a function to call when the trigger is heard. The trigger word is a string: when someone says jokbot: your trigger word blah blah blah your function gets called. Note that your trigger "word" can be any string, including one that contains spaces; you get called if your string appears at the start of someone's request to jokbot. Your function is called with three parameters, user, channel, and message. user is the name of the user who made the command; channel is the channel they said it on, and message is the thing they said: message *does* include your trigger word but does *not* include "jokbot: ". To say something in response, your function must return a string. If you don't want to say anything in response, return None. The function you set up with trigger_word should have a docstring of the format "my trigger word - description of my plugin's syntax". For example, the ticket plugin, which retrieves details of a Trac ticket from the Jokosher repository, has as a docstring "ticket - shows a bug in the bugtracker" This is important because "jokbot: help" will show this docstring as part of the help. See ticket.py in the jokbot distribution for an example prompted plugin which uses urllib to load ticket details from a Trac installation when passed a ticket number. Unprompted plugins ------------------ To have jokbot say things without prompting, use Twisted's LoopingCall function. At the start of your plugin, after "from plugin import *", add "from twisted.internet import task". Then, in your plugin, run something like: l = task.LoopingCall(myfunction) l.start(30.0) which will call myfunction() every thirty seconds with no parameters. To have myfunction say something on the channel, use the say() function; pass it a string and jokbot will say that string. See commitmsg.py in the jokbot distribution for an example unprompted plugin which uses the Python Subversion bindings to check for new commits in the Jokosher SVN repository once every 5 minutes.