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 (The original author who no longer works on the 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 0pt 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 (The original author who no longer works on the program).
45 This document applies to version 2.2 of the program named
48 Copyright 2002,2004,2005 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 File Placement::
72 * Configuration Files::
102 * Adding New Commands::
105 * Misc Scripting Stuff::
114 * Received Message Hooks::
115 * Sent Message Hooks::
117 * Miscellaneous Hooks::
121 * High Level Message Functions::
122 * Low Level Message Functions::
127 @node Introduction, Configuration, Top, Top
128 @chapter Introduction
130 Bobot++ is a powerful IRC bot written in C++. It can be used
131 standalone as a channel maintenence bot, or extended to do almost
132 anything using Scheme scripts.
134 FIXME: Fill the intro in more?
136 @node Configuration, Using the Bot, Introduction, Top
137 @chapter Configuration
139 Bobot++ is easy to configure. See the @file{examples} directory for an
140 example configuration.
142 The main configuration file is @file{bot.conf}. There are several
143 auxiliary configuration files (a user list, aliases file, ban list,
144 and a script autoexec).
147 * Configuration File Placement::
148 * Configuration Files::
151 @node Configuration File Placement, Configuration Files, Configuration, Configuration
152 @section Configuration File Placement
154 Bobot++ will look in @file{/etc/bobotpp/default/} for its default
155 config if none is specified on the command line. Put the configuration
156 files you want to be loaded by default in this directory. If you are
157 not root, or you want to have your own personal configuration, put it
158 in @file{~/.bobotpp/config/default/}.
160 @node Configuration Files, , Configuration File Placement, Configuration
161 @section Configuration Files
171 @node bot.conf, bot.users, Configuration Files, Configuration Files
174 @file{bot.conf} contains key value pairs separated by @code{=}.
176 @code{<key> = <value>}
178 Comments are started with a @code{#} and cause the entire line to be
179 ignored. @emph{Note that this only works when the @code{#} is the first
180 character of the line}.
182 bot.conf is the main configuration file for a Bobot++. The available
183 configuration variables are listed below in the format ``@var{variable}
184 <default-value>: description''
186 A few of the options have more complex syntax, they are documented in
187 their own subsections.
196 @item @var{maxnicklength} <9>: The maximum length a valid nickname may
197 be. This should be set before setting the bot's nickname if it will be
198 more than nine characters long. Most IRC servers support nicknames
199 longer than nine characters, but Bobot++ still follows the old spec
200 and defaults to nine.
201 @item @var{nickname} <Bobot>: The nickname of the bot (@var{nick} is an
202 alias for @var{nickname})
203 @item @var{username} <bobot>: The IRC username of the bot
204 @item @var{cmdchar} <!>: The character that prefixes commands given to
205 the bot (@var{command} is an alias for @var{cmdchar})
206 @item @var{ircname} <I'm a bobot++!>: The IRC name (or 'real name') of
207 the bot (@var{realname} is an alias for @var{ircname})
208 @item @var{userlist} <bot.users>: Name of the file where the userlist is
210 @item @var{autoexecfile} <bot.autoexec>: Name of the file containing
211 Scheme code to be executed when the bot starts (only used if the bot
212 is compiled with scripting support)
213 @item @var{initfile} <bot.init>: Name of the file containing the
214 default command aliases
215 @item @var{shitlist} <bot.shit>: Name of the file where the shitlist
217 @item @var{logfile} <$LOGDIR/bot.log>: Location of the bot logfile
218 (set this to @file{/dev/null} to disable logging).
219 @item @var{server} <None>: This specifies the server to which the bot
220 will connect. Note that this has a special syntax @pxref{server
222 @item @var{channel} <None>: This specifies the channels the bot will join
223 when it starts up. This has a special syntax @pxref{channel
228 @node server syntax, channel syntax, bot.conf, bot.conf
229 @subsubsection server syntax
231 The server syntax in @file{bot.conf} allows you to specify an
232 alternate port to connect on, and a password to send the server.
234 You may use more than one server line; Bobot++ will attempt to connect
235 to the first one, and will connect to the next one in the list if it
236 fails. The bot will continue cycling through the server list until it
237 is able to connect to one. There is a command (@code{!cycle}) to make
238 the bot to cycle servers.
240 @var{server} = @var{server_name} [@var{port} [@var{password}]]
242 This will make Bobot++ attempt to connect to @var{server_name} on port
243 @var{port} with the password @var{password}. @var{server_name} should
244 be the address of the server. @var{port} and @var{password} are
247 @node channel syntax, , server syntax, bot.conf
248 @subsubsection channel syntax
250 The channel syntax in @file{bot.conf} allows you to specify the
251 initial modes the bot should set on a channel, the modes the bot
252 should maintain, and a key if the channel needs it.
254 You may have any number of channel lines. When Bobot++ starts it will
255 attempt to join and gain operator status in every channel listed.
258 @var{name}:@var{initial_modes}:@var{modes_to_keep}:@var{channel_key}
260 The bot will join @var{name} and set the channel modes to
261 @var{initial_modes} (e.g. ``nt'') if it is able to gain operator
262 status. It will then maintain @var{modes_to_keep}. If the channel
263 requires a key to enter simply set @var{channel_key}. Every argument
264 except for @var{name} is optional.
269 @var{channel} = #foo:nt:nt:bar
272 The bot will join @code{#foo} with the channel key @code{bar} and will
273 then maintain the modes @code{nt}.
276 @var{channel} = #bar:::
279 The bot will join @code{#bar} and will not set any modes nor will it
280 attempt to maintain any modes.
282 @node bot.users, bot.init, bot.conf, Configuration Files
283 @subsection bot.users (User List)
285 @file{bot.users} is the default file name of the userlist. It may be
286 changed in @file{bot.conf} via the @var{userlist} option. @strong{You
287 must add an entry for yourself manually.} You will probably want to
288 add other entries using the IRC command interface as it is more
289 intuitive than editing the file by hand.
291 The file contains lines with the format:
293 @samp{@var{host_mask}:@var{channel_mask}:@var{level}:@var{protection}:@var{auto-op}:@var{expiration}:@var{password}}
297 @item @var{host_mask} is the host mask
298 (e.g. @samp{*!*username@*.domain.com}) of the user
300 @item @var{channel_mask} is a channel mask of the channels that the user
301 has priviliges to use the bot in (e.g. @samp{*} for all channels,
302 @samp{#*} for all non-local channel, @samp{#foo*} for all channels
303 starting with ``foo,'' @samp{#bar} for channel ``#bar'' only, etc.)
305 @item @var{level} is the user level of the user (@ref{User Levels}).
307 @item @var{protection} is the protection level of the user
310 @item @var{auto-op} is set to control whether a user is automatically
311 given operator priviliges on channel entry (@ref{Automatic Op}).
313 @item @var{expiration} is the UNIX timestamp of when the user entry
314 becomes invalid. Setting this to -1 will make the entry permanent.
316 @item @var{password} is the password the user must supply to the bot
317 to authenticate. This can be set to @code{*NONE*} to not have a password.
321 @node bot.init, bot.autoexec, bot.users, Configuration Files
322 @subsection bot.init (Command Aliases)
324 This file stores a list of IRC command aliases. The filename may be
325 changed in @file{bot.conf} via the @var{initfile} option. You use this
326 file to set up aliases for IRC commands, e.g. to make @code{!a} call
327 @code{!adduser}. This way you can save typing for commonly used commands.
329 The format of a line in the file is:
330 @var{alias} @var{command}
332 This will make @var{alias} call @var{command}. e.g. @samp{t topic}
333 will make @code{!t New Topic} set the current channel's topic to ``New
334 Topic,'' just as if you had used @code{!topic New Topic}.
336 @node bot.autoexec, bot.shit, bot.init, Configuration Files
337 @subsection bot.autoexec (Scheme Init File)
339 This file is only used when Bobot++ is compiled with scripting
340 support. The name of the autoexec file can be changed in
341 @file{bot.conf} via the @var{autoexecfile} option.
343 The contents of this file are evaluated by Guile when the bot
344 starts. You can use this to do things like loading a few default
345 modules when the bot starts.
347 @node bot.shit, , bot.autoexec, Configuration Files
348 @subsection bot.shit (Ban/Shit List)
350 This file stores the ban list. The name may be changed in
351 @file{bot.conf} via the @var{shitlist} option. You will most likely
352 want to use the IRC command interface to edit this file instead of
355 The file contains lines in the form:
357 @samp{@var{host_mask}:@var{channel_mask}:@var{level}:@var{expiration}:@var{reason}}
361 @item @var{host_mask} is the host mask
362 (e.g. @samp{*!*username@*.domain.com}) of the user
364 @item @var{channel_mask} is a channel mask of the channels that the user
365 is banned on (e.g. @samp{*} for all channels,
366 @samp{#*} for all non-local channel, @samp{#foo*} for all channels
367 starting with ``foo,'' @samp{#bar} for channel ``#bar'' only, etc.
369 @item @var{level} is a number specifying if the bot should not allow
370 the user to gain ops, to kick the user upon joining, or to prevent the
371 user from being debanned by other users. @ref{Shit Levels} for
372 information on the available levels.
374 @item @var{expiration} is the UNIX timestamp of when the shit entry
375 becomes invalid. This may be set to -1 to make it valid forever.
377 @item @var{reason} is text that is sent to the user when they are
378 kicked or banned from the channel.
382 @node Using the Bot, Scripting, Configuration, Top
383 @chapter Using Bobot++
385 Using Bobot++ is easy. This chapter covers starting the bot, a few
386 Bobot++ specific concepts, and using the built-in commands of the bot.
391 * Built-In Commands::
394 @node Starting the Bot, Concepts, Using the Bot, Using the Bot
395 @section Starting the Bot
397 The bot is usually installed with the binary name @file{bobotpp}. It
398 accepts the following command line arguments.
401 @item @code{[--help][-h]} - Shows detailed help and exits
402 @item @code{[--version][-v]} - Shows version information and exits
403 @item @code{[--no-background][-b]} - Run bobot++ in the foreground
404 @item @code{[--config-file file][-f]} - Use file instead of @file{bot.conf}
405 @item @code{[--config-dir dir][-d]} - Use dir as dir to load config file from
406 @item @code{[--config dir][-c]} - Search your config path (defaults to
407 @file{@var{$HOME}/.bobotpp/config/} and then @file{/etc/bobotpp/}) for
408 dir and then loads your config data using dir
409 @item @code{[--sys-config dir][-s]} - Looks for config in
410 @file{/etc/bobotpp/dir}. Note that the user dir is still searched
412 @item @code{[--user-config dir][-u]} - Looks for config in
413 @file{@var{$HOME}/.bobotpp/config/dir/}. Note that the system dir is
414 still searched after this if dir is not found.
415 @item @code{[--debug][-D]} Makes Bobot++ print debugging info and run
417 @item @code{[--debug-scripts][-S]} Enables the Guile debugging
418 evaluator for verbose script errors and backtraces while still running
419 the bot in the background.
422 The default configuration is read from
423 @file{@var{$HOME}/.bobotpp/config/default/} and then
424 @file{/etc/bobotpp/default/} if the user config is not found.
426 The bot defaults to running in the background as a daemon.
428 @node Concepts, Built-In Commands, Starting the Bot, Using the Bot
431 There are a few general concepts that a user of Bobot++ should know
441 @node User Levels, Protection, Concepts, Concepts
442 @subsection User Levels
444 There are several user levels available in Bobot++ to provide gradated
445 access to commands. @command{!adduser} and @file{bot.users} use the
446 numeric code; Scheme uses the textual name for the level. By default
447 (if the user is not found in the userlist) a user has access to
448 commands with the level @code{bot:user-none}.
452 @item @code{bot:user-none} - No @strong{built-in} commands may be
453 executed @emph{by default} (commands may be added from Scheme that can
454 be executed by users of level none and the level required to execute a
455 command may be changed from Scheme).
457 @item @code{bot:user-user} - Will be able to execute most commands but
458 not all and cannot use masks on kicks and bans.
460 @item @code{bot:user-trusted} - For built-ins with a default
461 configuration this user has access to the same set of commands as an
462 @code{user} but may use masks on kicks and bans. Scheme commands may
463 be added which require a user to be of this level.
465 @item @code{bot:user-friend} - In the default configuration a user who
466 is a friend will be able to do everything short of stopping the
467 bot. Again, there may be user added commands that require a higher
470 @item @code{bot:user-master} - This is the highest user level and has
471 access to every feature of the bot.
475 @node Protection, Automatic Op, User Levels, Concepts
476 @subsection Protection
478 A user added via Scheme, the @file{bot.users} file, or
479 @command{!adduser} may be protected from being deoped, kicked, or
480 banned. The user list and IRC commands use the numeric codes, Scheme
481 uses the symbolic names.
484 @item @code{bot:protection/none} No protection
485 @item @code{bot:protection/no-ban} No ban. If a user is banned the bot will unban him..
486 @item @code{bot:protection/no-kick} No kick. The user may still be kicked but the bot will kickban
487 the user who kicked the protected user.
488 @item @code{bot:protection/no-deop} No deop. The bot will ensure that the user always maintains
492 @node Automatic Op, Shit Levels, Protection, Concepts
493 @subsection Automatic Op
495 A user may be automatically given operator status upon entering a
496 channel. Scheme uses the symbolic name, the user list
497 (@file{bot.users}) and IRC commands use the numeric value.
500 @item @code{bot:aop/no} Do not automatically op the user
501 @item @code{bot:aop/yes} Do automatically op the user
504 @node Shit Levels, , Automatic Op, Concepts
505 @subsection Shit Levels
507 The shit list and shit list related commands use different levels to
508 define how much the bot hates a user. Scheme uses the symbolic names,
509 the shit list and IRC commands use the numbers.
512 @item @code{bot:shit/none} The bot doesn't hate the user (this is the
514 @item @code{bot:shit/no-op} The bot will deop the user any time he
515 gains operator priviliges in the channel
516 @item @code{bot:shit/no-join} The bot will kick and ban the user when he
518 @item @code{bot:shit/no-deban} The bot will kick and ban usre when he
519 joins the channel, and will prevent other users from debanning him.
522 @node Built-In Commands, , Concepts, Using the Bot
523 @section Built-In Commands
525 Bobot++ has many built-in commands that make it useful without
526 scripting support. The reference leaves off the command char; remember
527 to use whatever you defined the command char to be in
528 @file{bot.conf}. If a command needs the channel name then you must
529 specify the channel as the first argument to the command when private
530 messaging the bot a command.
532 @multitable @columnfractions 0.20 0.15 0.15 0.50
533 @item @sc{command} @tab @sc{Needs Channel} @tab @sc{Min Level to Use} @tab @sc{Description}
535 @item @command{action} @option{do} @tab Yes @tab @var{USER} @tab
536 Causes the bot to perform the action @option{do} in the current
539 @item @command{adduser} @tab @tab @tab
541 @item @command{addserver} @tab @tab @tab Adds the server specified by
542 @var{host name} or @var{ip address} to the server list.
544 @item @command{addshit} @tab @tab @tab
546 @item @command{alias} @tab @tab @tab Makes an alias, and adds the
547 function @var{new name}, that will do exactly the same command as
550 @item @command{ban} @tab @tab @tab Bans @var{mask} or @var{nick} from
551 @var{channel}. You need to be a trusted user to ban with a
554 @item @command{banlist} @tab @tab @tab
556 @item @command{channels} @tab @tab @tab Prints the channel(s) where
557 the bot is currently.
559 @item @command{cycle} @tab Yes @tab @tab Makes the bot leave and join
562 @item @command{dcclist} @tab @tab @tab Gives the list of all DCC Chat
565 @item @command{deban} @tab Yes @tab @tab Debans @var{mask} or
566 @var{nick} from @var{channel}. You need to be a trusted user to deban
569 @item @command{delserver} @tab @tab @tab Deletes server from server
570 list whose number in the server list is @var{server number}.
572 @item @command{deluser} @tab @tab @tab Removes @var{nick} or
573 @var{mask} from the userlist.
575 @item @command{delshit} @tab @tab @tab Removes @var{nick} or
576 @var{mask} from the shitlist.
578 @item @command{deop} @tab Yes @tab @tab Deops @var{mask} or @var{nick}
581 @item @command{die} @tab @tab @tab Makes the bot stop immediately.
583 @item @command{do} @tab @tab @tab
585 @item @command{execute} @tab @tab @tab @strong{Only available if
586 scripting support is enabled}
588 @item @command{help} @tab @tab @tab
590 @item @command{ident} @tab @tab @tab Identifies you on the bot. Note
591 that you should not use this command in public @dots{}
593 @item @command{invite} @tab Yes @tab @tab Invites @var{nick} on
596 @item @command{join} @tab @tab @tab Makes the bot join @var{channel}.
598 @item @command{keep} @tab Yes @tab @tab Sets the @var{modes} that the
599 bot will keep for @var{channel}.
601 @item @command{kick} @tab Yes @tab @tab Kicks @var{mask} or @var{nick}
602 out of @var{channel}, because of @var{reason}. You need to be a
603 trusted user to use a @var{mask}.
605 @item @command{kickban} @tab Yes @tab @tab Bans then kicks @var{mask}
606 or @var{nick} out of @var{channel}, because of @var{reason}. You need
607 to be a trusted user to use a @var{mask}.
609 @item @command{load} @tab @tab @tab Reloads the userlist from disk.
611 @item @command{loadscript} @tab @tab @tab @strong{Only available if
612 scripting support is enabled}
614 @item @command{lock} @tab @tab @tab Locks topic on @var{channel}.
616 @item @command{mode} @tab Yes @tab @tab Sends @var{mode string} as
617 mode for @var{channel}.
619 @item @command{msg} @tab @tab @tab
621 @item @command{names} @tab Yes @tab @tab Shows the nicknames and
622 status of users on @var{channel}.
624 @item @command{nextserver} @tab @tab @tab Makes the bot connect to the
625 next server in its server list.
627 @item @command{nick} @tab @tab @tab Makes the bot use nickname @var{nick}.
629 @item @command{nslookup} @tab @tab @tab Does a nameserver query about
630 @var{nick} host, @var{host} or @var{ip address}.
632 @item @command{op} @tab Yes @tab @tab Ops @var{nick} on @var{channel}.
634 @item @command{part} @tab Yes @tab @tab Makes the bot leave @var{channel}.
636 @item @command{password} @tab @tab @tab Changes your password on the
637 bot. Use @code{NONE} as password if you want to clear it. Do not use this
640 @item @command{reconnect} @tab @tab @tab Makes the bot reconnect to
643 @item @command{rspymessage} @tab @tab @tab Removes you from the spy
646 @item @command{save} @tab @tab @tab Saves the userlist.
648 @item @command{say} @tab Yes @tab @tab Makes the bot say @var{message}
651 @item @command{server} @tab @tab @tab Select the server to connect
652 to. @var{server number} is the number of the server in the serverlist.
654 @item @command{serverlist} @tab @tab @tab Shows the bot's serverlist.
656 @item @command{setfloodrate} @tab @tab @tab
658 @item @command{setversion} @tab @tab @tab
660 @item @command{shitlist} @tab @tab @tab Shows the bot's shitlist.
662 @item @command{spylist} @tab @tab @tab Shows the bot's spylist.
664 @item @command{spymessage} @tab @tab @tab Adds you to the spylist
666 @item @command{stats} @tab Yes @tab @tab Gives @var{channel}'s statistics.
668 @item @command{tban} @tab Yes @tab @tab Bans @var{nick} or @var{mask}
669 from @var{channel} for @var{time} seconds.
671 @item @command{tkban} @tab Yes @tab @tab Bans @var{nick} or @var{mask}
672 from @var{channel} for @var{time} seconds, then kicks him/them because
675 @item @command{topic} @tab Yes @tab @tab If no @var{topic}is given,
676 prints @var{channel}'s topic. Otherwise, the bot will change
677 @var{channel}'s topic to @var{topic}.
679 @item @command{unlock} @tab Yes @tab @tab Makes the bot unlock topic
682 @item @command{userlist} @tab @tab @tab Shows the bot's userlist
684 @item @command{who} @tab Yes @tab @tab Show your level on @var{channel}
686 @item @command{whois} @tab Yes @tab @tab Shows information about
687 @var{nick} on @var{channel}
691 @node Scripting, Concept Index, Using the Bot, Top
694 Bobot++'s most powerful feature is its scripting system. You write
695 scripts using Guile Scheme. This manual does not cover how to use
696 Guile or how to learn Scheme. @xref{Top, , Guile Reference Manual,
697 guile, The Guile Reference Manual}, for the Guile reference manual and
698 @url{http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html} for
699 a good tutorial on Scheme.
701 Note that in previous versions the scripting commands where in the
702 form @code{bot-@var{function}}. They are now in the form
703 @code{bot:@var{function}}. The old names are still available, but are
704 deprecated and will be removed in Bobot++ 3.0. New commands are only
705 available with the @code{bot:} prefix. The command @command{perl -pi
706 -e ``s/bot-/bot:/g'' @var{your-files}} should be enough to convert
707 your code to use the new functions.
709 @strong{NOTE}: All arguments to functions and hooks called by the bot
710 are strings unless otherwise specified.
713 * Adding New Commands::
716 * Misc Scripting Stuff::
719 @node Adding New Commands, Hooks, Scripting, Scripting
720 @section Adding New Commands
722 Adding a new command is simple. To register a new command use
723 @code{bot:addcommand}.
725 @defun bot:addcommand name func needs-channel? num-of-args min-level
727 The @var{name} is a string representing the name of the command being
728 added. @var{func} is a function accepting @var{num-of-args}
729 arguments. @var{needs-channel?} is a bool that is true if the function
730 needs the channel name as its first arg, and false otherwise.
731 @var{num-of-args} is the number of args @var{func} will take and must
732 be within zero (0) and twenty (20). @var{min-level} is one of the
733 @ref{User Levels}. A user must be at least a @var{min-level} user to
734 use the new command. None of the arguments are guaranteed to be
735 passed; if they aren't they are set to the empty string @code{""}. An
736 example of a new command would be:
739 (define (hello channel name)
740 (if (string=? name "")
741 (bot:say channel "Hello world!")
742 (bot:say channel (string-append "Hello " name "!")))
744 (bot:addcommand "hello" hello #t 2 0)
747 This will display ``Hello World!'' if called as @kbd{!hello} and
748 ``Hello World @var{USER}'' if called as @kbd{!hello @var{USER}}.
751 @node Hooks, Sending Messages, Adding New Commands, Scripting
754 @cindex Background on Hooks
755 Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
756 and tiny fugue (a MUD bot) hooks with a little bit of extra stuff
757 added in. A hook is called when a regular expression is matched
758 against a message sent to or by the bot.
760 Bobot++ uses different hook types for each IRC message type, and also
761 includes a hook for accessing raw irc messages. Hooks are tagged with
762 a priority and a flag that specifies whether to call the next hook
763 that matches after calling the current one or to stop
766 Hooks are processed from the highest to lowest priority, with
767 fallthrough hooks of equal priority to non-fallthrough hooks being
775 @node Creating a Hook, Hook Types, Hooks, Hooks
776 @subsection Creating a Hook
778 To add a new hook you use the function @code{bot:addhook}.
780 @defun bot:addhook type regex function [pri fall name]
781 @var{type} specifies the type of hook (the types of hooks are listed
782 in @ref{Hook Types}).
784 @var{regex} is a standard regular expression. If
785 @var{regex} is matched, @var{function} will be called.
787 @var{function} will take a different number of args depending on the
790 @var{pri} specifies the priority of the hook---higher priority hooks
791 are executed first. This argument is optional and defaults to
794 @var{fall} is @code{#t} if the hook is a fallthrough hook and
795 @code{#f} is the hook is not a fallthrough hook. This arg is also
796 optional and defaults to @code{#t}.
798 @var{name} is the optional name of the hook that defaults to
799 @code{"DEFAULT"}. If you set the name then you can have more than
800 one hook that matches the same regexp, as long as they have the same
801 name. E.g. in a log script you could have the regexps for the log
802 function all be @code{".*"} and set their names to @code{"log"} to
803 avoid a conflict with other hooks.
806 @node Hook Types, , Creating a Hook, Hooks
807 @subsection Hook Types
809 The following sections document the different hooks Bobot++ exposes.
811 The general format of each hook description is as if it were a
812 function to be defined, but these describe the function to be passed
813 to @code{bot:add-hook}. Do @emph{not} name your functions these
816 That said, here is the list of available hooks functions.
820 * Received Message Hooks::
821 * Sent Message Hooks::
823 * Miscellaneous Hooks::
826 @node Received Message Hooks, Sent Message Hooks, Hook Types, Hook Types
827 @subsubsection Receieved Message Hooks
829 The following hooks are triggered when a mesage is received by the bot.
831 @defun hooks/action from to action
832 This hook is triggered when someone performs an action.
834 @var{from} is the nickname the person that performed the
837 @var{to} is the target of the action, which is either a channel or the
838 Bot's nick if the user private messages the bot.
840 @var{action} is the text of the action. E.g. if someone did @samp{*
841 foobar does baz}, then @var{action} would be the string @code{"does
845 @defun hooks/nickname old-nick new-nick
846 This hook is called when someone changes his nickname from
847 @var{old-nick} to @var{new-nick}.
850 @defun hooks/signoff nick message
851 This hook is called when someone signs off of IRC.
853 @var{nick} is the nickname of the person signing off.
855 @var{message} is his quit message
858 @defun hooks/ctcp nick to command rest
859 This hook is called when a CTCP request is received by the bot.
861 @var{nick} is the nickname of the sender.
863 @var{to} is the target of the CTCP request. This will either be a
864 channel the bot is in, or the nickname of the bot.
866 @var{command} is the CTCP command issued.
868 @var{rest} contains the arguments to the CTCP command.
871 @defun hooks/ctcp-reply nick command rest
872 This hook is called when a CTCP REPLY is received. This occurs when
873 the bot has sent a CTCP request to another client. The CTCP REPLY is
874 always addressed to the bot directly.
876 @var{nick} is the nickname of the person who replied.
878 @var{command} is the command to which @var{nick} is replying.
880 @var{rest} contains the body of the reply.
883 @defun hooks/disconnect server intentional
884 This is called when the bot is disconnected from a server.
886 @var{server} is the hostname of the server from which the bot was
889 @var{intentional} is a flag set to @code{#t} when the bot disonnected
890 from the server as the result of a command (issued by a user from IRC,
891 SIGHUP, or from a script), or @code{#f} when the bot disconnected from
892 the server unintentionally..
895 @defun hooks/invite nick channel
896 This hook is called when a user invited the bot to join a channel.
898 @var{nick} is the nickname of the user who sent the invite.
900 @var{channel} is the channel to which the bot was invited.
903 @defun hooks/join nick channel
904 This is called when a user or the bot joins a channel.
906 @var{nick} is the nickname of the user who joined @var{channel}. This
907 may be the bot's nickname (the IRC server sends the JOIN command back
908 to the the bot after it joins a channel).
910 @var{channel} is the channel that was joined
913 @defun hooks/kick target from channel reason
914 This hook is called when a user, including the bot, is kicked out of a
917 @var{target} is the nick of the user who was kicked. This may be the
920 @var{from} is the nick of the user who issued the kick. This may also
923 @var{channel} is the channel the kick was issued in.
925 @var{reason} is the reason the user was kicked.
928 @defun hooks/part nick channel
929 This hook is called when a user parts a channel.
931 @var{nick} is the user who parted the channel. This may be the bot.
933 @var{channel} is the channel from which the user parted.
936 @defun hooks/mode nick target modes
937 This hook is called when someone sets the modes of @var{target}.
939 @var{nick} is the user who set the modes. This may be the bot.
941 @var{target} is the target of the MODE command. This may be a
942 channel or a user. If it is a user, it may be the bot.
944 @var{modes} is the MODE string.
947 @defun hooks/message nick message
948 This hook is called when someone sends a private message to the bot.
950 @var{nick} is the nickname of the user who sent the message.
952 @var{message} is the message the user sent.
955 @defun hooks/notice nick message
956 This hook is called when a user send a private notice to the bot.
958 @var{nick} is the user who sent the notice.
960 @var{message} is the message the user sent.
963 @defun hooks/public nick channel message
964 This hook is called when a user sends a normal message to a channel.
966 @var{nick} is the user who sent the message.
968 @var{channel} is the channel to which the message was sent.
970 @var{message} is the message that was sent.
973 @defun hooks/public-notice nick channel message
974 This hook is called when a user send a notice to a channel.
976 @var{nick} is the user who sent the notice.
978 @var{channel} is the channel to which the notice was sent.
980 @var{message} is the message that was sent.
983 @defun hooks/raw raw-message
984 This hook is called every time a message is received. This matches on
985 the raw message text and passes the hook function the raw IRC message.
987 @var{raw-message} is the raw IRC message.
990 @defun hooks/topic nick channel new-topic
991 This hook is called when a user changes the topic in a channel.
993 @var{nick} is the user who set the topic. This may be the bot.
995 @var{channel} is the channel that's topic was changed.
997 @var{new-topic} is the new topic.
1000 @node Sent Message Hooks, DCC CHAT Hooks, Received Message Hooks, Hook Types
1001 @subsubsection Sent Message Hooks
1003 These hooks are called when the bot sends a message. @var{mynick} is
1004 always the bot's nick and will not be documented in each hook
1007 @defun hooks/send/public mynick channel message
1008 This hook is called when the bot sends a normal message to a channel.
1010 @var{channel} is the channel to which the bot sent the message.
1012 @var{message} is the message the bot sent.
1015 @defun hooks/send/message mynick to message
1016 This hook is called when the bot sends a private message to a user.
1018 @var{to} is the nick of the user to whom the message was sent.
1020 @var{message} is the message that was sent.
1023 @defun hooks/send/action mynick to message
1024 This hook is called when the bot sents an action to a channel or a
1027 @var{to} is the channel or nick of the user to which the action was
1030 @var{message} is the text of the action.
1033 @defun hooks/send/ctcp mynick to command message
1034 This hook is called when the bot sends a CTCP message @emph{other
1035 than} an ACTION to a channel or user.
1037 @var{to} is the channel or nick of the user to which the CTCP was
1040 @var{command} is the CTCP command that was sent.
1042 @var{message} is a string containing the arguments to the CTCP command.
1045 @defun hooks/send/who who
1046 This is called when the bot sends a WHO message. The regex is matched
1047 on @var{who}, which is also passed as the only argument to your
1050 @var{who} is the channel or nick that was WHOed.
1053 @defun hooks/send/whois nick
1054 This is called when the bot sends a WHOIS message. The regex is
1055 matched on @var{nick}, which is also passed as the only argument to
1058 @var{nick} is the nickname of the person who was WHOISed.
1061 @node DCC CHAT Hooks, Miscellaneous Hooks, Sent Message Hooks, Hook Types
1062 @subsubsection DCC CHAT Hooks
1064 These hooks are called when a user initializes a DCC CHAT and when the
1065 bot receives messages from the user in a DCC CHAT.
1067 @defun hooks/dcc/chat-begin from
1068 This hook is called when a user begins a DCC CHAT with the bot.
1069 @var{from} is the user's address in the form @samp{nick!user@@host}.
1072 @defun hooks/dcc/chat-end address
1073 This hook is called when a DCC CHAT is purged after being idle for a
1074 while, or when the user closes the DCC CHAT. As such, you cannot write
1075 any more data to the DCC CHAT.
1077 @var{address} is the address (nick!user@@host) of the person on the
1078 other side of the DCC.
1081 @defun hooks/dcc/chat-message from message
1082 This hook is called when a user sends a message to the bot through
1085 @var{from} is the user's address in the form @samp{nick!user@@host}.
1087 @var{message} is the message the user sent to the bot.
1090 @node Miscellaneous Hooks, , DCC CHAT Hooks, Hook Types
1091 @subsubsection Miscellaneous Hooks
1093 @defun hooks/flood nick
1094 This hook is called when a user is detected flooding the bot.
1096 @var{nick} is the nickname of the user flooding the bot.
1099 @defun hooks/timer time
1100 This hook is called once a minute. The regex is @strong{not} used.
1102 @var{time} is the in zero-padded @code{hh:mm} format.
1106 @node Sending Messages, Misc Scripting Stuff, Hooks, Scripting
1107 @section Sending Messages
1109 There are several types of messages you can send with Bobot++ from
1110 scripts. They are split into High and Low level message sending
1111 functions. Most bots will only use the high level functions, but the
1112 low level ones are provided for when a bot needs to do things like
1113 send raw IRC messages or CTCP commands.
1116 * High Level Message Functions::
1117 * Low Level Message Functions::
1120 @node High Level Message Functions, Low Level Message Functions, Sending Messages, Sending Messages
1121 @subsection ``High Level'' Message Functions
1123 @defun bot:say channel message
1124 Send a public or private @var{message} to @var{channel}.
1126 Sends a normal text message, as if a user had typed it in. The
1127 @var{dest} can be a nickname or a channel.
1130 @defun bot:action channel message
1131 Send an ``action'' type @var{message} to @var{channel}
1135 @defun bot:msg target message
1136 @defunx bot:say target message
1137 Send a public or private message to @var{target}.
1139 @var{target} may be a channel or a nickname.
1141 In versions of Bobot++ prior to 2.1.8 @code{bot:say} could only send
1142 to channels, and @code{bot:msg} could only send private messages to
1143 users. They are aliases of the same command now, but it may be worth
1144 using them as they used to for clarity.
1147 @defun bot:notice target message
1148 Sends @var{message} as a NOTICE to @var{target}. @var{target} may be a
1149 user (nick) or a channel.
1152 @node Low Level Message Functions, , High Level Message Functions, Sending Messages
1153 @subsection ``Low Level'' Message Functions
1155 @c Add a url for rfc2812
1156 The ``Low Level'' messaging functions allow you to do things like send
1157 CTCP messages. You probably want to read rfc 2812 and the CTCP spec
1158 before using these. If you have no idea what these do, read rfc 2812
1159 (IRC Client Protocol) and CTCP spec. These functions all return
1160 @code{*unspecified*} always, so don't use the return value for
1163 @defun bot:ctcp to command message
1164 @var{to} is the target of your CTCP message, @var{command} is the
1165 CTCP command, and @var{message} is the message (or arguments) of the
1166 command. Make sure to @code{bot:ctcp-quote} the message!
1169 @defun bot:ctcp-reply to command message
1170 @var{to} is the target of your CTCP reply, @var{command} is the
1171 CTCP command, and @var{message} is the message (or arguments) of the
1172 command. Make sure to @code{bot:ctcp-quote} the message!
1174 This is used to reply to a ctcp that the bot has received.
1177 @node Misc Scripting Stuff, , Sending Messages, Scripting
1178 @section Misc. Scripting Stuff
1180 These are a few useful things that I thought people writing scripts
1184 If you want to execute code when the bot exits, just do
1185 @code{add-hook! bot:exit-hook @var{thunk}} where @var{thunk} is an
1186 argumentless procedure (a thunk). When the bot exits your thunk will
1190 [ I didn't know where to put any of these, so I just stuck them in
1193 There probably needs to be several sections added, like dealing with
1194 users (kicking, added, etc), dealing with the bot (channels, nickname
1195 of the bot, etc), server issues (serverlist), useful tools (nslookup,
1196 whois), and do on. ]
1200 @defun bot:adduser nick-or-mask cbannel-mask level prot auto-op
1201 Adds an user to the userlist, for a @code{nick!user@@host} matching the
1202 one given, on a channel matching the @var{channelMask} given.
1204 @multitable @columnfractions 0.33 0.33 0.33
1205 @item The @var{level} can be: @tab The @var{prot} can be: @tab The @var{auto-op} can be:
1206 @item 0 - No level @tab 0 - No protection @tab 0 - No auto-op
1207 @item 1 - User @tab 1 - No ban @tab 1 - Op on join
1208 @item 2 - Trusted User @tab 2 - No kick @tab
1209 @item 3 - Friend @tab 3 - No deop @tab
1210 @item 4 - Master @tab @tab
1216 @defun bot:addserver hostname ip-address [portnumber]
1217 Adds the server specified by @var{hostname} or @var{ip-address} to
1222 @defun bot:addshit nick-or-mask channel-mask level [time reason]
1223 Adds an user to the shitlist, for a nick!user@@host matching the
1224 one given, on a channel matching the @var{channelMask} given.
1227 The @var{level} can be:
1230 2 - Kick and Ban on join
1231 3 - Kick and Ban on join, no deban
1237 @defun bot:ban channel mask-or-nick
1238 Bans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
1239 user to ban with a @var{mask}.
1243 @defun bot:change-command-level nick-or-mask channel-mask new-level
1244 Gives @var{nick} or @var{mask} level @var{new-level} on channel(s)
1245 @var{channel-mask}. Note that you can not change level for someone
1246 whose level is greater than yours, and that you can not give a
1247 level greater than yours.
1251 @defun bot:cycle channel
1252 Makes the bot leave and join @var{channel}.
1256 @defun bot:deban channel mask-or-nick
1257 Debans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
1258 user to deban with a @var{mask}.
1262 @defun bot:delserver server-number
1263 Deletes server from server list whose number in the server list
1264 is @var{server-number}
1268 @defun bot:deluser nick-or-mask channel-mask
1269 Removes @var{nick} or @var{mask} from the userlist.
1273 @defun bot:delshit nick-or-mask channel-mask
1274 Removes @var{nick} or @var{mask} from the shitlist.
1278 @defun bot:deop channel mask-or-nick
1279 Deops @var{mask} or @var{nick} on @var{channel}.
1283 @defun bot:die reason
1284 Makes the bot stop immediately.
1292 @defun bot:invite channel nick
1293 Invites @var{nick} on @var{channel}.
1297 @defun bot:join channel
1298 Makes the bot join @var{channel}.
1302 @defun bot:keep channel modes
1303 Sets the @var{modes} that the bot will keep for @var{channel}.
1308 @defun bot:kick channel mask-or-nick [reason]
1309 Kicks @var{mask} or @var{nick} out of @var{channel}, because of @var{reason}.
1310 You need to be a trusted user to use a @var{mask}.
1314 @defun bot:kickban channel mask-or-nick [reason]
1315 Bans then kicks @var{mask} or @var{nick} out of @var{channel},
1316 because of @var{reason}.
1317 You need to be a trusted user to use a @var{mask}.
1321 @defun bot:lock channel
1322 Locks topic on @var{channel}.
1327 [ Probably returns the log port? ]
1331 @defun bot:mode channel mode-string
1332 Sends @var{mode-string} as mode for @var{channel}.
1336 @defun bot:nextserver
1337 Makes the bot connect to the next server in its server list.
1341 @defun bot:nick nick
1342 Makes the bot use nickname @var{nick}.
1346 @defun bot:op channel nick
1347 Ops @var{nick} on @var{channel}.
1351 @defun bot:part channel
1352 Makes the bot leave @var{channel}.
1356 @defun bot:reconnect
1357 Makes the bot reconnect to its current server.
1361 @defun bot:server server-number
1362 Select the server to connect to. @var{server-number} is the number of
1363 the server in the serverlist.
1367 @defun bot:setfloodrate ?
1371 @defun bot:setversion ?
1375 @defun bot:tban channel nick-or-mask time
1376 Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds.
1380 @defun bot:tkban channel nick-or-mask time [reason]
1381 Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds,
1382 then kicks him/them because of @var{reason}.
1386 @defun bot:topic channel topic
1387 If no @var{topic} is given, prints @var{channel}'s topic. Otherwise,
1388 the bot will change @var{channel}'s topic to @var{topic}.
1391 @defun bot:unlock channel
1392 Makes the bot unlock topic on @var{channel}.
1395 @defun bot:who target
1396 Sends a WHO command to @var{target}. @var{target} may be either a
1400 @defun bot:whois nick
1401 Sends a WHOIS command to @var{nick}. @var{nick} @strong{must} be a
1402 nickname, you cannot send a WHOIS to a channel.
1406 @defun bot:getnickname
1407 [ Gets the bot's nickname? ]
1411 @defun bot:getserver
1415 @defun bot:getserverlist
1420 [ Flushes the socket to the server? ]
1424 @defun bot:flushport
1425 [ Flushes the log port? ]
1430 [ Returns a random number? What range? Why? ]
1434 @defun bot:delcommand
1435 [ Probably deletes a command added with @code{bot:addcommand} ? ]
1439 @defun bot:addtimer ? ?
1443 @defun bot:deltimer ?
1447 @defun bot:dcc-chat-send ? ?
1451 [ And what about the stuff defined in @file{bobot-utils.scm} ? I just
1452 added it here so it could be somewhere. There should also be a
1453 section dealing with modules. How to use them. What module scripts
1454 are in. What module bobot++ provided primites are in. And so on. ]
1457 @defun bot:log . messages
1458 Write as many @var{messages} as you want to the log. If the arg is a
1459 thunk it will be executed and it's output will be written to the log.
1462 @defun bot:load file
1465 @defun bot:load-module module-spec
1468 @defun bot:use-module module-spec
1471 @defun bot:match-not-channel regex
1472 match-not-channel adds a prefix regex to your @var{regex} so it
1473 doesn't match the sender or channel in a PUBLIC message
1476 @defun bot:match-to-me regex
1477 match-to-me matches text that was addressed to the bot with a
1478 ':', ',', or nothing after the bot name.
1481 @defun bot:sent-to-me? message
1484 @defun bot:ctcp-quote message
1485 Returns the CTCP quoted message
1486 Input @emph{MUST NOT} contain the trailing @code{\r\n}
1487 (it is added by the message sending code).
1491 @defvar %bot:loadpath
1494 @defun %bot:load-extensions
1499 @node Concept Index, Function Index, Scripting, Top
1500 @unnumbered Concept Index
1503 @node Function Index, Variable Index, Concept Index, Top
1504 @unnumbered Function Index
1507 @node Variable Index, , Function Index, Top
1508 @unnumbered Variable Index