c8f13c06 |
1 | input texinfo @c -*- texinfo -*- |
2e20c3e1 |
2 | @c %**start of header |
3 | @setfilename bobot++.info |
4 | @settitle Bobot++: A Schemeable IRC Bot |
5 | @setchapternewpage on |
6 | @c %**end of header |
7 | |
8 | @ifinfo |
9 | This file documents Bobot++ by Clinton Ebadi and Etienne Bernard |
10 | (original author, no longer works on program). |
11 | |
2e18045a |
12 | Copyright 2002,2004,2005 Clinton Ebadi |
2e20c3e1 |
13 | |
14 | Permission is granted to copy, distribute and/or modify this document |
15 | under the terms of the GNU Free Documentation License, Version 1.1 or |
16 | any later version published by the Free Software Foundation; with no |
17 | Invariant Sections, with no Front-Cover Texts, and with no Back-Cover |
18 | Texts. |
19 | |
20 | @end ifinfo |
21 | |
22 | @titlepage |
23 | @title Bobot++: A Schemeable IRC Bot |
24 | @author Clinton Ebadi |
25 | |
26 | @page |
4edefeb6 |
27 | @vskip O plus 1filll |
2e18045a |
28 | Copyright @copyright{} 2002,2004,2005 Clinton Ebadi |
2e20c3e1 |
29 | |
30 | Permission is granted to copy, distribute and/or modify this document |
31 | under the terms of the GNU Free Documentation License, Version 1.1 or |
32 | any later version published by the Free Software Foundation; with no |
33 | Invariant Sections, with no Front-Cover Texts, and with no Back-Cover |
34 | Texts. |
35 | |
36 | @end titlepage |
37 | |
38 | @node Top, Introduction, (dir), (dir) |
39 | @comment node-name, next, previous, up |
40 | |
41 | @ifinfo |
42 | This document describes Bobot++ by Clinton Ebadi and Etienne Bernard |
43 | (original author, no longer works on program). |
44 | |
c7d9fb19 |
45 | This document applies to version 2.1.5 of the program named |
2e20c3e1 |
46 | Bobot++ |
439869bf |
47 | |
c7d9fb19 |
48 | Copyright 2002,2004 Clinton Ebadi |
439869bf |
49 | |
50 | Permission is granted to copy, distribute and/or modify this document |
51 | under the terms of the GNU Free Documentation License, Version 1.1 or |
52 | any later version published by the Free Software Foundation; with no |
53 | Invariant Sections, with no Front-Cover Texts, and with no Back-Cover |
54 | Texts. |
2e20c3e1 |
55 | @end ifinfo |
56 | |
57 | @menu |
58 | * Introduction:: |
31433d27 |
59 | * Configuration:: |
e07b6b46 |
60 | * Using the Bot:: |
31433d27 |
61 | * Scripting:: |
62 | * Concept Index:: |
63 | * Function Index:: |
64 | * Variable Index:: |
c7d9fb19 |
65 | |
66 | @detailmenu |
67 | --- The Detailed Node Listing --- |
68 | |
69 | Configuration |
70 | |
71 | * Configuration Files:: |
72 | * Configuration File Placement:: |
73 | |
74 | Configuration Files |
75 | |
76 | * bot.conf:: |
c8f13c06 |
77 | * bot.users:: |
c7d9fb19 |
78 | |
79 | bot.conf |
80 | |
81 | * server syntax:: |
82 | * channel syntax:: |
83 | |
84 | Using Bobot++ |
85 | |
6b59e728 |
86 | * Starting the Bot:: |
c7d9fb19 |
87 | * User Levels:: |
c8f13c06 |
88 | * Protection:: |
89 | * Automatic Op:: |
6b59e728 |
90 | * Built-In Commands:: |
c7d9fb19 |
91 | |
92 | Scripting |
93 | |
94 | * Adding New Commands:: |
95 | * Hooks:: |
96 | * Scheme User Levels:: |
97 | * Sending Messages:: |
98 | * Misc Scripting Stuff:: |
99 | |
100 | Hooks |
101 | |
102 | * Creating a Hook:: |
103 | * Hook Types:: |
104 | |
105 | Sending Messages |
106 | |
107 | * High Level Message Functions:: |
108 | * Low Level Message Functions:: |
109 | |
110 | @end detailmenu |
2e20c3e1 |
111 | @end menu |
112 | |
31433d27 |
113 | @node Introduction, Configuration, Top, Top |
2e20c3e1 |
114 | @chapter Introduction |
115 | |
31433d27 |
116 | This manual feels abused and neglected because it has almost no |
117 | content. |
118 | |
e07b6b46 |
119 | @node Configuration, Using the Bot, Introduction, Top |
31433d27 |
120 | @chapter Configuration |
121 | |
c8f13c06 |
122 | Bobot++ is easy to configure. See the @file{examples} directory for an |
123 | example configuration. |
31433d27 |
124 | |
125 | @menu |
c7d9fb19 |
126 | * Configuration Files:: |
127 | * Configuration File Placement:: |
31433d27 |
128 | @end menu |
129 | |
c7d9fb19 |
130 | @node Configuration Files, Configuration File Placement, Configuration, Configuration |
131 | @section Configuration Files |
31433d27 |
132 | |
e171dcce |
133 | @menu |
134 | * bot.conf:: |
c8f13c06 |
135 | * bot.users:: |
e171dcce |
136 | @end menu |
137 | |
c8f13c06 |
138 | @node bot.conf, bot.users, Configuration Files, Configuration Files |
e171dcce |
139 | @subsection bot.conf |
140 | |
c8f13c06 |
141 | @menu |
142 | * server syntax:: |
143 | * channel syntax:: |
144 | @end menu |
145 | |
c7d9fb19 |
146 | @file{bot.conf} contains key value pairs separated by @code{=}. |
147 | |
148 | @code{<key> = <value>} |
149 | |
150 | Comments are started with a @code{#} and cause the entire line to be |
151 | ignored. @emph{Note that this only works when the @code{#} is the first |
152 | character of the line}. |
153 | |
e171dcce |
154 | bot.conf is the main configuration file for a Bobot++. The available |
155 | configuration variables are listed below in the format ``@var{variable} |
156 | <default-value>: description'' |
157 | |
158 | @itemize @bullet |
159 | |
160 | @item @var{nickname} <Bobot>: The nickname of the bot (@var{nick} is an |
161 | alias for @var{nickname}) |
162 | @item @var{username} <bobot>: The IRC username of the bot |
163 | @item @var{cmdchar} <!>: The character that prefixes commands given to |
164 | the bot (@var{command} is an alias for @var{cmdchar}) |
165 | @item @var{ircname} <I'm a bobot++!>: The IRC name (or 'real name') of |
166 | the bot (@var{realname} is an alias for @var{ircname}) |
167 | @item @var{userlist} <bot.users>: Name of the file where the userlist is |
168 | stored |
169 | @item @var{shitlist} <bot.shit>: Name of the file where the shitlist is |
170 | stored |
c7d9fb19 |
171 | @item @var{logfile} <$LOGDIR/bot.log>: Location of the bot logfile |
172 | (set this to @file{/dev/null} to disable logging). |
173 | @item @var{server} <None>: This specifies the server to connect |
174 | to. Note that this has a special syntax. |
175 | @item @var{channel} <None>: This specifies a channel the bot will join |
176 | when it starts up. This also has a special syntax. |
e171dcce |
177 | |
178 | @end itemize |
31433d27 |
179 | |
c7d9fb19 |
180 | @node server syntax, channel syntax, bot.conf, bot.conf |
181 | @subsubsection server syntax |
182 | |
183 | @var{server} = @var{server_name} [@var{port} [@var{password}]] |
184 | |
185 | This will make Bobot++ attempt to connect to @var{server_name} on port |
186 | @var{port} with the password @var{password}. @var{server_name} should |
187 | be the address of the server. @var{port} and @var{password} are |
188 | optional. You may use more than one server line; Bobot++ will attempt |
189 | to connect to the first one and, if it fails, will connect to the next |
190 | one in the list. There is also a command to cause the bot to cycle |
191 | servers. At the present time Bobot++ cannot connect to more than one |
192 | server at a time. This is a planned feature of 3.0 (which is a very |
193 | long way away; the current structure of the program would make it very |
194 | difficult to add support for connecting to multiple servers at a time |
195 | in a usable manner). |
196 | |
197 | @node channel syntax, , server syntax, bot.conf |
198 | @subsubsection channel syntax |
199 | |
200 | @var{channel} = |
201 | @var{name}:@var{initial_modes}:@var{modes_to_keep}:@var{channel_key} |
202 | |
203 | You may have any number of channel lines. When Bobot++ starts it will |
204 | attempt to join and gain ops in every channel listed. It will join |
205 | @var{name} and set the channel modes to @var{initial_modes} |
206 | (e.g. ``nt'') if it is able to gain operator status. It will then |
207 | maintain @var{modes_to_keep}. If the channel requires a key to enter |
208 | simply set @var{channel_key}. Every argument except for @var{name} is |
209 | optional. |
210 | |
211 | A few example lines: |
212 | |
213 | @code{@var{channel} = #foo:nt:nt:bar} |
214 | |
215 | The bot will join @code{#foo} with the channel key @code{bar} and will |
216 | then maintain the modes @code{nt}. |
217 | |
218 | @code{@var{channel} = #bar:::} |
219 | |
220 | The bot will join @code{#bar} and will not set any modes nor will it |
221 | attempt to maintain any modes. |
222 | |
c8f13c06 |
223 | @node bot.users, , bot.conf, Configuration Files |
224 | @subsection bot.users |
225 | |
226 | @file{bot.users} is the default file name of the userlist. It may be |
227 | changed in @file{bot.conf}. The file contains lines with the format: |
228 | |
229 | @samp{@var{mask}:@var{channel}:@var{level}:@var{protection}:@var{auto-op}} |
230 | |
231 | @itemize |
232 | |
233 | @item @var{mask} is the host mask |
234 | (e.g. @samp{*!*username@*.domain.com}) of the user |
235 | |
236 | @item @var{channel} is a channel mask of the channels that the user |
237 | has priviliges to use the bot in (e.g. @samp{*} for all channels, |
238 | @samp{#*} for all non-local channel, @samp{#foo*} for all channels |
239 | starting with ``foo,'' @samp{#bar} for channel ``#bar'' only, etc.) |
240 | |
241 | @item @var{level} is the user level of the user (@ref{User Levels}). |
242 | |
243 | @item @var{protection} is the protection level of the user |
244 | (@ref{Protection}). |
245 | |
246 | @item @var{auto-op} is set to control whether a user is automatically |
247 | given operator priviliges on channel entry (@ref{Automatic Op}). |
248 | |
249 | @end itemize |
250 | |
c7d9fb19 |
251 | @node Configuration File Placement, , Configuration Files, Configuration |
ad529fde |
252 | @section Configuration File Placement |
31433d27 |
253 | |
254 | Bobot++ will look in @file{/etc/bobotpp/default/} for its default |
255 | config if none is specified on the command line. Put the configuration |
ad529fde |
256 | files you want to be loaded by default in this directory. If you are |
c8f13c06 |
257 | not root or you want to have your own personal configuration, put it |
258 | in @file{~/.bobotpp/config/default/}. |
31433d27 |
259 | |
e07b6b46 |
260 | @node Using the Bot, Scripting, Configuration, Top |
261 | @chapter Using Bobot++ |
262 | |
263 | FIXME: stuff here... |
264 | |
265 | @menu |
6b59e728 |
266 | * Starting the Bot:: |
e07b6b46 |
267 | * User Levels:: |
c8f13c06 |
268 | * Protection:: |
269 | * Automatic Op:: |
6b59e728 |
270 | * Built-In Commands:: |
e07b6b46 |
271 | @end menu |
272 | |
6b59e728 |
273 | @node Starting the Bot, User Levels, Using the Bot, Using the Bot |
274 | @section Starting the Bot |
275 | |
276 | The bot is usually installed with the binary name @file{bobotpp}. It |
277 | accepts the following command line arguments: |
278 | |
279 | @itemize |
280 | |
281 | @item @code{[--help][-h]} - Shows detailed help and exits |
282 | |
283 | @item @code{[--version][-v]} - Shows version information and exits |
284 | |
285 | @item @code{[--no-background][-b]} - Run bobot++ in the foreground |
286 | |
287 | @item @code{[--config-file file][-f]} - Use file instead of |
288 | @file{bot.conf} |
289 | |
290 | @item @code{[--config-dir dir][-d]} - Use dir as dir to load config |
291 | file from |
292 | |
293 | @item @code{[--config dir][-c]} - Search your config path (defaults to |
294 | @file{@var{$HOME}/.bobotpp/config/} and then @file{/etc/bobotpp/}) for |
295 | dir and then loads your config data using dir |
296 | |
297 | @item @code{[--sys-config dir][-s]} - Looks for config in |
298 | @file{/etc/bobotpp/dir}. Note that the user dir is still searched |
299 | first |
300 | |
301 | @item @code{[--user-config dir][-u]} - Looks for config in |
302 | @file{@var{$HOME}/.bobotpp/config/dir/}. Note that the system dir is |
303 | still searched after this if dir is not found. |
304 | |
305 | @item @code{[--debug][-D]} Makes Bobot++ print debugging info and run |
306 | in the foreground |
307 | |
308 | @end itemize |
309 | |
310 | The default configuration is read from |
311 | @file{@var{$HOME}/.bobotpp/config/default/} and then |
312 | @file{/etc/bobotpp/default/} if the user config is not found. |
313 | |
314 | The bot defaults to running in the background as a daemon. |
315 | |
316 | @node User Levels, Protection, Starting the Bot, Using the Bot |
e07b6b46 |
317 | @section User Levels |
318 | |
c8f13c06 |
319 | There are several user levels available in Bobot++ to provide gradated |
320 | access to commands. @command{!adduser} and @file{bot.users} use the |
321 | numeric code; Scheme uses the textual name for the level. By default |
322 | (if no catch-all setting is found in @xref{bot.users}.) a user is not |
323 | even a @code{bot:user-none} and cannot execute @strong{any} commands, |
324 | even commands available to @code{bot:user-none}. |
325 | |
326 | @enumerate 0 |
327 | |
328 | @item @code{bot:user-none} - No @strong{built-in} commands may be |
329 | executed @emph{by default} (commands may be added from Scheme that can |
330 | be executed by users of level none and the level required to execute a |
331 | command may be changed from Scheme). |
332 | |
333 | @item @code{bot:user-user} - Will be able to execute most commands but |
334 | not all and cannot use masks on kicks and bans. |
335 | |
336 | @item @code{bot:user-trusted} - For built-ins with a default |
337 | configuration this user has access to the same set of commands as an |
338 | @code{user} but may use masks on kicks and bans. Scheme commands may |
339 | be added which require a user to be of this level. |
340 | |
341 | @item @code{bot:user-friend} - In the default configuration a user who |
342 | is a friend will be able to do everything short of stopping the |
343 | bot. Again, there may be user added commands that require a higher |
344 | user level. |
345 | |
346 | @item @code{bot:user-master} - This is the highest user level and has |
347 | access to every feature of the bot. |
348 | |
349 | @end enumerate |
350 | |
351 | @node Protection, Automatic Op, User Levels, Using the Bot |
352 | @section Protection |
353 | |
354 | A user added via Scheme, the @file{bot.users} file, or |
355 | @command{!adduser} may be protected from being deoped, kicked, or |
356 | banned. There are currently no symbolic levels in Scheme; just use the |
357 | numeric code. |
358 | |
359 | @enumerate 0 |
360 | |
361 | @item No protection |
362 | |
363 | @item No ban. If a user is banned the bot will unban him.. |
364 | |
365 | @item No kick. The user may still be kicked but the bot will kickban |
366 | the user who kicked the protected user. |
367 | |
368 | @item No deop. The bot will ensure that the user always maintains |
369 | operator status. |
370 | |
371 | @end enumerate |
372 | |
6b59e728 |
373 | @node Automatic Op, Built-In Commands, Protection, Using the Bot |
c8f13c06 |
374 | @section Automatic Op |
375 | |
376 | A user may be automatically given operator status upon entering a |
377 | channel. Set the @var{aop} field to ``0'' to disable auto-op or ``1'' |
378 | to enable auto-op. |
e07b6b46 |
379 | |
6b59e728 |
380 | @node Built-In Commands, , Automatic Op, Using the Bot |
381 | @section Built-In Commands |
382 | |
383 | Bobot++ has many built-in commands that make it useful without |
384 | scripting support. The reference leaves off the command char; |
385 | remember to use whatever you defined the command char to be in |
386 | @file{bot.conf}. If a command needs the channel name then you must |
387 | specify the channel as the first argument to the command when private |
388 | messaging the bot a command. |
389 | |
390 | @multitable @columnfractions 0.25 0.25 0.25 0.25 |
391 | @item @sc{command} @tab @sc{Needs Channel} @tab @sc{Min Level to Use} @tab @sc{Description} |
392 | |
393 | @item @command{action} @option{do} @tab Yes @tab @var{USER} @tab |
394 | Causes the bot to perform the action @option{do} in the current |
395 | channel. |
396 | |
397 | @item @command{adduser} |
398 | |
399 | @item @command{addserver} |
400 | |
401 | @item @command{addshit} |
402 | |
403 | @item @command{alias} |
404 | |
405 | @item @command{ban} |
406 | |
407 | @item @command{banlist} |
408 | |
409 | @item @command{channels} |
410 | |
411 | @item @command{cycle} |
412 | |
413 | @item @command{dcclist} |
414 | |
415 | @item @command{deban} |
416 | |
417 | @item @command{delserver} |
418 | |
419 | @item @command{deluser} |
420 | |
421 | @item @command{delshit} |
422 | |
423 | @item @command{deop} |
424 | |
425 | @item @command{die} |
426 | |
427 | @item @command{do} |
428 | |
429 | @item @command{execute} @tab @tab @tab @strong{Only available if scripting |
430 | support is enabled} |
431 | |
432 | @item @command{help} |
433 | |
434 | @item @command{ident} |
435 | |
436 | @item @command{invite} |
437 | |
438 | @item @command{join} |
439 | |
440 | @item @command{keep} |
441 | |
442 | @item @command{kick} |
443 | |
444 | @item @command{kickban} |
445 | |
446 | @item @command{load} |
447 | |
448 | @item @command{loadscript} @tab @tab @tab @strong{Only available if scripting |
449 | support is enabled} |
450 | |
451 | @item @command{lock} |
452 | |
453 | @item @command{mode} |
454 | |
455 | @item @command{msg} |
456 | |
457 | @item @command{names} |
458 | |
459 | @item @command{nextserver} |
460 | |
461 | @item @command{nick} |
462 | |
463 | @item @command{nslookup} |
464 | |
465 | @item @command{op} |
466 | |
467 | @item @command{part} |
468 | |
469 | @item @command{password} |
470 | |
471 | @item @command{reconnect} |
472 | |
473 | @item @command{rspymessage} |
474 | |
475 | @item @command{save} |
476 | |
477 | @item @command{say} |
478 | |
479 | @item @command{server} |
480 | |
481 | @item @command{serverlist} |
482 | |
483 | @item @command{setfloodrate} |
484 | |
485 | @item @command{setversion} |
486 | |
487 | @item @command{shitlist} |
488 | |
489 | @item @command{spylist} |
490 | |
491 | @item @command{spymessage} |
492 | |
493 | @item @command{stats} |
494 | |
495 | @item @command{tban} |
496 | |
497 | @item @command{tkban} |
498 | |
499 | @item @command{topic} |
500 | |
501 | @item @command{unlock} |
502 | |
503 | @item @command{userlist} |
504 | |
505 | @item @command{who} |
506 | |
507 | @item @command{whois} |
508 | |
509 | @end multitable |
510 | |
e07b6b46 |
511 | @node Scripting, Concept Index, Using the Bot, Top |
31433d27 |
512 | @chapter Scripting |
513 | |
514 | Bobot++'s most powerful feature is its scripting system. You write |
515 | scripts using Guile Scheme. This manual does not cover how to use |
ad529fde |
516 | Guile or how to learn Scheme. @xref{Top, , Guile Reference Manual, |
517 | guile, The Guile Reference Manual}, for the Guile reference manual and |
31433d27 |
518 | @url{http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html} for |
519 | a good tutorial on Scheme. |
520 | |
439869bf |
521 | Note that in previous versions the scripting commands where in the |
522 | form @code{bot-@var{function}}. They are now in the form |
523 | @code{bot:@var{function}}. The old names are still available, but are |
c8f13c06 |
524 | deprecated and will be removed in Bobot++ 3.0. New commands are only |
525 | available with the @code{bot:} prefix. The command @command{perl -pi |
526 | -e ``s/bot-/bot:/g'' @var{your-files}} should be enough to convert |
527 | your code to use the new functions. |
439869bf |
528 | |
529 | @menu |
530 | * Adding New Commands:: |
531 | * Hooks:: |
e07b6b46 |
532 | * Scheme User Levels:: |
533 | * Sending Messages:: |
91dddabd |
534 | * Misc Scripting Stuff:: |
439869bf |
535 | @end menu |
536 | |
537 | @node Adding New Commands, Hooks, Scripting, Scripting |
538 | @section Adding New Commands |
539 | |
e07b6b46 |
540 | @findex addcommand |
541 | Adding a new command is simple. To register a new command use |
542 | @code{bot:addcommand}. The prototype for @code{bot:addcommand} is |
543 | @code{(bot:addcommand name func needs-channel? num-of-args |
544 | min-level)}. The @code{name} is a string representing the name of the |
545 | command being added. @code{func} is a function accepting |
546 | @code{num-of-args} arguments. @code{needs-channel?} is a bool that is |
547 | true if the function needs the channel name as its first arg, and |
548 | false otherwise. @code{num-of-args} is the number of args @code{func} |
549 | will take and must be within zero (0) and twenty |
550 | (20). @code{min-level} is one of the @ref{Scheme User Levels}. A user must be |
551 | at least a @code{min-level} user to use the new command. None of the |
552 | arguments are guaranteed to be passed; if they aren't they are set to |
553 | the empty string @code{""}. An example of a new command would be: |
fed59248 |
554 | |
555 | @example |
e07b6b46 |
556 | (define (hello channel name) |
fed59248 |
557 | (if (string=? name "") |
e07b6b46 |
558 | (bot:say channel "Hello world!") |
559 | (bot:say channel (string-append "Hello " name "!"))) |
560 | |
561 | (bot:addcommand "hello" hello #t 2 0) |
fed59248 |
562 | @end example |
563 | |
e07b6b46 |
564 | This will display ``Hello World!'' if called as @kbd{!hello} and |
565 | ``Hello World @code{USER}'' if called as @kbd{!hello @var{USER}}. |
566 | |
567 | @node Hooks, Scheme User Levels, Adding New Commands, Scripting |
439869bf |
568 | @section Hooks |
569 | |
e07b6b46 |
570 | @cindex Background on Hooks |
439869bf |
571 | Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII |
fed59248 |
572 | and tiny fugue (a MUD bot) hooks with a little bit of extra stuff |
573 | added in. The basic idea of a hook if that you match a text against |
574 | regular expression and call a function if text in a message matches |
575 | that regex. The different types of hooks provided by Bobot++ |
576 | correspond to the different classes of messages that Bobot++ can |
577 | recieve. A Hook also has several properties, including its priority |
578 | and whether or not it is a fallthrough hook. Higher priority hooks are |
579 | executed before lower priority hooks and fallthrough hooks are |
580 | executed before non-fallthrough hooks of the same priority. A |
581 | fallthrough hook can match and processing of hooks will continue; as |
582 | soon as the first non-fallthrough hooks matches processing of hooks |
583 | stops. |
439869bf |
584 | |
585 | @menu |
586 | * Creating a Hook:: |
587 | * Hook Types:: |
588 | @end menu |
589 | |
590 | @node Creating a Hook, Hook Types, Hooks, Hooks |
591 | @subsection Creating a Hook |
592 | |
e07b6b46 |
593 | @findex addhook |
439869bf |
594 | To add a new hook you use the function |
595 | @code{bot:addhook}. @code{bot:addhook} is prototyped as |
fd7440f1 |
596 | @code{(bot:addhook type regex function pri fall name)}. @code{type} |
439869bf |
597 | specifies the type of hook (the types of hooks are listed in @ref{Hook |
598 | Types}). @code{regex} is a standard regular expression. If |
599 | @code{regex} is matched, @code{function} will be |
600 | called. @code{function} will take a different number of args depending |
601 | on the hook type. @code{pri} specifies the priority of the |
e07b6b46 |
602 | hook---higher priority hooks are executed first. This argument is |
439869bf |
603 | optional and defaults to @code{0}. @code{fall} is @code{#t} if the |
604 | hook is a fallthrough hook and @code{#f} is the hook is not a |
fd7440f1 |
605 | fallthrough hook. This arg is also optional and default to |
606 | @code{#t}. @code{name} is the optional name of the hook that defaults |
607 | to ``DEFAULT''. If you set the name then you can have more than one |
608 | hook that matches the same regexp, as long as they have the same |
609 | name. E.g. in a log script you could have the regexps for the log |
610 | function all be @code{".*"} and set their names to @code{"log"} to |
611 | avoid a conflict with other hooks. |
439869bf |
612 | |
613 | @node Hook Types, , Creating a Hook, Hooks |
614 | @subsection Hook Types |
615 | |
616 | Here is a list of the various hooks are notes on each one. The general |
617 | format of a hook is: |
618 | |
619 | @itemize @bullet |
620 | @item |
621 | @code{hooks/name} (this is the Scheme variable name of the hook) |
622 | @itemize @minus |
623 | @item |
624 | Description of the hook |
625 | @item |
fed59248 |
626 | @var{arg1} @var{arg2} ... @var{argn} |
439869bf |
627 | @itemize @minus |
628 | @item |
fed59248 |
629 | @var{arg1}: desc |
439869bf |
630 | @item |
fed59248 |
631 | @var{arg2}: desc |
439869bf |
632 | @item |
633 | ... |
634 | @item |
fed59248 |
635 | @var{argN}: desc |
439869bf |
636 | @end itemize |
637 | @end itemize |
638 | @end itemize |
639 | |
640 | That said, here is the list of available hooks: |
e07b6b46 |
641 | FIXME: write docs |
439869bf |
642 | |
643 | @itemize @bullet |
e07b6b46 |
644 | |
439869bf |
645 | @item |
e07b6b46 |
646 | @vindex hooks/action |
439869bf |
647 | @code{hooks/action} |
648 | @itemize @minus |
649 | @item |
fed59248 |
650 | This hook is triggered when someone performs an action. |
439869bf |
651 | @item |
fed59248 |
652 | @var{from}, @var{to}, @var{action} |
439869bf |
653 | @itemize @minus |
654 | @item |
fed59248 |
655 | @var{from}: this is the address of the person that performed the |
0b7a49e2 |
656 | action in the form @samp{@var{nick} ! @var{user} @@ @var{host}} |
fed59248 |
657 | (without the spaces). |
658 | @item |
659 | @var{to}: This is the target of the action, which is either a channel |
660 | or the Bot's nick. |
661 | @item |
662 | @var{action}: This is the text of the action. E.g. if someone did |
663 | @samp{* foobar does baz}, then @var{action} would be the string |
664 | @code{"does baz"}. |
439869bf |
665 | @end itemize |
666 | @end itemize |
667 | |
439869bf |
668 | @item |
e07b6b46 |
669 | @vindex hooks/nickname |
439869bf |
670 | @code{hooks/nickname} |
671 | @itemize @minus |
672 | @item |
673 | Description of the hook |
674 | @item |
675 | # of args |
676 | @itemize @minus |
677 | @item |
678 | @code{arg1}: desc |
679 | @end itemize |
680 | @end itemize |
681 | |
439869bf |
682 | @item |
e07b6b46 |
683 | @vindex hooks/signoff |
439869bf |
684 | @code{hooks/signoff} |
685 | @itemize @minus |
686 | @item |
687 | Description of the hook |
688 | @item |
689 | # of args |
690 | @itemize @minus |
691 | @item |
692 | @code{arg1}: desc |
693 | @end itemize |
694 | @end itemize |
695 | |
439869bf |
696 | @item |
e07b6b46 |
697 | @vindex hooks/ctcp |
439869bf |
698 | @code{hooks/ctcp} |
699 | @itemize @minus |
700 | @item |
701 | Description of the hook |
702 | @item |
703 | # of args |
704 | @itemize @minus |
705 | @item |
706 | @code{arg1}: desc |
707 | @end itemize |
708 | @end itemize |
709 | |
439869bf |
710 | @item |
e07b6b46 |
711 | @vindex hooks/ctcp-reply |
439869bf |
712 | @code{hooks/ctcp-reply} |
713 | @itemize @minus |
714 | @item |
715 | Description of the hook |
716 | @item |
717 | # of args |
718 | @itemize @minus |
719 | @item |
720 | @code{arg1}: desc |
721 | @end itemize |
722 | @end itemize |
723 | |
439869bf |
724 | @item |
e07b6b46 |
725 | @vindex hooks/disconnect |
439869bf |
726 | @code{hooks/disconnect} |
727 | @itemize @minus |
728 | @item |
729 | Description of the hook |
730 | @item |
731 | # of args |
732 | @itemize @minus |
733 | @item |
734 | @code{arg1}: desc |
735 | @end itemize |
736 | @end itemize |
737 | |
439869bf |
738 | @item |
e07b6b46 |
739 | @vindex hooks/flood |
439869bf |
740 | @code{hooks/flood} |
741 | @itemize @minus |
742 | @item |
743 | Description of the hook |
744 | @item |
745 | # of args |
746 | @itemize @minus |
747 | @item |
748 | @code{arg1}: desc |
749 | @end itemize |
750 | @end itemize |
751 | |
439869bf |
752 | @item |
e07b6b46 |
753 | @vindex hooks/invite |
439869bf |
754 | @code{hooks/invite} |
755 | @itemize @minus |
756 | @item |
757 | Description of the hook |
758 | @item |
759 | # of args |
760 | @itemize @minus |
761 | @item |
762 | @code{arg1}: desc |
763 | @end itemize |
764 | @end itemize |
765 | |
439869bf |
766 | @item |
e07b6b46 |
767 | @vindex hooks/join |
439869bf |
768 | @code{hooks/join} |
769 | @itemize @minus |
770 | @item |
771 | Description of the hook |
772 | @item |
773 | # of args |
774 | @itemize @minus |
775 | @item |
776 | @code{arg1}: desc |
777 | @end itemize |
778 | @end itemize |
779 | |
439869bf |
780 | @item |
e07b6b46 |
781 | @vindex hooks/kick |
439869bf |
782 | @code{hooks/kick} |
783 | @itemize @minus |
784 | @item |
785 | Description of the hook |
786 | @item |
787 | # of args |
788 | @itemize @minus |
789 | @item |
790 | @code{arg1}: desc |
791 | @end itemize |
792 | @end itemize |
793 | |
439869bf |
794 | @item |
e07b6b46 |
795 | @vindex hooks/part |
439869bf |
796 | @code{hooks/part} |
797 | @itemize @minus |
798 | @item |
799 | Description of the hook |
800 | @item |
801 | # of args |
802 | @itemize @minus |
803 | @item |
804 | @code{arg1}: desc |
805 | @end itemize |
806 | @end itemize |
807 | |
439869bf |
808 | @item |
e07b6b46 |
809 | @vindex hooks/mode |
439869bf |
810 | @code{hooks/mode} |
811 | @itemize @minus |
812 | @item |
813 | Description of the hook |
814 | @item |
815 | # of args |
816 | @itemize @minus |
817 | @item |
818 | @code{arg1}: desc |
819 | @end itemize |
820 | @end itemize |
821 | |
439869bf |
822 | @item |
e07b6b46 |
823 | @vindex hooks/message |
439869bf |
824 | @code{hooks/message} |
825 | @itemize @minus |
826 | @item |
827 | Description of the hook |
828 | @item |
829 | # of args |
830 | @itemize @minus |
831 | @item |
832 | @code{arg1}: desc |
833 | @end itemize |
834 | @end itemize |
835 | |
439869bf |
836 | @item |
e07b6b46 |
837 | @vindex hooks/notice |
439869bf |
838 | @code{hooks/notice} |
839 | @itemize @minus |
840 | @item |
841 | Description of the hook |
842 | @item |
843 | # of args |
844 | @itemize @minus |
845 | @item |
846 | @code{arg1}: desc |
847 | @end itemize |
848 | @end itemize |
849 | |
439869bf |
850 | @item |
e07b6b46 |
851 | @vindex hooks/public |
439869bf |
852 | @code{hooks/public} |
853 | @itemize @minus |
854 | @item |
855 | Description of the hook |
856 | @item |
857 | # of args |
858 | @itemize @minus |
859 | @item |
860 | @code{arg1}: desc |
861 | @end itemize |
862 | @end itemize |
863 | |
439869bf |
864 | @item |
e07b6b46 |
865 | @vindex hooks/public-notice |
439869bf |
866 | @code{hooks/public-notice} |
867 | @itemize @minus |
868 | @item |
869 | Description of the hook |
870 | @item |
871 | # of args |
872 | @itemize @minus |
873 | @item |
874 | @code{arg1}: desc |
875 | @end itemize |
876 | @end itemize |
877 | |
439869bf |
878 | @item |
e07b6b46 |
879 | @vindex hooks/raw |
439869bf |
880 | @code{hooks/raw} |
881 | @itemize @minus |
882 | @item |
883 | Description of the hook |
884 | @item |
885 | # of args |
886 | @itemize @minus |
887 | @item |
888 | @code{arg1}: desc |
889 | @end itemize |
890 | @end itemize |
891 | |
439869bf |
892 | @item |
e07b6b46 |
893 | @vindex hooks/timer |
439869bf |
894 | @code{hooks/timer} |
895 | @itemize @minus |
896 | @item |
897 | Description of the hook |
898 | @item |
899 | # of args |
900 | @itemize @minus |
901 | @item |
902 | @code{arg1}: desc |
903 | @end itemize |
904 | @end itemize |
905 | |
439869bf |
906 | @item |
e07b6b46 |
907 | @vindex hooks/topic |
439869bf |
908 | @code{hooks/topic} |
909 | @itemize @minus |
910 | @item |
911 | Description of the hook |
912 | @item |
913 | # of args |
914 | @itemize @minus |
915 | @item |
916 | @code{arg1}: desc |
917 | @end itemize |
918 | @end itemize |
919 | |
0b7a49e2 |
920 | @item |
921 | @vindex hooks/dcc/begin |
922 | @code{hooks/dcc/begin} |
923 | @itemize @minus |
924 | @item |
925 | This hook is triggered when a user begins a DCC CHAT with the bot. |
926 | @item |
927 | @var{FROM} |
928 | @itemize @minus |
929 | @item |
930 | @var{FROM}: This is the user's address in the form |
931 | @samp{nick!user@@host}. |
932 | @end itemize |
933 | @end itemize |
934 | |
935 | @item |
936 | @vindex hooks/dcc/message |
937 | @code{hooks/dcc/message} |
938 | @itemize @minus |
939 | @item |
940 | This hook is triggered when a user sends a message to the bot through |
941 | a DCC CHAT |
942 | @item |
943 | @var{FROM} @var{MESSAGE} |
944 | @itemize @minus |
945 | @item |
946 | @var{FROM}: This is the user's address in the form |
947 | @samp{nick!user@@host}. |
948 | @item |
949 | @var{MESSAGE}: This is the message the user sent to the bot. |
950 | @end itemize |
951 | @end itemize |
439869bf |
952 | @end itemize |
953 | |
954 | |
e07b6b46 |
955 | @node Scheme User Levels, Sending Messages, Hooks, Scripting |
956 | @section Scheme User Levels |
957 | |
958 | @vindex user-none |
959 | @vindex user-user |
960 | @vindex user-trusted |
961 | @vindex user-friend |
962 | @vindex user-master |
963 | There are five levels that a user may be when interfacing with a bot: |
964 | @var{none}, @var{user}, @var{trusted_user}, @var{friend}, |
965 | @var{master}. The Scheme variables for the user levels are |
966 | @code{bot:user-none}, @code{bot:user-user}, @code{bot:user-trusted}, |
967 | @code{bot:user-friend}, and @code{bot:user-master}. See @ref{User |
968 | Levels} for more information on User Levels. |
969 | |
970 | When adding a new command, think about who should be able to use |
971 | it. Is your command a general purpose command that helps the channel |
972 | (e.g. @code{!seen}) that everyone should be able to use? Or is it |
973 | something that should be restricted? See @ref{User Levels} for |
974 | information on what level users can do what with the built in bot |
975 | commands and think about what level a user your command is targetted |
976 | towards. You must be @emph{very} careful when giving new commands to |
977 | lower level users because you can do basically everything the bot can |
978 | do with a script. As the scripting interface becomes more powerful, |
979 | you must think more about what users can use new commands you add. |
980 | |
91dddabd |
981 | @node Sending Messages, Misc Scripting Stuff, Scheme User Levels, Scripting |
e07b6b46 |
982 | @section Sending Messages |
983 | |
984 | There are several types of messages you can send with Bobot++ from |
985 | scripts. There is the simple, but rather limited, @code{bot:say}, |
986 | @code{bot:action} and @code{bot:msg}, and |
987 | the more powerful, but lower level, @code{bot:send-MESSAGE} |
988 | functions. Most bots will probably only need the higher level |
989 | functions, but for the sake of why-not Bobot++ lets you use the lower |
ce02032f |
990 | level functions (in progress). |
e07b6b46 |
991 | |
992 | @menu |
993 | * High Level Message Functions:: |
994 | * Low Level Message Functions:: |
995 | @end menu |
996 | |
997 | @node High Level Message Functions, Low Level Message Functions, Sending Messages, Sending Messages |
998 | @subsection ``High Level'' Message Functions |
999 | |
1000 | ... |
1001 | |
1002 | @node Low Level Message Functions, , High Level Message Functions, Sending Messages |
1003 | @subsection ``Low Level'' Message Functions |
1004 | |
1005 | The ``Low Level'' messaging functions allow you to do things like send |
1006 | CTCP messages. You probably want to read rfc 2812 and the CTCP spec |
1007 | before using these. If you have no idea what these do, read rfc 2812 |
1008 | (IRC Client Protocol) and CTCP spec. These functions all return |
1009 | @code{*unspecified*} always, so don't use the return value for anything. |
1010 | |
1011 | @itemize @bullet |
1012 | |
1013 | @item @code{bot:send-CTCP to command message} |
1014 | @code{to} is the target of your CTCP message, @code{command} is the |
1015 | CTCP command, and @code{message} is the message (or arguments) of the |
1016 | command. Make sure to @code{bot:ctcp-quote} the message! |
1017 | |
1018 | @end itemize |
1019 | |
91dddabd |
1020 | @node Misc Scripting Stuff, , Sending Messages, Scripting |
1021 | @section Misc. Scripting Stuff |
1022 | |
1023 | These are a few useful things that I thought people writing scripts |
1024 | might want to know. |
1025 | |
fed59248 |
1026 | @vindex exit-hook |
91dddabd |
1027 | If you want to execute code when the bot exits, just do |
1028 | @code{add-hook! bot:exit-hook @var{thunk}} where @var{thunk} is an |
1029 | argumentless procedure (a thunk). When the bot exits your thunk will |
1030 | be called. |
1031 | |
31433d27 |
1032 | @node Concept Index, Function Index, Scripting, Top |
1033 | @unnumbered Concept Index |
1034 | @printindex cp |
1035 | |
1036 | @node Function Index, Variable Index, Concept Index, Top |
1037 | @unnumbered Function Index |
1038 | @printindex fn |
1039 | |
1040 | @node Variable Index, , Function Index, Top |
1041 | @unnumbered Variable Index |
1042 | @printindex vr |
91dddabd |
1043 | |
1044 | @bye |