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::
103 * User List Commands::
107 * Adding New Commands::
110 * Misc Scripting Stuff::
121 * Received Message Hooks::
122 * Sent Message Hooks::
124 * Miscellaneous Hooks::
128 * High Level Message Functions::
129 * Low Level Message Functions::
131 Misc. Scripting Stuff
139 @node Introduction, Configuration, Top, Top
140 @chapter Introduction
142 Bobot++ is a powerful IRC bot written in C++. It can be used
143 standalone as a channel maintenence bot, or extended to do almost
144 anything using Scheme scripts.
146 FIXME: Fill the intro in more?
148 @node Configuration, Using the Bot, Introduction, Top
149 @chapter Configuration
151 Bobot++ is easy to configure. See the @file{examples} directory for an
152 example configuration.
154 The main configuration file is @file{bot.conf}. There are several
155 auxiliary configuration files (a user list, aliases file, ban list,
156 and a script autoexec).
159 * Configuration File Placement::
160 * Configuration Files::
163 @node Configuration File Placement, Configuration Files, Configuration, Configuration
164 @section Configuration File Placement
166 Bobot++ will look in @file{/etc/bobotpp/default/} for its default
167 config if none is specified on the command line. Put the configuration
168 files you want to be loaded by default in this directory. If you are
169 not root, or you want to have your own personal configuration, put it
170 in @file{~/.bobotpp/config/default/}.
172 @node Configuration Files, , Configuration File Placement, Configuration
173 @section Configuration Files
183 @node bot.conf, bot.users, Configuration Files, Configuration Files
186 @file{bot.conf} contains key value pairs separated by @code{=}.
188 @code{<key> = <value>}
190 Comments are started with a @code{#} and cause the entire line to be
191 ignored. @emph{Note that this only works when the @code{#} is the first
192 character of the line}.
194 bot.conf is the main configuration file for a Bobot++. The available
195 configuration variables are listed below in the format ``@var{variable}
196 <default-value>: description''
198 A few of the options have more complex syntax, they are documented in
199 their own subsections.
208 @item @var{maxnicklength} <9>: The maximum length a valid nickname may
209 be. This should be set before setting the bot's nickname if it will be
210 more than nine characters long. Most IRC servers support nicknames
211 longer than nine characters, but Bobot++ still follows the old spec
212 and defaults to nine.
213 @item @var{nickname} <Bobot>: The nickname of the bot (@var{nick} is an
214 alias for @var{nickname})
215 @item @var{username} <bobot>: The IRC username of the bot
216 @item @var{cmdchar} <!>: The character that prefixes commands given to
217 the bot (@var{command} is an alias for @var{cmdchar})
218 @item @var{ircname} <I'm a bobot++!>: The IRC name (or 'real name') of
219 the bot (@var{realname} is an alias for @var{ircname})
220 @item @var{userlist} <bot.users>: Name of the file where the userlist is
222 @item @var{autoexecfile} <bot.autoexec>: Name of the file containing
223 Scheme code to be executed when the bot starts (only used if the bot
224 is compiled with scripting support)
225 @item @var{initfile} <bot.init>: Name of the file containing the
226 default command aliases
227 @item @var{shitlist} <bot.shit>: Name of the file where the shitlist
229 @item @var{logfile} <$LOGDIR/bot.log>: Location of the bot logfile
230 (set this to @file{/dev/null} to disable logging).
231 @item @var{server} <None>: This specifies the server to which the bot
232 will connect. Note that this has a special syntax @pxref{server
234 @item @var{channel} <None>: This specifies the channels the bot will join
235 when it starts up. This has a special syntax @pxref{channel
240 @node server syntax, channel syntax, bot.conf, bot.conf
241 @subsubsection server syntax
243 The server syntax in @file{bot.conf} allows you to specify an
244 alternate port to connect on, and a password to send the server.
246 You may use more than one server line; Bobot++ will attempt to connect
247 to the first one, and will connect to the next one in the list if it
248 fails. The bot will continue cycling through the server list until it
249 is able to connect to one. There is a command (@code{!cycle}) to make
250 the bot to cycle servers.
252 @var{server} = @var{server_name} [@var{port} [@var{password}]]
254 This will make Bobot++ attempt to connect to @var{server_name} on port
255 @var{port} with the password @var{password}. @var{server_name} should
256 be the address of the server. @var{port} and @var{password} are
259 @node channel syntax, , server syntax, bot.conf
260 @subsubsection channel syntax
262 The channel syntax in @file{bot.conf} allows you to specify the
263 initial modes the bot should set on a channel, the modes the bot
264 should maintain, and a key if the channel needs it.
266 You may have any number of channel lines. When Bobot++ starts it will
267 attempt to join and gain operator status in every channel listed.
270 @var{name}:@var{initial_modes}:@var{modes_to_keep}:@var{channel_key}
272 The bot will join @var{name} and set the channel modes to
273 @var{initial_modes} (e.g. ``nt'') if it is able to gain operator
274 status. It will then maintain @var{modes_to_keep}. If the channel
275 requires a key to enter simply set @var{channel_key}. Every argument
276 except for @var{name} is optional.
281 @var{channel} = #foo:nt:nt:bar
284 The bot will join @code{#foo} with the channel key @code{bar} and will
285 then maintain the modes @code{nt}.
288 @var{channel} = #bar:::
291 The bot will join @code{#bar} and will not set any modes nor will it
292 attempt to maintain any modes.
294 @node bot.users, bot.init, bot.conf, Configuration Files
295 @subsection bot.users (User List)
297 @file{bot.users} is the default file name of the userlist. It may be
298 changed in @file{bot.conf} via the @var{userlist} option. @strong{You
299 must add an entry for yourself manually.} You will probably want to
300 add other entries using the IRC command interface as it is more
301 intuitive than editing the file by hand.
303 The file contains lines with the format:
305 @samp{@var{host_mask}:@var{channel_mask}:@var{level}:@var{protection}:@var{auto-op}:@var{expiration}:@var{password}}
309 @item @var{host_mask} is the host mask
310 (e.g. @samp{*!*username@*.domain.com}) of the user
312 @item @var{channel_mask} is a channel mask of the channels that the user
313 has priviliges to use the bot in (e.g. @samp{*} for all channels,
314 @samp{#*} for all non-local channel, @samp{#foo*} for all channels
315 starting with ``foo,'' @samp{#bar} for channel ``#bar'' only, etc.)
317 @item @var{level} is the user level of the user (@ref{User Levels}).
319 @item @var{protection} is the protection level of the user
322 @item @var{auto-op} is set to control whether a user is automatically
323 given operator priviliges on channel entry (@ref{Automatic Op}).
325 @item @var{expiration} is the UNIX timestamp of when the user entry
326 becomes invalid. Setting this to -1 will make the entry permanent.
328 @item @var{password} is the password the user must supply to the bot
329 to authenticate. This can be set to @code{*NONE*} to not have a password.
333 @node bot.init, bot.autoexec, bot.users, Configuration Files
334 @subsection bot.init (Command Aliases)
336 This file stores a list of IRC command aliases. The filename may be
337 changed in @file{bot.conf} via the @var{initfile} option. You use this
338 file to set up aliases for IRC commands, e.g. to make @code{!a} call
339 @code{!adduser}. This way you can save typing for commonly used commands.
341 The format of a line in the file is:
342 @var{alias} @var{command}
344 This will make @var{alias} call @var{command}. e.g. @samp{t topic}
345 will make @code{!t New Topic} set the current channel's topic to ``New
346 Topic,'' just as if you had used @code{!topic New Topic}.
348 @node bot.autoexec, bot.shit, bot.init, Configuration Files
349 @subsection bot.autoexec (Scheme Init File)
351 This file is only used when Bobot++ is compiled with scripting
352 support. The name of the autoexec file can be changed in
353 @file{bot.conf} via the @var{autoexecfile} option.
355 The contents of this file are evaluated by Guile when the bot
356 starts. You can use this to do things like loading a few default
357 modules when the bot starts.
359 @node bot.shit, , bot.autoexec, Configuration Files
360 @subsection bot.shit (Ban/Shit List)
362 This file stores the ban list. The name may be changed in
363 @file{bot.conf} via the @var{shitlist} option. You will most likely
364 want to use the IRC command interface to edit this file instead of
367 The file contains lines in the form:
369 @samp{@var{host_mask}:@var{channel_mask}:@var{level}:@var{expiration}:@var{reason}}
373 @item @var{host_mask} is the host mask
374 (e.g. @samp{*!*username@*.domain.com}) of the user
376 @item @var{channel_mask} is a channel mask of the channels that the user
377 is banned on (e.g. @samp{*} for all channels,
378 @samp{#*} for all non-local channel, @samp{#foo*} for all channels
379 starting with ``foo,'' @samp{#bar} for channel ``#bar'' only, etc.
381 @item @var{level} is a number specifying if the bot should not allow
382 the user to gain ops, to kick the user upon joining, or to prevent the
383 user from being debanned by other users. @ref{Shit Levels} for
384 information on the available levels.
386 @item @var{expiration} is the UNIX timestamp of when the shit entry
387 becomes invalid. This may be set to -1 to make it valid forever.
389 @item @var{reason} is text that is sent to the user when they are
390 kicked or banned from the channel.
394 @node Using the Bot, Scripting, Configuration, Top
395 @chapter Using Bobot++
397 Using Bobot++ is easy. This chapter covers starting the bot, a few
398 Bobot++ specific concepts, and using the built-in commands of the bot.
403 * Built-In Commands::
406 @node Starting the Bot, Concepts, Using the Bot, Using the Bot
407 @section Starting the Bot
409 The bot is usually installed with the binary name @file{bobotpp}. It
410 accepts the following command line arguments.
413 @item @code{[--help][-h]} - Shows detailed help and exits
414 @item @code{[--version][-v]} - Shows version information and exits
415 @item @code{[--no-background][-b]} - Run bobot++ in the foreground
416 @item @code{[--config-file file][-f]} - Use file instead of @file{bot.conf}
417 @item @code{[--config-dir dir][-d]} - Use dir as dir to load config file from
418 @item @code{[--config dir][-c]} - Search your config path (defaults to
419 @file{@var{$HOME}/.bobotpp/config/} and then @file{/etc/bobotpp/}) for
420 dir and then loads your config data using dir
421 @item @code{[--sys-config dir][-s]} - Looks for config in
422 @file{/etc/bobotpp/dir}. Note that the user dir is still searched
424 @item @code{[--user-config dir][-u]} - Looks for config in
425 @file{@var{$HOME}/.bobotpp/config/dir/}. Note that the system dir is
426 still searched after this if dir is not found.
427 @item @code{[--debug][-D]} Makes Bobot++ print debugging info and run
429 @item @code{[--debug-scripts][-S]} Enables the Guile debugging
430 evaluator for verbose script errors and backtraces while still running
431 the bot in the background.
434 The default configuration is read from
435 @file{@var{$HOME}/.bobotpp/config/default/} and then
436 @file{/etc/bobotpp/default/} if the user config is not found.
438 The bot defaults to running in the background as a daemon.
440 @node Concepts, Built-In Commands, Starting the Bot, Using the Bot
443 There are a few general concepts that a user of Bobot++ should know
453 @node User Levels, Protection, Concepts, Concepts
454 @subsection User Levels
456 There are several user levels available in Bobot++ to provide gradated
457 access to commands. @command{!adduser} and @file{bot.users} use the
458 numeric code; Scheme uses the textual name for the level. By default
459 (if the user is not found in the userlist) a user has access to
460 commands with the level @code{bot:user-none}.
464 @item @code{bot:user-none} - No @strong{built-in} commands may be
465 executed @emph{by default} (commands may be added from Scheme that can
466 be executed by users of level none and the level required to execute a
467 command may be changed from Scheme).
469 @item @code{bot:user-user} - Will be able to execute most commands but
470 not all and cannot use masks on kicks and bans.
472 @item @code{bot:user-trusted} - For built-ins with a default
473 configuration this user has access to the same set of commands as an
474 @code{user} but may use masks on kicks and bans. Scheme commands may
475 be added which require a user to be of this level.
477 @item @code{bot:user-friend} - In the default configuration a user who
478 is a friend will be able to do everything short of stopping the
479 bot. Again, there may be user added commands that require a higher
482 @item @code{bot:user-master} - This is the highest user level and has
483 access to every feature of the bot.
487 @node Protection, Automatic Op, User Levels, Concepts
488 @subsection Protection
490 A user added via Scheme, the @file{bot.users} file, or
491 @command{!adduser} may be protected from being deoped, kicked, or
492 banned. The user list and IRC commands use the numeric codes, Scheme
493 uses the symbolic names.
496 @item @code{bot:protection/none} No protection
497 @item @code{bot:protection/no-ban} No ban. If a user is banned the bot will unban him..
498 @item @code{bot:protection/no-kick} No kick. The user may still be kicked but the bot will kickban
499 the user who kicked the protected user.
500 @item @code{bot:protection/no-deop} No deop. The bot will ensure that the user always maintains
504 @node Automatic Op, Shit Levels, Protection, Concepts
505 @subsection Automatic Op
507 A user may be automatically given operator status upon entering a
508 channel. Scheme uses the symbolic name, the user list
509 (@file{bot.users}) and IRC commands use the numeric value.
512 @item @code{bot:aop/no} Do not automatically op the user
513 @item @code{bot:aop/yes} Do automatically op the user
516 @node Shit Levels, , Automatic Op, Concepts
517 @subsection Shit Levels
519 The shit list and shit list related commands use different levels to
520 define how much the bot hates a user. Scheme uses the symbolic names,
521 the shit list and IRC commands use the numbers.
524 @item @code{bot:shit/none} The bot doesn't hate the user (this is the
526 @item @code{bot:shit/no-op} The bot will deop the user any time he
527 gains operator priviliges in the channel
528 @item @code{bot:shit/no-join} The bot will kick and ban the user when he
530 @item @code{bot:shit/no-deban} The bot will kick and ban usre when he
531 joins the channel, and will prevent other users from debanning him.
534 @node Built-In Commands, , Concepts, Using the Bot
535 @section Built-In Commands
537 Bobot++ has many built-in commands that make it useful without
538 scripting support. The reference leaves off the command char; remember
539 to use whatever you defined the command char to be in
540 @file{bot.conf}. If a command needs the channel name then you must
541 specify the channel as the first argument to the command when private
542 messaging the bot a command.
546 * User List Commands::
549 @node Message Commands, User List Commands, Built-In Commands, Built-In Commands
550 @subsection Message Commands
552 @multitable @columnfractions 0.20 0.15 0.15 0.50
553 @item @sc{command} @tab @sc{Needs Channel} @tab @sc{Min Level to Use}
554 @tab @sc{Description}
556 @item @command{action} @option{do} @tab Yes @tab @var{USER} @tab
557 Causes the bot to perform the action @option{do} in the current
560 @item @command{do} @tab @tab @tab
562 @item @command{msg} @tab @tab @tab
564 @item @command{say} @tab Yes @tab @tab Makes the bot say @var{message}
570 @node User List Commands, , Message Commands, Built-In Commands
571 @subsection User List Commands
573 @multitable @columnfractions 0.20 0.15 0.15 0.50
574 @item @sc{command} @tab @sc{Needs Channel} @tab @sc{Min Level to Use} @tab @sc{Description}
577 @item @command{adduser} @tab @tab @tab
579 @item @command{addserver} @tab @tab @tab Adds the server specified by
580 @var{host name} or @var{ip address} to the server list.
582 @item @command{addshit} @tab @tab @tab
584 @item @command{alias} @tab @tab @tab Makes an alias, and adds the
585 function @var{new name}, that will do exactly the same command as
588 @item @command{ban} @tab @tab @tab Bans @var{mask} or @var{nick} from
589 @var{channel}. You need to be a trusted user to ban with a
592 @item @command{banlist} @tab @tab @tab
594 @item @command{channels} @tab @tab @tab Prints the channel(s) where
595 the bot is currently.
597 @item @command{cycle} @tab Yes @tab @tab Makes the bot leave and join
600 @item @command{dcclist} @tab @tab @tab Gives the list of all DCC Chat
603 @item @command{deban} @tab Yes @tab @tab Debans @var{mask} or
604 @var{nick} from @var{channel}. You need to be a trusted user to deban
607 @item @command{delserver} @tab @tab @tab Deletes server from server
608 list whose number in the server list is @var{server number}.
610 @item @command{deluser} @tab @tab @tab Removes @var{nick} or
611 @var{mask} from the userlist.
613 @item @command{delshit} @tab @tab @tab Removes @var{nick} or
614 @var{mask} from the shitlist.
616 @item @command{deop} @tab Yes @tab @tab Deops @var{mask} or @var{nick}
619 @item @command{die} @tab @tab @tab Makes the bot stop immediately.
623 @item @command{execute} @tab @tab @tab @strong{Only available if
624 scripting support is enabled}
626 @item @command{help} @tab @tab @tab
628 @item @command{ident} @tab @tab @tab Identifies you on the bot. Note
629 that you should not use this command in public @dots{}
631 @item @command{invite} @tab Yes @tab @tab Invites @var{nick} on
634 @item @command{join} @tab @tab @tab Makes the bot join @var{channel}.
636 @item @command{keep} @tab Yes @tab @tab Sets the @var{modes} that the
637 bot will keep for @var{channel}.
639 @item @command{kick} @tab Yes @tab @tab Kicks @var{mask} or @var{nick}
640 out of @var{channel}, because of @var{reason}. You need to be a
641 trusted user to use a @var{mask}.
643 @item @command{kickban} @tab Yes @tab @tab Bans then kicks @var{mask}
644 or @var{nick} out of @var{channel}, because of @var{reason}. You need
645 to be a trusted user to use a @var{mask}.
647 @item @command{load} @tab @tab @tab Reloads the userlist from disk.
649 @item @command{loadscript} @tab @tab @tab @strong{Only available if
650 scripting support is enabled}
652 @item @command{lock} @tab @tab @tab Locks topic on @var{channel}.
654 @item @command{mode} @tab Yes @tab @tab Sends @var{mode string} as
655 mode for @var{channel}.
659 @item @command{names} @tab Yes @tab @tab Shows the nicknames and
660 status of users on @var{channel}.
662 @item @command{nextserver} @tab @tab @tab Makes the bot connect to the
663 next server in its server list.
665 @item @command{nick} @tab @tab @tab Makes the bot use nickname @var{nick}.
667 @item @command{nslookup} @tab @tab @tab Does a nameserver query about
668 @var{nick} host, @var{host} or @var{ip address}.
670 @item @command{op} @tab Yes @tab @tab Ops @var{nick} on @var{channel}.
672 @item @command{part} @tab Yes @tab @tab Makes the bot leave @var{channel}.
674 @item @command{password} @tab @tab @tab Changes your password on the
675 bot. Use @code{NONE} as password if you want to clear it. Do not use this
678 @item @command{reconnect} @tab @tab @tab Makes the bot reconnect to
681 @item @command{rspymessage} @tab @tab @tab Removes you from the spy
684 @item @command{save} @tab @tab @tab Saves the userlist.
688 @item @command{server} @tab @tab @tab Select the server to connect
689 to. @var{server number} is the number of the server in the serverlist.
691 @item @command{serverlist} @tab @tab @tab Shows the bot's serverlist.
693 @item @command{setfloodrate} @tab @tab @tab
695 @item @command{setversion} @tab @tab @tab
697 @item @command{shitlist} @tab @tab @tab Shows the bot's shitlist.
699 @item @command{spylist} @tab @tab @tab Shows the bot's spylist.
701 @item @command{spymessage} @tab @tab @tab Adds you to the spylist
703 @item @command{stats} @tab Yes @tab @tab Gives @var{channel}'s statistics.
705 @item @command{tban} @tab Yes @tab @tab Bans @var{nick} or @var{mask}
706 from @var{channel} for @var{time} seconds.
708 @item @command{tkban} @tab Yes @tab @tab Bans @var{nick} or @var{mask}
709 from @var{channel} for @var{time} seconds, then kicks him/them because
712 @item @command{topic} @tab Yes @tab @tab If no @var{topic}is given,
713 prints @var{channel}'s topic. Otherwise, the bot will change
714 @var{channel}'s topic to @var{topic}.
716 @item @command{unlock} @tab Yes @tab @tab Makes the bot unlock topic
719 @item @command{userlist} @tab @tab @tab Shows the bot's userlist
721 @item @command{who} @tab Yes @tab @tab Show your level on @var{channel}
723 @item @command{whois} @tab Yes @tab @tab Shows information about
724 @var{nick} on @var{channel}
728 @node Scripting, Concept Index, Using the Bot, Top
731 Bobot++'s most powerful feature is its scripting system. You write
732 scripts using Guile Scheme. This manual does not cover how to use
733 Guile or how to learn Scheme. @xref{Top, , Guile Reference Manual,
734 guile, The Guile Reference Manual}, for the Guile reference manual and
735 @url{http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html} for
736 a good tutorial on Scheme.
738 Note that in previous versions the scripting commands where in the
739 form @code{bot-@var{function}}. They are now in the form
740 @code{bot:@var{function}}. The old names are still available, but are
741 deprecated and will be removed in Bobot++ 3.0. New commands are only
742 available with the @code{bot:} prefix. The command @command{perl -pi
743 -e ``s/bot-/bot:/g'' @var{your-files}} should be enough to convert
744 your code to use the new functions.
746 @strong{NOTE}: All arguments to functions and hooks called by the bot
747 are strings unless otherwise specified.
750 * Adding New Commands::
753 * Misc Scripting Stuff::
758 @node Adding New Commands, Hooks, Scripting, Scripting
759 @section Adding New Commands
761 Adding a new command is simple. To register a new command use
762 @code{bot:addcommand}.
764 @defun bot:addcommand name func needs-channel? num-of-args min-level
766 The @var{name} is a string representing the name of the command being
767 added. @var{func} is a function accepting @var{num-of-args}
768 arguments. @var{needs-channel?} is a bool that is true if the function
769 needs the channel name as its first arg, and false otherwise.
770 @var{num-of-args} is the number of args @var{func} will take and must
771 be within zero (0) and twenty (20). @var{min-level} is one of the
772 @ref{User Levels}. A user must be at least a @var{min-level} user to
773 use the new command. None of the arguments are guaranteed to be
774 passed; if they aren't they are set to the empty string @code{""}. An
775 example of a new command would be:
778 (define (hello channel name)
779 (if (string=? name "")
780 (bot:say channel "Hello world!")
781 (bot:say channel (string-append "Hello " name "!")))
783 (bot:addcommand "hello" hello #t 2 0)
786 This will display ``Hello World!'' if called as @kbd{!hello} and
787 ``Hello World @var{USER}'' if called as @kbd{!hello @var{USER}}.
790 @node Hooks, Sending Messages, Adding New Commands, Scripting
793 @cindex Background on Hooks
794 Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
795 and tiny fugue (a MUD bot) hooks with a little bit of extra stuff
796 added in. A hook is called when a regular expression is matched
797 against a message sent to or by the bot.
799 Bobot++ uses different hook types for each IRC message type, and also
800 includes a hook for accessing raw irc messages. Hooks are tagged with
801 a priority and a flag that specifies whether to call the next hook
802 that matches after calling the current one or to stop
805 Hooks are processed from the highest to lowest priority, with
806 fallthrough hooks of equal priority to non-fallthrough hooks being
814 @node Creating a Hook, Hook Types, Hooks, Hooks
815 @subsection Creating a Hook
817 To add a new hook you use the function @code{bot:addhook}.
819 @defun bot:addhook type regex function [pri fall name]
820 @var{type} specifies the type of hook (the types of hooks are listed
821 in @ref{Hook Types}).
823 @var{regex} is a standard regular expression. If
824 @var{regex} is matched, @var{function} will be called.
826 @var{function} will take a different number of args depending on the
829 @var{pri} specifies the priority of the hook---higher priority hooks
830 are executed first. This argument is optional and defaults to
833 @var{fall} is @code{#t} if the hook is a fallthrough hook and
834 @code{#f} is the hook is not a fallthrough hook. This arg is also
835 optional and defaults to @code{#t}.
837 @var{name} is the optional name of the hook that defaults to
838 @code{"DEFAULT"}. If you set the name then you can have more than
839 one hook that matches the same regexp, as long as they have the same
840 name. E.g. in a log script you could have the regexps for the log
841 function all be @code{".*"} and set their names to @code{"log"} to
842 avoid a conflict with other hooks.
845 @node Hook Types, , Creating a Hook, Hooks
846 @subsection Hook Types
848 The following sections document the different hooks Bobot++ exposes.
850 The general format of each hook description is as if it were a
851 function to be defined, but these describe the function to be passed
852 to @code{bot:add-hook}. Do @emph{not} name your functions these
855 That said, here is the list of available hooks functions.
859 * Received Message Hooks::
860 * Sent Message Hooks::
862 * Miscellaneous Hooks::
865 @node Received Message Hooks, Sent Message Hooks, Hook Types, Hook Types
866 @subsubsection Receieved Message Hooks
868 The following hooks are triggered when a mesage is received by the bot.
870 @defun hooks/action from to action
871 This hook is triggered when someone performs an action.
873 @var{from} is the nickname the person that performed the
876 @var{to} is the target of the action, which is either a channel or the
877 Bot's nick if the user private messages the bot.
879 @var{action} is the text of the action. E.g. if someone did @samp{*
880 foobar does baz}, then @var{action} would be the string @code{"does
884 @defun hooks/nickname old-nick new-nick
885 This hook is called when someone changes his nickname from
886 @var{old-nick} to @var{new-nick}.
889 @defun hooks/signoff nick message
890 This hook is called when someone signs off of IRC.
892 @var{nick} is the nickname of the person signing off.
894 @var{message} is his quit message
897 @defun hooks/ctcp nick to command rest
898 This hook is called when a CTCP request is received by the bot.
900 @var{nick} is the nickname of the sender.
902 @var{to} is the target of the CTCP request. This will either be a
903 channel the bot is in, or the nickname of the bot.
905 @var{command} is the CTCP command issued.
907 @var{rest} contains the arguments to the CTCP command.
910 @defun hooks/ctcp-reply nick command rest
911 This hook is called when a CTCP REPLY is received. This occurs when
912 the bot has sent a CTCP request to another client. The CTCP REPLY is
913 always addressed to the bot directly.
915 @var{nick} is the nickname of the person who replied.
917 @var{command} is the command to which @var{nick} is replying.
919 @var{rest} contains the body of the reply.
922 @defun hooks/disconnect server intentional
923 This is called when the bot is disconnected from a server.
925 @var{server} is the hostname of the server from which the bot was
928 @var{intentional} is a flag set to @code{#t} when the bot disonnected
929 from the server as the result of a command (issued by a user from IRC,
930 SIGHUP, or from a script), or @code{#f} when the bot disconnected from
931 the server unintentionally..
934 @defun hooks/invite nick channel
935 This hook is called when a user invited the bot to join a channel.
937 @var{nick} is the nickname of the user who sent the invite.
939 @var{channel} is the channel to which the bot was invited.
942 @defun hooks/join nick channel
943 This is called when a user or the bot joins a channel.
945 @var{nick} is the nickname of the user who joined @var{channel}. This
946 may be the bot's nickname (the IRC server sends the JOIN command back
947 to the the bot after it joins a channel).
949 @var{channel} is the channel that was joined
952 @defun hooks/kick target from channel reason
953 This hook is called when a user, including the bot, is kicked out of a
956 @var{target} is the nick of the user who was kicked. This may be the
959 @var{from} is the nick of the user who issued the kick. This may also
962 @var{channel} is the channel the kick was issued in.
964 @var{reason} is the reason the user was kicked.
967 @defun hooks/part nick channel
968 This hook is called when a user parts a channel.
970 @var{nick} is the user who parted the channel. This may be the bot.
972 @var{channel} is the channel from which the user parted.
975 @defun hooks/mode nick target modes
976 This hook is called when someone sets the modes of @var{target}.
978 @var{nick} is the user who set the modes. This may be the bot.
980 @var{target} is the target of the MODE command. This may be a
981 channel or a user. If it is a user, it may be the bot.
983 @var{modes} is the MODE string.
986 @defun hooks/message nick message
987 This hook is called when someone sends a private message to the bot.
989 @var{nick} is the nickname of the user who sent the message.
991 @var{message} is the message the user sent.
994 @defun hooks/notice nick message
995 This hook is called when a user send a private notice to the bot.
997 @var{nick} is the user who sent the notice.
999 @var{message} is the message the user sent.
1002 @defun hooks/public nick channel message
1003 This hook is called when a user sends a normal message to a channel.
1005 @var{nick} is the user who sent the message.
1007 @var{channel} is the channel to which the message was sent.
1009 @var{message} is the message that was sent.
1012 @defun hooks/public-notice nick channel message
1013 This hook is called when a user send a notice to a channel.
1015 @var{nick} is the user who sent the notice.
1017 @var{channel} is the channel to which the notice was sent.
1019 @var{message} is the message that was sent.
1022 @defun hooks/raw raw-message
1023 This hook is called every time a message is received. This matches on
1024 the raw message text and passes the hook function the raw IRC message.
1026 @var{raw-message} is the raw IRC message.
1029 @defun hooks/topic nick channel new-topic
1030 This hook is called when a user changes the topic in a channel.
1032 @var{nick} is the user who set the topic. This may be the bot.
1034 @var{channel} is the channel that's topic was changed.
1036 @var{new-topic} is the new topic.
1039 @node Sent Message Hooks, DCC CHAT Hooks, Received Message Hooks, Hook Types
1040 @subsubsection Sent Message Hooks
1042 These hooks are called when the bot sends a message. @var{mynick} is
1043 always the bot's nick and will not be documented in each hook
1046 @defun hooks/send/public mynick channel message
1047 This hook is called when the bot sends a normal message to a channel.
1049 @var{channel} is the channel to which the bot sent the message.
1051 @var{message} is the message the bot sent.
1054 @defun hooks/send/message mynick to message
1055 This hook is called when the bot sends a private message to a user.
1057 @var{to} is the nick of the user to whom the message was sent.
1059 @var{message} is the message that was sent.
1062 @defun hooks/send/action mynick to message
1063 This hook is called when the bot sents an action to a channel or a
1066 @var{to} is the channel or nick of the user to which the action was
1069 @var{message} is the text of the action.
1072 @defun hooks/send/ctcp mynick to command message
1073 This hook is called when the bot sends a CTCP message @emph{other
1074 than} an ACTION to a channel or user.
1076 @var{to} is the channel or nick of the user to which the CTCP was
1079 @var{command} is the CTCP command that was sent.
1081 @var{message} is a string containing the arguments to the CTCP command.
1084 @defun hooks/send/who who
1085 This is called when the bot sends a WHO message. The regex is matched
1086 on @var{who}, which is also passed as the only argument to your
1089 @var{who} is the channel or nick that was WHOed.
1092 @defun hooks/send/whois nick
1093 This is called when the bot sends a WHOIS message. The regex is
1094 matched on @var{nick}, which is also passed as the only argument to
1097 @var{nick} is the nickname of the person who was WHOISed.
1100 @node DCC CHAT Hooks, Miscellaneous Hooks, Sent Message Hooks, Hook Types
1101 @subsubsection DCC CHAT Hooks
1103 These hooks are called when a user initializes a DCC CHAT and when the
1104 bot receives messages from the user in a DCC CHAT.
1106 @defun hooks/dcc/chat-begin from
1107 This hook is called when a user begins a DCC CHAT with the bot.
1108 @var{from} is the user's address in the form @samp{nick!user@@host}.
1111 @defun hooks/dcc/chat-end address
1112 This hook is called when a DCC CHAT is purged after being idle for a
1113 while, or when the user closes the DCC CHAT. As such, you cannot write
1114 any more data to the DCC CHAT.
1116 @var{address} is the address (nick!user@@host) of the person on the
1117 other side of the DCC.
1120 @defun hooks/dcc/chat-message from message
1121 This hook is called when a user sends a message to the bot through
1124 @var{from} is the user's address in the form @samp{nick!user@@host}.
1126 @var{message} is the message the user sent to the bot.
1129 @node Miscellaneous Hooks, , DCC CHAT Hooks, Hook Types
1130 @subsubsection Miscellaneous Hooks
1132 @defun hooks/flood nick
1133 This hook is called when a user is detected flooding the bot.
1135 @var{nick} is the nickname of the user flooding the bot.
1138 @defun hooks/timer time
1139 This hook is called once a minute. The regex is @strong{not} used.
1141 @var{time} is the in zero-padded @code{hh:mm} format.
1145 @node Sending Messages, Misc Scripting Stuff, Hooks, Scripting
1146 @section Sending Messages
1148 There are several types of messages you can send with Bobot++ from
1149 scripts. They are split into High and Low level message sending
1150 functions. Most bots will only use the high level functions, but the
1151 low level ones are provided for when a bot needs to do things like
1152 send raw IRC messages or CTCP commands.
1155 * High Level Message Functions::
1156 * Low Level Message Functions::
1159 @node High Level Message Functions, Low Level Message Functions, Sending Messages, Sending Messages
1160 @subsection ``High Level'' Message Functions
1162 @defun bot:say channel message
1163 Send a public or private @var{message} to @var{channel}.
1165 Sends a normal text message, as if a user had typed it in. The
1166 @var{dest} can be a nickname or a channel.
1169 @defun bot:action channel message
1170 Send an ``action'' type @var{message} to @var{channel}
1174 @defun bot:msg target message
1175 @defunx bot:say target message
1176 Send a public or private message to @var{target}.
1178 @var{target} may be a channel or a nickname.
1180 In versions of Bobot++ prior to 2.1.8 @code{bot:say} could only send
1181 to channels, and @code{bot:msg} could only send private messages to
1182 users. They are aliases of the same command now, but it may be worth
1183 using them as they used to for clarity.
1186 @defun bot:notice target message
1187 Sends @var{message} as a NOTICE to @var{target}. @var{target} may be a
1188 user (nick) or a channel.
1191 @node Low Level Message Functions, , High Level Message Functions, Sending Messages
1192 @subsection ``Low Level'' Message Functions
1194 @c Add a url for rfc2812
1195 The ``Low Level'' messaging functions allow you to do things like send
1196 CTCP messages. You probably want to read rfc 2812 and the CTCP spec
1197 before using these. If you have no idea what these do, read rfc 2812
1198 (IRC Client Protocol) and CTCP spec. These functions all return
1199 @code{*unspecified*} always, so don't use the return value for
1202 @defun bot:ctcp to command message
1203 @var{to} is the target of your CTCP message, @var{command} is the
1204 CTCP command, and @var{message} is the message (or arguments) of the
1205 command. Make sure to @code{bot:ctcp-quote} the message!
1208 @defun bot:ctcp-reply to command message
1209 @var{to} is the target of your CTCP reply, @var{command} is the
1210 CTCP command, and @var{message} is the message (or arguments) of the
1211 command. Make sure to @code{bot:ctcp-quote} the message!
1213 This is used to reply to a ctcp that the bot has received.
1216 @node Misc Scripting Stuff, Scheme Commands, Sending Messages, Scripting
1217 @section Misc. Scripting Stuff
1219 These are a few useful things that I thought people writing scripts
1223 If you want to execute code when the bot exits, just do
1224 @code{add-hook! bot:exit-hook @var{thunk}} where @var{thunk} is an
1225 argumentless procedure (a thunk). When the bot exits your thunk will
1234 @node Scheme Commands, Query Functions, Misc Scripting Stuff, Scripting
1235 @section Scheme Commands
1237 These scheme functions are the same as the commands.
1238 They allow you to execute bot commands from scheme scripts.
1240 @defun bot:adduser nick-or-mask cbannel-mask level prot auto-op
1241 Adds an user to the userlist, for a @code{nick!user@@host} matching the
1242 one given, on a channel matching the @var{channelMask} given.
1244 @multitable @columnfractions 0.33 0.33 0.33
1245 @item The @var{level} can be: @tab The @var{prot} can be: @tab The @var{auto-op} can be:
1246 @item 0 - No level @tab 0 - No protection @tab 0 - No auto-op
1247 @item 1 - User @tab 1 - No ban @tab 1 - Op on join
1248 @item 2 - Trusted User @tab 2 - No kick @tab
1249 @item 3 - Friend @tab 3 - No deop @tab
1250 @item 4 - Master @tab @tab
1256 @defun bot:addserver hostname ip-address [portnumber]
1257 Adds the server specified by @var{hostname} or @var{ip-address} to
1262 @defun bot:addshit nick-or-mask channel-mask level [time reason]
1263 Adds an user to the shitlist, for a nick!user@@host matching the
1264 one given, on a channel matching the @var{channelMask} given.
1267 The @var{level} can be:
1270 2 - Kick and Ban on join
1271 3 - Kick and Ban on join, no deban
1277 @defun bot:ban channel mask-or-nick
1278 Bans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
1279 user to ban with a @var{mask}.
1283 @defun bot:change-command-level nick-or-mask channel-mask new-level
1284 Gives @var{nick} or @var{mask} level @var{new-level} on channel(s)
1285 @var{channel-mask}. Note that you can not change level for someone
1286 whose level is greater than yours, and that you can not give a
1287 level greater than yours.
1291 @defun bot:cycle channel
1292 Makes the bot leave and join @var{channel}.
1296 @defun bot:deban channel mask-or-nick
1297 Debans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
1298 user to deban with a @var{mask}.
1302 @defun bot:delserver server-number
1303 Deletes server from server list whose number in the server list
1304 is @var{server-number}
1308 @defun bot:deluser nick-or-mask channel-mask
1309 Removes @var{nick} or @var{mask} from the userlist.
1313 @defun bot:delshit nick-or-mask channel-mask
1314 Removes @var{nick} or @var{mask} from the shitlist.
1318 @defun bot:deop channel mask-or-nick
1319 Deops @var{mask} or @var{nick} on @var{channel}.
1323 @defun bot:die reason
1324 Makes the bot stop immediately.
1332 @defun bot:invite channel nick
1333 Invites @var{nick} on @var{channel}.
1337 @defun bot:join channel
1338 Makes the bot join @var{channel}.
1342 @defun bot:keep channel modes
1343 Sets the @var{modes} that the bot will keep for @var{channel}.
1348 @defun bot:kick channel mask-or-nick [reason]
1349 Kicks @var{mask} or @var{nick} out of @var{channel}, because of @var{reason}.
1350 You need to be a trusted user to use a @var{mask}.
1354 @defun bot:kickban channel mask-or-nick [reason]
1355 Bans then kicks @var{mask} or @var{nick} out of @var{channel},
1356 because of @var{reason}.
1357 You need to be a trusted user to use a @var{mask}.
1361 @defun bot:lock channel
1362 Locks topic on @var{channel}.
1366 @defun bot:mode channel mode-string
1367 Sends @var{mode-string} as mode for @var{channel}.
1371 @defun bot:nextserver
1372 Makes the bot connect to the next server in its server list.
1376 @defun bot:nick nick
1377 Makes the bot use nickname @var{nick}.
1381 @defun bot:op channel nick
1382 Ops @var{nick} on @var{channel}.
1386 @defun bot:part channel
1387 Makes the bot leave @var{channel}.
1391 @defun bot:reconnect
1392 Makes the bot reconnect to its current server.
1396 @defun bot:server server-number
1397 Select the server to connect to. @var{server-number} is the number of
1398 the server in the serverlist.
1402 @defun bot:setfloodrate ?
1406 @defun bot:setversion ?
1410 @defun bot:tban channel nick-or-mask time
1411 Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds.
1415 @defun bot:tkban channel nick-or-mask time [reason]
1416 Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds,
1417 then kicks him/them because of @var{reason}.
1421 @defun bot:topic channel topic
1422 If no @var{topic} is given, prints @var{channel}'s topic. Otherwise,
1423 the bot will change @var{channel}'s topic to @var{topic}.
1426 @defun bot:unlock channel
1427 Makes the bot unlock topic on @var{channel}.
1430 @defun bot:who target
1431 Sends a WHO command to @var{target}. @var{target} may be either a
1435 @defun bot:whois nick
1436 Sends a WHOIS command to @var{nick}. @var{nick} @strong{must} be a
1437 nickname, you cannot send a WHOIS to a channel.
1443 @defun bot:delcommand
1444 [ Probably deletes a command added with @code{bot:addcommand} ? ]
1449 @node Query Functions, , Scheme Commands, Scripting
1450 @section Query Functions
1453 [ I didn't know where to put any of these, so I just stuck them in
1456 There probably needs to be several sections added, like dealing with
1457 users (kicking, added, etc), dealing with the bot (channels, nickname
1458 of the bot, etc), server issues (serverlist), useful tools (nslookup,
1459 whois), and do on. ]
1462 These functions allow scripts to get various bits of information.
1466 [ Probably returns the log port? ]
1470 @defun bot:getnickname
1471 [ Gets the bot's nickname? ]
1475 @defun bot:getserver
1479 @defun bot:getserverlist
1484 [ Flushes the socket to the server? ]
1488 @defun bot:flushport
1489 [ Flushes the log port? ]
1494 [ Returns a random number? What range? Why? ]
1498 @defun bot:addtimer ? ?
1502 @defun bot:deltimer ?
1506 @defun bot:dcc-chat-send ? ?
1510 [ And what about the stuff defined in @file{bobot-utils.scm} ? I just
1511 added it here so it could be somewhere. There should also be a
1512 section dealing with modules. How to use them. What module scripts
1513 are in. What module bobot++ provided primites are in. And so on. ]
1516 @defun bot:log . messages
1517 Write as many @var{messages} as you want to the log. If the arg is a
1518 thunk it will be executed and it's output will be written to the log.
1521 @defun bot:load file
1524 @defun bot:load-module module-spec
1527 @defun bot:use-module module-spec
1530 @defun bot:match-not-channel regex
1531 @code{bot:match-not-channel} adds a prefix regex to your @var{regex} so it
1532 doesn't match the sender or channel in a PUBLIC message
1535 @defun bot:match-to-me regex
1536 @code{bot:match-to-me} matches text that was addressed to the bot with a
1537 ':', ',', or nothing after the bot name.
1540 @defun bot:sent-to-me? message
1543 @defun bot:ctcp-quote message
1544 Returns the CTCP quoted message
1545 Input @emph{MUST NOT} contain the trailing @code{\r\n}
1546 (it is added by the message sending code).
1550 @defvar %bot:loadpath
1553 @defun %bot:load-extensions
1558 @node Concept Index, Function Index, Scripting, Top
1559 @unnumbered Concept Index
1562 @node Function Index, Variable Index, Concept Index, Top
1563 @unnumbered Function Index
1566 @node Variable Index, , Function Index, Top
1567 @unnumbered Variable Index