2e20c3e1 |
1 | This is bobot++.info, produced by makeinfo version 4.1 from |
2 | bobot++.texinfo. |
3 | |
4 | This file documents Bobot++ by Clinton Ebadi and Etienne Bernard |
5 | (original author, no longer works on program). |
6 | |
7 | Copyright 2002 Clinton Ebadi |
8 | |
9 | Permission is granted to copy, distribute and/or modify this document |
10 | under the terms of the GNU Free Documentation License, Version 1.1 or |
11 | any later version published by the Free Software Foundation; with no |
12 | Invariant Sections, with no Front-Cover Texts, and with no Back-Cover |
13 | Texts. |
14 | |
15 | \1f |
16 | File: bobot++.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) |
17 | |
18 | This document describes Bobot++ by Clinton Ebadi and Etienne Bernard |
19 | (original author, no longer works on program). |
20 | |
21 | This document applies to version 2.1.0 of the program named Bobot++ |
22 | |
439869bf |
23 | Copyright 2002 Clinton Ebadi |
24 | |
25 | Permission is granted to copy, distribute and/or modify this document |
26 | under the terms of the GNU Free Documentation License, Version 1.1 or |
27 | any later version published by the Free Software Foundation; with no |
28 | Invariant Sections, with no Front-Cover Texts, and with no Back-Cover |
29 | Texts. |
30 | |
2e20c3e1 |
31 | * Menu: |
32 | |
33 | * Introduction:: |
ad529fde |
34 | * Configuration:: |
e07b6b46 |
35 | * Using the Bot:: |
ad529fde |
36 | * Scripting:: |
37 | * Concept Index:: |
38 | * Function Index:: |
39 | * Variable Index:: |
2e20c3e1 |
40 | |
41 | \1f |
ad529fde |
42 | File: bobot++.info, Node: Introduction, Next: Configuration, Prev: Top, Up: Top |
2e20c3e1 |
43 | |
44 | Introduction |
45 | ************ |
46 | |
ad529fde |
47 | This manual feels abused and neglected because it has almost no |
48 | content. |
2e20c3e1 |
49 | |
ad529fde |
50 | \1f |
e07b6b46 |
51 | File: bobot++.info, Node: Configuration, Next: Using the Bot, Prev: Introduction, Up: Top |
ad529fde |
52 | |
53 | Configuration |
54 | ************* |
55 | |
56 | Bobot++ is easy to configure. The configuration file format may be |
57 | changing in the 2.1 series, so it is not documented for now. See the |
58 | `examples' directory for an example configuration. |
59 | |
60 | * Menu: |
61 | |
62 | * Configuration File Syntax:: |
63 | * Configure File Placement:: |
64 | |
65 | \1f |
66 | File: bobot++.info, Node: Configuration File Syntax, Next: Configure File Placement, Prev: Configuration, Up: Configuration |
67 | |
68 | Configuration File Syntax |
69 | ========================= |
70 | |
71 | Not here yet. |
72 | |
73 | \1f |
74 | File: bobot++.info, Node: Configure File Placement, Prev: Configuration File Syntax, Up: Configuration |
75 | |
76 | Configuration File Placement |
77 | ============================ |
78 | |
79 | Bobot++ will look in `/etc/bobotpp/default/' for its default config |
80 | if none is specified on the command line. Put the configuration files |
81 | you want to be loaded by default in this directory. If you are not root |
82 | or you want to have your own personal configration, put it in |
83 | `~/.bobotpp/config/default/'. |
84 | |
85 | \1f |
e07b6b46 |
86 | File: bobot++.info, Node: Using the Bot, Next: Scripting, Prev: Configuration, Up: Top |
87 | |
88 | Using Bobot++ |
89 | ************* |
90 | |
91 | FIXME: stuff here... |
92 | |
93 | * Menu: |
94 | |
95 | * User Levels:: |
96 | |
97 | \1f |
98 | File: bobot++.info, Node: User Levels, Prev: Using the Bot, Up: Using the Bot |
99 | |
100 | User Levels |
101 | =========== |
102 | |
103 | There are five levels that a user may be when interfacing with a bot: |
104 | NONE, USER, TRUSTED_USER, FRIEND, MASTER. All users default to NONE |
105 | unless they are changed by a script, the `!adduser' command or the |
106 | `bot.users' file. NONE is for everyone--very few commands (e.g. help) |
107 | are available to the users and almost everyone should be this level. A |
108 | USER can execute many of the bot commands, but can't use masks on kicks |
109 | and bans. A TRUSTED user can everything a USER can do, but can also use |
110 | masks on kicks and bans. A FRIEND can do everything except for stopping |
111 | the bot (be careful who you give this to!). The MASTER level is for the |
112 | bot's owner (probably you) and can do _everything_ to the bot. Be |
113 | _very_ careful if you give MASTER level access to anyone else. You |
114 | cannot use this symbolic levels with the `!adduser' command. See |
115 | (FIXME: ref) for the numbers you must use with `!adduser'. |
116 | |
117 | \1f |
118 | File: bobot++.info, Node: Scripting, Next: Concept Index, Prev: Using the Bot, Up: Top |
ad529fde |
119 | |
120 | Scripting |
121 | ********* |
122 | |
123 | Bobot++'s most powerful feature is its scripting system. You write |
124 | scripts using Guile Scheme. This manual does not cover how to use Guile |
125 | or how to learn Scheme. *Note Guile Reference Manual: (guile)Top, for |
126 | the Guile reference manual and |
127 | <http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html> for a |
128 | good tutorial on Scheme. |
129 | |
439869bf |
130 | Note that in previous versions the scripting commands where in the |
131 | form `bot-FUNCTION'. They are now in the form `bot:FUNCTION'. The old |
132 | names are still available, but are deprecated and will be removed in |
133 | Bobot++ 2.4. The command `perl -pi -e ``s/bot-/bot:/g'' YOUR-FILES' |
134 | should be enough to convert your code to use the new functions. |
135 | |
136 | * Menu: |
137 | |
138 | * Adding New Commands:: |
139 | * Hooks:: |
e07b6b46 |
140 | * Scheme User Levels:: |
141 | * Sending Messages:: |
91dddabd |
142 | * Misc Scripting Stuff:: |
439869bf |
143 | |
144 | \1f |
145 | File: bobot++.info, Node: Adding New Commands, Next: Hooks, Prev: Scripting, Up: Scripting |
146 | |
147 | Adding New Commands |
148 | =================== |
149 | |
e07b6b46 |
150 | Adding a new command is simple. To register a new command use |
151 | `bot:addcommand'. The prototype for `bot:addcommand' is |
152 | `(bot:addcommand name func needs-channel? num-of-args min-level)'. The |
153 | `name' is a string representing the name of the command being added. |
154 | `func' is a function accepting `num-of-args' arguments. |
155 | `needs-channel?' is a bool that is true if the function needs the |
156 | channel name as its first arg, and false otherwise. `num-of-args' is |
157 | the number of args `func' will take and must be within zero (0) and |
158 | twenty (20). `min-level' is one of the *Note Scheme User Levels::. A |
159 | user must be at least a `min-level' user to use the new command. None |
160 | of the arguments are guaranteed to be passed; if they aren't they are |
161 | set to the empty string `""'. An example of a new command would be: |
e07b6b46 |
162 | |
fed59248 |
163 | (define (hello channel name) |
164 | (if (string=? name "") |
165 | (bot:say channel "Hello world!") |
166 | (bot:say channel (string-append "Hello " name "!"))) |
167 | |
168 | (bot:addcommand "hello" hello #t 2 0) |
e07b6b46 |
169 | |
fed59248 |
170 | This will display "Hello World!" if called as `!hello' and "Hello |
171 | World `USER'" if called as `!hello USER'. |
439869bf |
172 | |
173 | \1f |
e07b6b46 |
174 | File: bobot++.info, Node: Hooks, Next: Scheme User Levels, Prev: Adding New Commands, Up: Scripting |
439869bf |
175 | |
176 | Hooks |
177 | ===== |
178 | |
179 | Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII |
6530edbf |
180 | and tiny fugue (a MUD bot) hooks with a little bit of extra stuff added |
181 | in. The basic idea of a hook if that you match a text against regular |
182 | expression and call a function if text in a message matches that regex. |
183 | The different types of hooks provided by Bobot++ correspond to the |
184 | different classes of messages that Bobot++ can recieve. A Hook also has |
185 | several properties, including its priority and whether or not it is a |
186 | fallthrough hook. Higher priority hooks are executed before lower |
187 | priority hooks and fallthrough hooks are executed before |
188 | non-fallthrough hooks of the same priority. A fallthrough hook can |
189 | match and processing of hooks will continue; as soon as the first |
190 | non-fallthrough hooks matches processing of hooks stops. |
439869bf |
191 | |
192 | * Menu: |
193 | |
194 | * Creating a Hook:: |
195 | * Hook Types:: |
196 | |
197 | \1f |
198 | File: bobot++.info, Node: Creating a Hook, Next: Hook Types, Prev: Hooks, Up: Hooks |
199 | |
200 | Creating a Hook |
201 | --------------- |
202 | |
203 | To add a new hook you use the function `bot:addhook'. `bot:addhook' |
fd7440f1 |
204 | is prototyped as `(bot:addhook type regex function pri fall name)'. |
205 | `type' specifies the type of hook (the types of hooks are listed in |
206 | *Note Hook Types::). `regex' is a standard regular expression. If |
207 | `regex' is matched, `function' will be called. `function' will take a |
208 | different number of args depending on the hook type. `pri' specifies |
fed59248 |
209 | the priority of the hook--higher priority hooks are executed first. |
fd7440f1 |
210 | This argument is optional and defaults to `0'. `fall' is `#t' if the |
211 | hook is a fallthrough hook and `#f' is the hook is not a fallthrough |
212 | hook. This arg is also optional and default to `#t'. `name' is the |
fed59248 |
213 | optional name of the hook that defaults to "DEFAULT". If you set the |
fd7440f1 |
214 | name then you can have more than one hook that matches the same regexp, |
215 | as long as they have the same name. E.g. in a log script you could have |
216 | the regexps for the log function all be `".*"' and set their names to |
217 | `"log"' to avoid a conflict with other hooks. |
439869bf |
218 | |
219 | \1f |
220 | File: bobot++.info, Node: Hook Types, Prev: Creating a Hook, Up: Hooks |
221 | |
222 | Hook Types |
223 | ---------- |
224 | |
225 | Here is a list of the various hooks are notes on each one. The |
226 | general format of a hook is: |
227 | |
228 | * `hooks/name' (this is the Scheme variable name of the hook) |
229 | - Description of the hook |
230 | |
fed59248 |
231 | - ARG1 ARG2 ... ARGN |
232 | - ARG1: desc |
439869bf |
233 | |
fed59248 |
234 | - ARG2: desc |
439869bf |
235 | |
236 | - ... |
237 | |
fed59248 |
238 | - ARGN: desc |
439869bf |
239 | |
e07b6b46 |
240 | That said, here is the list of available hooks: FIXME: write docs |
439869bf |
241 | |
242 | * `hooks/action' |
fed59248 |
243 | - This hook is triggered when someone performs an action. |
439869bf |
244 | |
fed59248 |
245 | - FROM, TO, ACTION |
246 | - FROM: this is the address of the person that performed |
0b7a49e2 |
247 | the action in the form `NICK ! USER @ HOST' (without the |
fed59248 |
248 | spaces). |
249 | |
250 | - TO: This is the target of the action, which is either a |
251 | channel or the Bot's nick. |
252 | |
253 | - ACTION: This is the text of the action. E.g. if someone |
254 | did `* foobar does baz', then ACTION would be the string |
255 | `"does baz"'. |
439869bf |
256 | |
439869bf |
257 | * `hooks/nickname' |
258 | - Description of the hook |
259 | |
260 | - # of args |
261 | - `arg1': desc |
262 | |
439869bf |
263 | * `hooks/signoff' |
264 | - Description of the hook |
265 | |
266 | - # of args |
267 | - `arg1': desc |
268 | |
439869bf |
269 | * `hooks/ctcp' |
270 | - Description of the hook |
271 | |
272 | - # of args |
273 | - `arg1': desc |
274 | |
439869bf |
275 | * `hooks/ctcp-reply' |
276 | - Description of the hook |
277 | |
278 | - # of args |
279 | - `arg1': desc |
280 | |
439869bf |
281 | * `hooks/disconnect' |
282 | - Description of the hook |
283 | |
284 | - # of args |
285 | - `arg1': desc |
286 | |
439869bf |
287 | * `hooks/flood' |
288 | - Description of the hook |
289 | |
290 | - # of args |
291 | - `arg1': desc |
292 | |
439869bf |
293 | * `hooks/invite' |
294 | - Description of the hook |
295 | |
296 | - # of args |
297 | - `arg1': desc |
298 | |
439869bf |
299 | * `hooks/join' |
300 | - Description of the hook |
301 | |
302 | - # of args |
303 | - `arg1': desc |
304 | |
439869bf |
305 | * `hooks/kick' |
306 | - Description of the hook |
307 | |
308 | - # of args |
309 | - `arg1': desc |
310 | |
439869bf |
311 | * `hooks/part' |
312 | - Description of the hook |
313 | |
314 | - # of args |
315 | - `arg1': desc |
316 | |
439869bf |
317 | * `hooks/mode' |
318 | - Description of the hook |
319 | |
320 | - # of args |
321 | - `arg1': desc |
322 | |
439869bf |
323 | * `hooks/message' |
324 | - Description of the hook |
325 | |
326 | - # of args |
327 | - `arg1': desc |
328 | |
439869bf |
329 | * `hooks/notice' |
330 | - Description of the hook |
331 | |
332 | - # of args |
333 | - `arg1': desc |
334 | |
439869bf |
335 | * `hooks/public' |
336 | - Description of the hook |
337 | |
338 | - # of args |
339 | - `arg1': desc |
340 | |
439869bf |
341 | * `hooks/public-notice' |
342 | - Description of the hook |
343 | |
344 | - # of args |
345 | - `arg1': desc |
346 | |
439869bf |
347 | * `hooks/raw' |
348 | - Description of the hook |
349 | |
350 | - # of args |
351 | - `arg1': desc |
352 | |
439869bf |
353 | * `hooks/timer' |
354 | - Description of the hook |
355 | |
356 | - # of args |
357 | - `arg1': desc |
358 | |
439869bf |
359 | * `hooks/topic' |
360 | - Description of the hook |
361 | |
362 | - # of args |
363 | - `arg1': desc |
364 | |
0b7a49e2 |
365 | * `hooks/dcc/begin' |
366 | - This hook is triggered when a user begins a DCC CHAT with the |
367 | bot. |
368 | |
369 | - FROM |
370 | - FROM: This is the user's address in the form |
371 | `nick!user@host'. |
372 | |
373 | * `hooks/dcc/message' |
374 | - This hook is triggered when a user sends a message to the bot |
375 | through a DCC CHAT |
376 | |
377 | - FROM MESSAGE |
378 | - FROM: This is the user's address in the form |
379 | `nick!user@host'. |
380 | |
381 | - MESSAGE: This is the message the user sent to the bot. |
439869bf |
382 | |
e07b6b46 |
383 | \1f |
384 | File: bobot++.info, Node: Scheme User Levels, Next: Sending Messages, Prev: Hooks, Up: Scripting |
385 | |
386 | Scheme User Levels |
387 | ================== |
388 | |
389 | There are five levels that a user may be when interfacing with a bot: |
390 | NONE, USER, TRUSTED_USER, FRIEND, MASTER. The Scheme variables for the |
391 | user levels are `bot:user-none', `bot:user-user', `bot:user-trusted', |
392 | `bot:user-friend', and `bot:user-master'. See *Note User Levels:: for |
393 | more information on User Levels. |
394 | |
395 | When adding a new command, think about who should be able to use it. |
396 | Is your command a general purpose command that helps the channel (e.g. |
397 | `!seen') that everyone should be able to use? Or is it something that |
398 | should be restricted? See *Note User Levels:: for information on what |
399 | level users can do what with the built in bot commands and think about |
400 | what level a user your command is targetted towards. You must be _very_ |
401 | careful when giving new commands to lower level users because you can |
402 | do basically everything the bot can do with a script. As the scripting |
403 | interface becomes more powerful, you must think more about what users |
404 | can use new commands you add. |
405 | |
406 | \1f |
91dddabd |
407 | File: bobot++.info, Node: Sending Messages, Next: Misc Scripting Stuff, Prev: Scheme User Levels, Up: Scripting |
e07b6b46 |
408 | |
409 | Sending Messages |
410 | ================ |
411 | |
412 | There are several types of messages you can send with Bobot++ from |
413 | scripts. There is the simple, but rather limited, `bot:say', |
414 | `bot:action' and `bot:msg', and the more powerful, but lower level, |
415 | `bot:send-MESSAGE' functions. Most bots will probably only need the |
416 | higher level functions, but for the sake of why-not Bobot++ lets you |
417 | use the lower level functions. |
418 | |
419 | * Menu: |
420 | |
421 | * High Level Message Functions:: |
422 | * Low Level Message Functions:: |
423 | |
424 | \1f |
425 | File: bobot++.info, Node: High Level Message Functions, Next: Low Level Message Functions, Prev: Sending Messages, Up: Sending Messages |
426 | |
fed59248 |
427 | "High Level" Message Functions |
428 | ------------------------------ |
e07b6b46 |
429 | |
430 | ... |
431 | |
432 | \1f |
433 | File: bobot++.info, Node: Low Level Message Functions, Prev: High Level Message Functions, Up: Sending Messages |
434 | |
fed59248 |
435 | "Low Level" Message Functions |
436 | ----------------------------- |
e07b6b46 |
437 | |
fed59248 |
438 | The "Low Level" messaging functions allow you to do things like send |
439 | CTCP messages. You probably want to read rfc 2812 and the CTCP spec |
e07b6b46 |
440 | before using these. If you have no idea what these do, read rfc 2812 |
441 | (IRC Client Protocol) and CTCP spec. These functions all return |
442 | `*unspecified*' always, so don't use the return value for anything. |
443 | |
444 | * `bot:send-CTCP to command message' `to' is the target of your CTCP |
445 | message, `command' is the CTCP command, and `message' is the |
446 | message (or arguments) of the command. Make sure to |
447 | `bot:ctcp-quote' the message! |
448 | |
449 | |
91dddabd |
450 | \1f |
451 | File: bobot++.info, Node: Misc Scripting Stuff, Prev: Sending Messages, Up: Scripting |
452 | |
453 | Misc. Scripting Stuff |
454 | ===================== |
455 | |
456 | These are a few useful things that I thought people writing scripts |
457 | might want to know. |
458 | |
459 | If you want to execute code when the bot exits, just do `add-hook! |
460 | bot:exit-hook THUNK' where THUNK is an argumentless procedure (a |
461 | thunk). When the bot exits your thunk will be called. |
462 | |
ad529fde |
463 | \1f |
464 | File: bobot++.info, Node: Concept Index, Next: Function Index, Prev: Scripting, Up: Top |
465 | |
466 | Concept Index |
467 | ************* |
468 | |
469 | * Menu: |
e07b6b46 |
470 | |
471 | * Background on Hooks: Hooks. |
472 | |
ad529fde |
473 | \1f |
474 | File: bobot++.info, Node: Function Index, Next: Variable Index, Prev: Concept Index, Up: Top |
475 | |
476 | Function Index |
477 | ************** |
478 | |
479 | * Menu: |
e07b6b46 |
480 | |
481 | * addcommand: Adding New Commands. |
482 | * addhook: Creating a Hook. |
483 | |
ad529fde |
484 | \1f |
485 | File: bobot++.info, Node: Variable Index, Prev: Function Index, Up: Top |
486 | |
487 | Variable Index |
488 | ************** |
489 | |
490 | * Menu: |
2e20c3e1 |
491 | |
fed59248 |
492 | * exit-hook: Misc Scripting Stuff. |
e07b6b46 |
493 | * hooks/action: Hook Types. |
494 | * hooks/ctcp: Hook Types. |
495 | * hooks/ctcp-reply: Hook Types. |
0b7a49e2 |
496 | * hooks/dcc/begin: Hook Types. |
497 | * hooks/dcc/message: Hook Types. |
e07b6b46 |
498 | * hooks/disconnect: Hook Types. |
499 | * hooks/flood: Hook Types. |
500 | * hooks/invite: Hook Types. |
501 | * hooks/join: Hook Types. |
502 | * hooks/kick: Hook Types. |
503 | * hooks/message: Hook Types. |
504 | * hooks/mode: Hook Types. |
505 | * hooks/nickname: Hook Types. |
506 | * hooks/notice: Hook Types. |
507 | * hooks/part: Hook Types. |
508 | * hooks/public: Hook Types. |
509 | * hooks/public-notice: Hook Types. |
510 | * hooks/raw: Hook Types. |
511 | * hooks/signoff: Hook Types. |
512 | * hooks/timer: Hook Types. |
513 | * hooks/topic: Hook Types. |
514 | * user-friend: Scheme User Levels. |
515 | * user-master: Scheme User Levels. |
516 | * user-none: Scheme User Levels. |
517 | * user-trusted: Scheme User Levels. |
518 | * user-user: Scheme User Levels. |
519 | |
520 | |
2e20c3e1 |
521 | \1f |
522 | Tag Table: |
523 | Node: Top\7f517 |
e07b6b46 |
524 | Node: Introduction\7f1246 |
525 | Node: Configuration\7f1437 |
526 | Node: Configuration File Syntax\7f1823 |
527 | Node: Configure File Placement\7f2025 |
528 | Node: Using the Bot\7f2499 |
529 | Node: User Levels\7f2673 |
530 | Node: Scripting\7f3677 |
91dddabd |
531 | Node: Adding New Commands\7f4585 |
fed59248 |
532 | Node: Hooks\7f5852 |
6530edbf |
533 | Node: Creating a Hook\7f6826 |
534 | Node: Hook Types\7f7965 |
0b7a49e2 |
535 | Node: Scheme User Levels\7f11439 |
536 | Node: Sending Messages\7f12568 |
537 | Node: High Level Message Functions\7f13165 |
538 | Node: Low Level Message Functions\7f13379 |
539 | Node: Misc Scripting Stuff\7f14132 |
540 | Node: Concept Index\7f14551 |
541 | Node: Function Index\7f14733 |
542 | Node: Variable Index\7f14994 |
2e20c3e1 |
543 | \1f |
544 | End Tag Table |