1 \input texinfo @c -*- texinfo -*-
3 @setfilename bobot++.info
4 @settitle Bobot++: A Schemeable IRC Bot
9 This file documents Bobot++ by Clinton Ebadi and Etienne Bernard
10 (original author, no longer works on program).
12 Copyright 2002 Clinton Ebadi
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
23 @title Bobot++: A Schemeable IRC Bot
28 Copyright @copyright{} 2002 Clinton Ebadi
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
38 @node Top, Introduction, (dir), (dir)
39 @comment node-name, next, previous, up
42 This document describes Bobot++ by Clinton Ebadi and Etienne Bernard
43 (original author, no longer works on program).
45 This document applies to version 2.1.0 of the program named
48 Copyright 2002 Clinton Ebadi
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
67 @node Introduction, Configuration, Top, Top
70 This manual feels abused and neglected because it has almost no
73 @node Configuration, Using the Bot, Introduction, Top
74 @chapter Configuration
76 Bobot++ is easy to configure. The configuration file format may be
77 changing in the 2.1 series, so it is not documented for now. See the
78 @file{examples} directory for an example configuration.
81 * Configuration File Syntax::
82 * Configure File Placement::
85 @node Configuration File Syntax, Configure File Placement, Configuration, Configuration
86 @section Configuration File Syntax
92 @node bot.conf, , Configuration File Syntax, Configuration File Syntax
95 bot.conf is the main configuration file for a Bobot++. The available
96 configuration variables are listed below in the format ``@var{variable}
97 <default-value>: description''
101 @item @var{nickname} <Bobot>: The nickname of the bot (@var{nick} is an
102 alias for @var{nickname})
103 @item @var{username} <bobot>: The IRC username of the bot
104 @item @var{cmdchar} <!>: The character that prefixes commands given to
105 the bot (@var{command} is an alias for @var{cmdchar})
106 @item @var{ircname} <I'm a bobot++!>: The IRC name (or 'real name') of
107 the bot (@var{realname} is an alias for @var{ircname})
108 @item @var{userlist} <bot.users>: Name of the file where the userlist is
110 @item @var{shitlist} <bot.shit>: Name of the file where the shitlist is
112 @item @var{logfile} <$LOGDIR/bot.log>:
116 @node Configure File Placement, , Configuration File Syntax, Configuration
117 @section Configuration File Placement
119 Bobot++ will look in @file{/etc/bobotpp/default/} for its default
120 config if none is specified on the command line. Put the configuration
121 files you want to be loaded by default in this directory. If you are
122 not root or you want to have your own personal configration, put it in
123 @file{~/.bobotpp/config/default/}.
125 @node Using the Bot, Scripting, Configuration, Top
126 @chapter Using Bobot++
134 @node User Levels, , Using the Bot, Using the Bot
137 There are five levels that a user may be when interfacing with a bot:
138 @var{none}, @var{user}, @var{trusted_user}, @var{friend},
139 @var{master}. All users default to @var{none} unless they are changed
140 by a script, the @code{!adduser} command or the @file{bot.users}
141 file. @var{none} is for everyone---very few commands (e.g. help) are
142 available to the users and almost everyone should be this
143 level. A @var{user} can execute many of the bot commands, but can't
144 use masks on kicks and bans. A @var{trusted} user can everything a
145 @var{user} can do, but can also use masks on kicks and bans. A
146 @var{friend} can do everything except for stopping the bot (be
147 careful who you give this to!). The @var{master} level is for the
148 bot's owner (probably you) and can do @emph{everything} to the bot. Be
149 @emph{very} careful if you give @var{master} level access to anyone
150 else. You cannot use this symbolic levels with the @code{!adduser}
151 command. See (FIXME: ref) for the numbers you must use with
154 @node Scripting, Concept Index, Using the Bot, Top
157 Bobot++'s most powerful feature is its scripting system. You write
158 scripts using Guile Scheme. This manual does not cover how to use
159 Guile or how to learn Scheme. @xref{Top, , Guile Reference Manual,
160 guile, The Guile Reference Manual}, for the Guile reference manual and
161 @url{http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html} for
162 a good tutorial on Scheme.
164 Note that in previous versions the scripting commands where in the
165 form @code{bot-@var{function}}. They are now in the form
166 @code{bot:@var{function}}. The old names are still available, but are
167 deprecated and will be removed in Bobot++ 2.4. The command
168 @command{perl -pi -e ``s/bot-/bot:/g'' @var{your-files}} should be enough to
169 convert your code to use the new functions.
172 * Adding New Commands::
174 * Scheme User Levels::
176 * Misc Scripting Stuff::
179 @node Adding New Commands, Hooks, Scripting, Scripting
180 @section Adding New Commands
183 Adding a new command is simple. To register a new command use
184 @code{bot:addcommand}. The prototype for @code{bot:addcommand} is
185 @code{(bot:addcommand name func needs-channel? num-of-args
186 min-level)}. The @code{name} is a string representing the name of the
187 command being added. @code{func} is a function accepting
188 @code{num-of-args} arguments. @code{needs-channel?} is a bool that is
189 true if the function needs the channel name as its first arg, and
190 false otherwise. @code{num-of-args} is the number of args @code{func}
191 will take and must be within zero (0) and twenty
192 (20). @code{min-level} is one of the @ref{Scheme User Levels}. A user must be
193 at least a @code{min-level} user to use the new command. None of the
194 arguments are guaranteed to be passed; if they aren't they are set to
195 the empty string @code{""}. An example of a new command would be:
198 (define (hello channel name)
199 (if (string=? name "")
200 (bot:say channel "Hello world!")
201 (bot:say channel (string-append "Hello " name "!")))
203 (bot:addcommand "hello" hello #t 2 0)
206 This will display ``Hello World!'' if called as @kbd{!hello} and
207 ``Hello World @code{USER}'' if called as @kbd{!hello @var{USER}}.
209 @node Hooks, Scheme User Levels, Adding New Commands, Scripting
212 @cindex Background on Hooks
213 Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
214 and tiny fugue (a MUD bot) hooks with a little bit of extra stuff
215 added in. The basic idea of a hook if that you match a text against
216 regular expression and call a function if text in a message matches
217 that regex. The different types of hooks provided by Bobot++
218 correspond to the different classes of messages that Bobot++ can
219 recieve. A Hook also has several properties, including its priority
220 and whether or not it is a fallthrough hook. Higher priority hooks are
221 executed before lower priority hooks and fallthrough hooks are
222 executed before non-fallthrough hooks of the same priority. A
223 fallthrough hook can match and processing of hooks will continue; as
224 soon as the first non-fallthrough hooks matches processing of hooks
232 @node Creating a Hook, Hook Types, Hooks, Hooks
233 @subsection Creating a Hook
236 To add a new hook you use the function
237 @code{bot:addhook}. @code{bot:addhook} is prototyped as
238 @code{(bot:addhook type regex function pri fall name)}. @code{type}
239 specifies the type of hook (the types of hooks are listed in @ref{Hook
240 Types}). @code{regex} is a standard regular expression. If
241 @code{regex} is matched, @code{function} will be
242 called. @code{function} will take a different number of args depending
243 on the hook type. @code{pri} specifies the priority of the
244 hook---higher priority hooks are executed first. This argument is
245 optional and defaults to @code{0}. @code{fall} is @code{#t} if the
246 hook is a fallthrough hook and @code{#f} is the hook is not a
247 fallthrough hook. This arg is also optional and default to
248 @code{#t}. @code{name} is the optional name of the hook that defaults
249 to ``DEFAULT''. If you set the name then you can have more than one
250 hook that matches the same regexp, as long as they have the same
251 name. E.g. in a log script you could have the regexps for the log
252 function all be @code{".*"} and set their names to @code{"log"} to
253 avoid a conflict with other hooks.
255 @node Hook Types, , Creating a Hook, Hooks
256 @subsection Hook Types
258 Here is a list of the various hooks are notes on each one. The general
263 @code{hooks/name} (this is the Scheme variable name of the hook)
266 Description of the hook
268 @var{arg1} @var{arg2} ... @var{argn}
282 That said, here is the list of available hooks:
292 This hook is triggered when someone performs an action.
294 @var{from}, @var{to}, @var{action}
297 @var{from}: this is the address of the person that performed the
298 action in the form @samp{@var{nick} ! @var{user} @@ @var{host}}
299 (without the spaces).
301 @var{to}: This is the target of the action, which is either a channel
304 @var{action}: This is the text of the action. E.g. if someone did
305 @samp{* foobar does baz}, then @var{action} would be the string
311 @vindex hooks/nickname
312 @code{hooks/nickname}
315 Description of the hook
325 @vindex hooks/signoff
329 Description of the hook
343 Description of the hook
353 @vindex hooks/ctcp-reply
354 @code{hooks/ctcp-reply}
357 Description of the hook
367 @vindex hooks/disconnect
368 @code{hooks/disconnect}
371 Description of the hook
385 Description of the hook
399 Description of the hook
413 Description of the hook
427 Description of the hook
441 Description of the hook
455 Description of the hook
465 @vindex hooks/message
469 Description of the hook
483 Description of the hook
497 Description of the hook
507 @vindex hooks/public-notice
508 @code{hooks/public-notice}
511 Description of the hook
525 Description of the hook
539 Description of the hook
553 Description of the hook
563 @vindex hooks/dcc/begin
564 @code{hooks/dcc/begin}
567 This hook is triggered when a user begins a DCC CHAT with the bot.
572 @var{FROM}: This is the user's address in the form
573 @samp{nick!user@@host}.
578 @vindex hooks/dcc/message
579 @code{hooks/dcc/message}
582 This hook is triggered when a user sends a message to the bot through
585 @var{FROM} @var{MESSAGE}
588 @var{FROM}: This is the user's address in the form
589 @samp{nick!user@@host}.
591 @var{MESSAGE}: This is the message the user sent to the bot.
597 @node Scheme User Levels, Sending Messages, Hooks, Scripting
598 @section Scheme User Levels
605 There are five levels that a user may be when interfacing with a bot:
606 @var{none}, @var{user}, @var{trusted_user}, @var{friend},
607 @var{master}. The Scheme variables for the user levels are
608 @code{bot:user-none}, @code{bot:user-user}, @code{bot:user-trusted},
609 @code{bot:user-friend}, and @code{bot:user-master}. See @ref{User
610 Levels} for more information on User Levels.
612 When adding a new command, think about who should be able to use
613 it. Is your command a general purpose command that helps the channel
614 (e.g. @code{!seen}) that everyone should be able to use? Or is it
615 something that should be restricted? See @ref{User Levels} for
616 information on what level users can do what with the built in bot
617 commands and think about what level a user your command is targetted
618 towards. You must be @emph{very} careful when giving new commands to
619 lower level users because you can do basically everything the bot can
620 do with a script. As the scripting interface becomes more powerful,
621 you must think more about what users can use new commands you add.
623 @node Sending Messages, Misc Scripting Stuff, Scheme User Levels, Scripting
624 @section Sending Messages
626 There are several types of messages you can send with Bobot++ from
627 scripts. There is the simple, but rather limited, @code{bot:say},
628 @code{bot:action} and @code{bot:msg}, and
629 the more powerful, but lower level, @code{bot:send-MESSAGE}
630 functions. Most bots will probably only need the higher level
631 functions, but for the sake of why-not Bobot++ lets you use the lower
632 level functions (in progress).
635 * High Level Message Functions::
636 * Low Level Message Functions::
639 @node High Level Message Functions, Low Level Message Functions, Sending Messages, Sending Messages
640 @subsection ``High Level'' Message Functions
644 @node Low Level Message Functions, , High Level Message Functions, Sending Messages
645 @subsection ``Low Level'' Message Functions
647 The ``Low Level'' messaging functions allow you to do things like send
648 CTCP messages. You probably want to read rfc 2812 and the CTCP spec
649 before using these. If you have no idea what these do, read rfc 2812
650 (IRC Client Protocol) and CTCP spec. These functions all return
651 @code{*unspecified*} always, so don't use the return value for anything.
655 @item @code{bot:send-CTCP to command message}
656 @code{to} is the target of your CTCP message, @code{command} is the
657 CTCP command, and @code{message} is the message (or arguments) of the
658 command. Make sure to @code{bot:ctcp-quote} the message!
662 @node Misc Scripting Stuff, , Sending Messages, Scripting
663 @section Misc. Scripting Stuff
665 These are a few useful things that I thought people writing scripts
669 If you want to execute code when the bot exits, just do
670 @code{add-hook! bot:exit-hook @var{thunk}} where @var{thunk} is an
671 argumentless procedure (a thunk). When the bot exits your thunk will
674 @node Concept Index, Function Index, Scripting, Top
675 @unnumbered Concept Index
678 @node Function Index, Variable Index, Concept Index, Top
679 @unnumbered Function Index
682 @node Variable Index, , Function Index, Top
683 @unnumbered Variable Index