1 This is bobot++.info, produced by makeinfo version 4.1 from
4 This file documents Bobot++ by Clinton Ebadi and Etienne Bernard
5 (original author, no longer works on program).
7 Copyright 2002 Clinton Ebadi
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
16 File: bobot++.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
18 This document describes Bobot++ by Clinton Ebadi and Etienne Bernard
19 (original author, no longer works on program).
21 This document applies to version 2.1.0 of the program named Bobot++
23 Copyright 2002 Clinton Ebadi
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
42 File: bobot++.info, Node: Introduction, Next: Configuration, Prev: Top, Up: Top
47 This manual feels abused and neglected because it has almost no
51 File: bobot++.info, Node: Configuration, Next: Using the Bot, Prev: Introduction, Up: Top
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.
62 * Configuration File Syntax::
63 * Configure File Placement::
66 File: bobot++.info, Node: Configuration File Syntax, Next: Configure File Placement, Prev: Configuration, Up: Configuration
68 Configuration File Syntax
69 =========================
74 File: bobot++.info, Node: Configure File Placement, Prev: Configuration File Syntax, Up: Configuration
76 Configuration File Placement
77 ============================
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/'.
86 File: bobot++.info, Node: Using the Bot, Next: Scripting, Prev: Configuration, Up: Top
98 File: bobot++.info, Node: User Levels, Prev: Using the Bot, Up: Using the Bot
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'.
118 File: bobot++.info, Node: Scripting, Next: Concept Index, Prev: Using the Bot, Up: Top
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.
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.
138 * Adding New Commands::
140 * Scheme User Levels::
142 * Misc Scripting Stuff::
145 File: bobot++.info, Node: Adding New Commands, Next: Hooks, Prev: Scripting, Up: Scripting
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:
163 (define (hello channel name)
164 (if (string=? name "")
165 (bot:say channel "Hello world!")
166 (bot:say channel (string-append "Hello " name "!")))
168 (bot:addcommand "hello" hello #t 2 0)
170 This will display "Hello World!" if called as `!hello' and "Hello
171 World `USER'" if called as `!hello USER'.
174 File: bobot++.info, Node: Hooks, Next: Scheme User Levels, Prev: Adding New Commands, Up: Scripting
179 Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
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.
198 File: bobot++.info, Node: Creating a Hook, Next: Hook Types, Prev: Hooks, Up: Hooks
203 To add a new hook you use the function `bot:addhook'. `bot:addhook'
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
209 the priority of the hook--higher priority hooks are executed first.
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
213 optional name of the hook that defaults to "DEFAULT". If you set the
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.
220 File: bobot++.info, Node: Hook Types, Prev: Creating a Hook, Up: Hooks
225 Here is a list of the various hooks are notes on each one. The
226 general format of a hook is:
228 * `hooks/name' (this is the Scheme variable name of the hook)
229 - Description of the hook
240 That said, here is the list of available hooks: FIXME: write docs
243 - This hook is triggered when someone performs an action.
246 - FROM: this is the address of the person that performed
247 the action in the form `USER ! NICK @ HOST' (without the
250 - TO: This is the target of the action, which is either a
251 channel or the Bot's nick.
253 - ACTION: This is the text of the action. E.g. if someone
254 did `* foobar does baz', then ACTION would be the string
258 - Description of the hook
264 - Description of the hook
270 - Description of the hook
276 - Description of the hook
282 - Description of the hook
288 - Description of the hook
294 - Description of the hook
300 - Description of the hook
306 - Description of the hook
312 - Description of the hook
318 - Description of the hook
324 - Description of the hook
330 - Description of the hook
336 - Description of the hook
341 * `hooks/public-notice'
342 - Description of the hook
348 - Description of the hook
354 - Description of the hook
360 - Description of the hook
367 File: bobot++.info, Node: Scheme User Levels, Next: Sending Messages, Prev: Hooks, Up: Scripting
372 There are five levels that a user may be when interfacing with a bot:
373 NONE, USER, TRUSTED_USER, FRIEND, MASTER. The Scheme variables for the
374 user levels are `bot:user-none', `bot:user-user', `bot:user-trusted',
375 `bot:user-friend', and `bot:user-master'. See *Note User Levels:: for
376 more information on User Levels.
378 When adding a new command, think about who should be able to use it.
379 Is your command a general purpose command that helps the channel (e.g.
380 `!seen') that everyone should be able to use? Or is it something that
381 should be restricted? See *Note User Levels:: for information on what
382 level users can do what with the built in bot commands and think about
383 what level a user your command is targetted towards. You must be _very_
384 careful when giving new commands to lower level users because you can
385 do basically everything the bot can do with a script. As the scripting
386 interface becomes more powerful, you must think more about what users
387 can use new commands you add.
390 File: bobot++.info, Node: Sending Messages, Next: Misc Scripting Stuff, Prev: Scheme User Levels, Up: Scripting
395 There are several types of messages you can send with Bobot++ from
396 scripts. There is the simple, but rather limited, `bot:say',
397 `bot:action' and `bot:msg', and the more powerful, but lower level,
398 `bot:send-MESSAGE' functions. Most bots will probably only need the
399 higher level functions, but for the sake of why-not Bobot++ lets you
400 use the lower level functions.
404 * High Level Message Functions::
405 * Low Level Message Functions::
408 File: bobot++.info, Node: High Level Message Functions, Next: Low Level Message Functions, Prev: Sending Messages, Up: Sending Messages
410 "High Level" Message Functions
411 ------------------------------
416 File: bobot++.info, Node: Low Level Message Functions, Prev: High Level Message Functions, Up: Sending Messages
418 "Low Level" Message Functions
419 -----------------------------
421 The "Low Level" messaging functions allow you to do things like send
422 CTCP messages. You probably want to read rfc 2812 and the CTCP spec
423 before using these. If you have no idea what these do, read rfc 2812
424 (IRC Client Protocol) and CTCP spec. These functions all return
425 `*unspecified*' always, so don't use the return value for anything.
427 * `bot:send-CTCP to command message' `to' is the target of your CTCP
428 message, `command' is the CTCP command, and `message' is the
429 message (or arguments) of the command. Make sure to
430 `bot:ctcp-quote' the message!
434 File: bobot++.info, Node: Misc Scripting Stuff, Prev: Sending Messages, Up: Scripting
436 Misc. Scripting Stuff
437 =====================
439 These are a few useful things that I thought people writing scripts
442 If you want to execute code when the bot exits, just do `add-hook!
443 bot:exit-hook THUNK' where THUNK is an argumentless procedure (a
444 thunk). When the bot exits your thunk will be called.
447 File: bobot++.info, Node: Concept Index, Next: Function Index, Prev: Scripting, Up: Top
454 * Background on Hooks: Hooks.
457 File: bobot++.info, Node: Function Index, Next: Variable Index, Prev: Concept Index, Up: Top
464 * addcommand: Adding New Commands.
465 * addhook: Creating a Hook.
468 File: bobot++.info, Node: Variable Index, Prev: Function Index, Up: Top
475 * exit-hook: Misc Scripting Stuff.
476 * hooks/action: Hook Types.
477 * hooks/ctcp: Hook Types.
478 * hooks/ctcp-reply: Hook Types.
479 * hooks/disconnect: Hook Types.
480 * hooks/flood: Hook Types.
481 * hooks/invite: Hook Types.
482 * hooks/join: Hook Types.
483 * hooks/kick: Hook Types.
484 * hooks/message: Hook Types.
485 * hooks/mode: Hook Types.
486 * hooks/nickname: Hook Types.
487 * hooks/notice: Hook Types.
488 * hooks/part: Hook Types.
489 * hooks/public: Hook Types.
490 * hooks/public-notice: Hook Types.
491 * hooks/raw: Hook Types.
492 * hooks/signoff: Hook Types.
493 * hooks/timer: Hook Types.
494 * hooks/topic: Hook Types.
495 * user-friend: Scheme User Levels.
496 * user-master: Scheme User Levels.
497 * user-none: Scheme User Levels.
498 * user-trusted: Scheme User Levels.
499 * user-user: Scheme User Levels.
505 Node: Introduction
\7f1246
506 Node: Configuration
\7f1437
507 Node: Configuration File Syntax
\7f1823
508 Node: Configure File Placement
\7f2025
509 Node: Using the Bot
\7f2499
510 Node: User Levels
\7f2673
511 Node: Scripting
\7f3677
512 Node: Adding New Commands
\7f4585
514 Node: Creating a Hook
\7f6826
515 Node: Hook Types
\7f7965
516 Node: Scheme User Levels
\7f10905
517 Node: Sending Messages
\7f12034
518 Node: High Level Message Functions
\7f12631
519 Node: Low Level Message Functions
\7f12845
520 Node: Misc Scripting Stuff
\7f13598
521 Node: Concept Index
\7f14017
522 Node: Function Index
\7f14199
523 Node: Variable Index
\7f14460