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,2004,2005 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
27 @vskip Opt plus 1filll
28 Copyright @copyright{} 2002,2004,2005 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.5 of the program named
48 Copyright 2002,2004 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 --- The Detailed Node Listing ---
71 * Configuration Files::
72 * Configuration File Placement::
94 * Adding New Commands::
96 * Scheme User Levels::
98 * Misc Scripting Stuff::
107 * High Level Message Functions::
108 * Low Level Message Functions::
113 @node Introduction, Configuration, Top, Top
114 @chapter Introduction
116 This manual feels abused and neglected because it has almost no
119 @node Configuration, Using the Bot, Introduction, Top
120 @chapter Configuration
122 Bobot++ is easy to configure. See the @file{examples} directory for an
123 example configuration.
126 * Configuration Files::
127 * Configuration File Placement::
130 @node Configuration Files, Configuration File Placement, Configuration, Configuration
131 @section Configuration Files
138 @node bot.conf, bot.users, Configuration Files, Configuration Files
146 @file{bot.conf} contains key value pairs separated by @code{=}.
148 @code{<key> = <value>}
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}.
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''
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
169 @item @var{shitlist} <bot.shit>: Name of the file where the shitlist is
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.
180 @node server syntax, channel syntax, bot.conf, bot.conf
181 @subsubsection server syntax
183 @var{server} = @var{server_name} [@var{port} [@var{password}]]
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
197 @node channel syntax, , server syntax, bot.conf
198 @subsubsection channel syntax
201 @var{name}:@var{initial_modes}:@var{modes_to_keep}:@var{channel_key}
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
213 @code{@var{channel} = #foo:nt:nt:bar}
215 The bot will join @code{#foo} with the channel key @code{bar} and will
216 then maintain the modes @code{nt}.
218 @code{@var{channel} = #bar:::}
220 The bot will join @code{#bar} and will not set any modes nor will it
221 attempt to maintain any modes.
223 @node bot.users, , bot.conf, Configuration Files
224 @subsection bot.users
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:
229 @samp{@var{mask}:@var{channel}:@var{level}:@var{protection}:@var{auto-op}}
233 @item @var{mask} is the host mask
234 (e.g. @samp{*!*username@*.domain.com}) of the user
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.)
241 @item @var{level} is the user level of the user (@ref{User Levels}).
243 @item @var{protection} is the protection level of the user
246 @item @var{auto-op} is set to control whether a user is automatically
247 given operator priviliges on channel entry (@ref{Automatic Op}).
251 @node Configuration File Placement, , Configuration Files, Configuration
252 @section Configuration File Placement
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
256 files you want to be loaded by default in this directory. If you are
257 not root or you want to have your own personal configuration, put it
258 in @file{~/.bobotpp/config/default/}.
260 @node Using the Bot, Scripting, Configuration, Top
261 @chapter Using Bobot++
270 * Built-In Commands::
273 @node Starting the Bot, User Levels, Using the Bot, Using the Bot
274 @section Starting the Bot
276 The bot is usually installed with the binary name @file{bobotpp}. It
277 accepts the following command line arguments:
281 @item @code{[--help][-h]} - Shows detailed help and exits
283 @item @code{[--version][-v]} - Shows version information and exits
285 @item @code{[--no-background][-b]} - Run bobot++ in the foreground
287 @item @code{[--config-file file][-f]} - Use file instead of
290 @item @code{[--config-dir dir][-d]} - Use dir as dir to load config
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
297 @item @code{[--sys-config dir][-s]} - Looks for config in
298 @file{/etc/bobotpp/dir}. Note that the user dir is still searched
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.
305 @item @code{[--debug][-D]} Makes Bobot++ print debugging info and run
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.
314 The bot defaults to running in the background as a daemon.
316 @node User Levels, Protection, Starting the Bot, Using the Bot
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}.
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).
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.
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.
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
346 @item @code{bot:user-master} - This is the highest user level and has
347 access to every feature of the bot.
351 @node Protection, Automatic Op, User Levels, Using the Bot
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
363 @item No ban. If a user is banned the bot will unban him..
365 @item No kick. The user may still be kicked but the bot will kickban
366 the user who kicked the protected user.
368 @item No deop. The bot will ensure that the user always maintains
373 @node Automatic Op, Built-In Commands, Protection, Using the Bot
374 @section Automatic Op
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''
380 @node Built-In Commands, , Automatic Op, Using the Bot
381 @section Built-In Commands
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.
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}
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
397 @item @command{adduser}
399 @item @command{addserver}
401 @item @command{addshit}
403 @item @command{alias}
407 @item @command{banlist}
409 @item @command{channels}
411 @item @command{cycle}
413 @item @command{dcclist}
415 @item @command{deban}
417 @item @command{delserver}
419 @item @command{deluser}
421 @item @command{delshit}
429 @item @command{execute} @tab @tab @tab @strong{Only available if scripting
434 @item @command{ident}
436 @item @command{invite}
444 @item @command{kickban}
448 @item @command{loadscript} @tab @tab @tab @strong{Only available if scripting
457 @item @command{names}
459 @item @command{nextserver}
463 @item @command{nslookup}
469 @item @command{password}
471 @item @command{reconnect}
473 @item @command{rspymessage}
479 @item @command{server}
481 @item @command{serverlist}
483 @item @command{setfloodrate}
485 @item @command{setversion}
487 @item @command{shitlist}
489 @item @command{spylist}
491 @item @command{spymessage}
493 @item @command{stats}
497 @item @command{tkban}
499 @item @command{topic}
501 @item @command{unlock}
503 @item @command{userlist}
507 @item @command{whois}
511 @node Scripting, Concept Index, Using the Bot, Top
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
516 Guile or how to learn Scheme. @xref{Top, , Guile Reference Manual,
517 guile, The Guile Reference Manual}, for the Guile reference manual and
518 @url{http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html} for
519 a good tutorial on Scheme.
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
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.
530 * Adding New Commands::
532 * Scheme User Levels::
534 * Misc Scripting Stuff::
537 @node Adding New Commands, Hooks, Scripting, Scripting
538 @section Adding New Commands
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:
556 (define (hello channel name)
557 (if (string=? name "")
558 (bot:say channel "Hello world!")
559 (bot:say channel (string-append "Hello " name "!")))
561 (bot:addcommand "hello" hello #t 2 0)
564 This will display ``Hello World!'' if called as @kbd{!hello} and
565 ``Hello World @code{USER}'' if called as @kbd{!hello @var{USER}}.
567 @node Hooks, Scheme User Levels, Adding New Commands, Scripting
570 @cindex Background on Hooks
571 Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
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
590 @node Creating a Hook, Hook Types, Hooks, Hooks
591 @subsection Creating a Hook
594 To add a new hook you use the function
595 @code{bot:addhook}. @code{bot:addhook} is prototyped as
596 @code{(bot:addhook type regex function pri fall name)}. @code{type}
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
602 hook---higher priority hooks are executed first. This argument is
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
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.
613 @node Hook Types, , Creating a Hook, Hooks
614 @subsection Hook Types
616 Here is a list of the various hooks are notes on each one. The general
621 @code{hooks/name} (this is the Scheme variable name of the hook)
624 Description of the hook
626 @var{arg1} @var{arg2} ... @var{argn}
640 That said, here is the list of available hooks:
650 This hook is triggered when someone performs an action.
652 @var{from}, @var{to}, @var{action}
655 @var{from}: this is the address of the person that performed the
656 action in the form @samp{@var{nick} ! @var{user} @@ @var{host}}
657 (without the spaces).
659 @var{to}: This is the target of the action, which is either a channel
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
669 @vindex hooks/nickname
670 @code{hooks/nickname}
673 Description of the hook
683 @vindex hooks/signoff
687 Description of the hook
701 Description of the hook
711 @vindex hooks/ctcp-reply
712 @code{hooks/ctcp-reply}
715 Description of the hook
725 @vindex hooks/disconnect
726 @code{hooks/disconnect}
729 Description of the hook
743 Description of the hook
757 Description of the hook
771 Description of the hook
785 Description of the hook
799 Description of the hook
813 Description of the hook
823 @vindex hooks/message
827 Description of the hook
841 Description of the hook
855 Description of the hook
865 @vindex hooks/public-notice
866 @code{hooks/public-notice}
869 Description of the hook
883 Description of the hook
897 Description of the hook
911 Description of the hook
921 @vindex hooks/dcc/begin
922 @code{hooks/dcc/begin}
925 This hook is triggered when a user begins a DCC CHAT with the bot.
930 @var{FROM}: This is the user's address in the form
931 @samp{nick!user@@host}.
936 @vindex hooks/dcc/message
937 @code{hooks/dcc/message}
940 This hook is triggered when a user sends a message to the bot through
943 @var{FROM} @var{MESSAGE}
946 @var{FROM}: This is the user's address in the form
947 @samp{nick!user@@host}.
949 @var{MESSAGE}: This is the message the user sent to the bot.
955 @node Scheme User Levels, Sending Messages, Hooks, Scripting
956 @section Scheme User Levels
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.
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.
981 @node Sending Messages, Misc Scripting Stuff, Scheme User Levels, Scripting
982 @section Sending Messages
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
990 level functions (in progress).
993 * High Level Message Functions::
994 * Low Level Message Functions::
997 @node High Level Message Functions, Low Level Message Functions, Sending Messages, Sending Messages
998 @subsection ``High Level'' Message Functions
1002 @node Low Level Message Functions, , High Level Message Functions, Sending Messages
1003 @subsection ``Low Level'' Message Functions
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.
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!
1020 @node Misc Scripting Stuff, , Sending Messages, Scripting
1021 @section Misc. Scripting Stuff
1023 These are a few useful things that I thought people writing scripts
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
1032 @node Concept Index, Function Index, Scripting, Top
1033 @unnumbered Concept Index
1036 @node Function Index, Variable Index, Concept Index, Top
1037 @unnumbered Function Index
1040 @node Variable Index, , Function Index, Top
1041 @unnumbered Variable Index