5
__copyright__ = 'this file is in the public domain'
9
a plugin can do 2 things: implement commands or/and implement callbacks:
15
from gozerbot.commands import cmnds
17
def yourhandlingfunction(bot, ievent):
18
DO WHAT YOU WANT THE COMMAND TODO
20
cmnds.add('yourcommand', yourhandlingfunction, 'USER')
22
make a callback if you want to repond to messages the bot gets
23
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
26
from gozerbot.callbacks import callbacks
28
def preremind(bot, ievent):
29
""" remind precondition """
30
return remind.wouldremind(ievent.userhost)
32
def remindcb(bot, ievent):
33
""" remind callbacks """
34
remind.remind(bot, ievent.userhost)
36
callbacks.add('PRIVMSG', remindcb, preremind)
38
the callbacks.add function registers 2 functions for PRIVMSG ircevents.
39
the second function (preremind) checks if the callback should be run, it
40
returns 1 in that case. if this is the case the first function (remindcb)
41
gets fired in its own thread so that it can potentially block. The test
42
function can be omitted by passing in None, in which case the callback
43
always fires when the bot sees such an ircevent.
50
from gozerbot.commands import cmnds
52
def handle_hello(bot, ievent):
53
ievent.reply('hello ' + ievent.nick)
55
cmnds.add('hello', handle_hello, 'USER')
58
we want to add a command that says "hello". first we do a
59
import cmnds from gozerbot.commands so that we can add a command to it.
60
then we go make the function that will do the command. it takes 2 arguments,
61
bot and ievent. we use ievent.reply() to send a response.
62
as a last step we add the function handling the command to the cmnds object.
64
cmnds.add('hello', handle_hello, 'USER')
66
first argument is the command, second argument is the function handling the
67
command and the third is the permission that is needed to be allowed to do
68
the command. you can use the 'ANY" permission to allow everybody.
69
other permissions are for example 'USER' and 'OPER'. you can make permission
70
a list of multiple permissions.
75
- the bot connects to the server
76
- bot gets data back from server. string
77
- this string gets converted to an ircevent
78
- the bot checks if the ircevent triggers a command or a callback (functions)
79
- the ircevent is passed on to the triggered function
81
- response is given back with ievent.reply(txt)
83
the bot and ievent arguments
84
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
85
commands and callbacks get two arguments passed to them. first one is the bot
86
the event took place on and the second the ircevent itself.
88
the test command shows how a ircevent looks like:
92
< gozerbot> Ircevent ==> cmnd=PRIVMSG prefix=bart!~bart@127.0.0.1
93
postfix=#dunkbots nick=bart userhost=bart@127.0.0.1
94
channel=#dunkbots txt=test args=[] rest= speed=5
96
each event has a cmnd attribute for the IRC command in question, in this case
97
a PRIVMSG command. there are prefix and postfix attributes for the text before
98
and after the command. nick, userhosts and channel attributes are set
99
if available. the txt attribute gives the txt if provided, if so args gives
100
possible arguments given after the first word in txt and rest is all txt after
101
the first word. there are more attributes to the ircevent object, see
104
see gozerbot/bot.py and gozerbot/irc.py for bot data members and methods
106
the init and shutdown functions
107
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
108
2 special functions can be defined in a plugin: init() and shutdown().
109
init is called upon plugin load/bot start and shutdown on plugin unload/
114
you can put your own written plugs in their own directory, so you can easily
115
copy them if you need to move the bot to a new directory.
119
if you want to get a response from a user you can use the waitforuser
120
command. it is in gozerbot.generic.
122
example taken from plugs/misc.py, the response function:
125
def handle_response(bot, ievent):
126
""" response .. check if we can get a reply of user """
127
ievent.reply("say something so i can see if i can get a response from you")
128
reply = waitforuser(bot, ievent.userhost)
130
ievent.reply("can't get a response")
132
ievent.reply("you said %s" % reply.txt)
134
take note that waitforuser returns the ievent that the user gives.
added
removed
doc/PROGRAMPLUGIN
