1 This is bobot++.info, produced by makeinfo version 4.8 from
4 This file documents Bobot++ by Clinton Ebadi and Etienne Bernard
5 (The original author who no longer works on the program).
7 Copyright 2002,2004,2005 Clinton Ebadi
9 Permission is granted to copy, distribute and/or modify this document
10 under the terms of the GNU Free Documentation License, Version 1.1 or
11 any later version published by the Free Software Foundation; with no
12 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
16 File: bobot++.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
18 This document describes Bobot++ by Clinton Ebadi and Etienne Bernard
19 (The original author who no longer works on the program).
21 This document applies to version 2.2 of the program named Bobot++.
23 Copyright 2002,2004,2005 Clinton Ebadi
25 Permission is granted to copy, distribute and/or modify this document
26 under the terms of the GNU Free Documentation License, Version 1.1 or
27 any later version published by the Free Software Foundation; with no
28 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
41 --- The Detailed Node Listing ---
45 * Configuration File Placement::
46 * Configuration Files::
83 * Bot Control Commands::
87 * User List Commands::
88 * Server List Commands::
89 * Shit List Commands::
91 * Scripting Commands::
92 * Authentication Commands::
93 * Miscellaneous Commands::
97 * Adding New Commands::
100 * Misc Scripting Stuff::
111 * Received Message Hooks::
112 * Sent Message Hooks::
114 * Miscellaneous Hooks::
118 * High Level Message Functions::
119 * Low Level Message Functions::
121 Misc. Scripting Stuff
127 File: bobot++.info, Node: Introduction, Next: Configuration, Prev: Top, Up: Top
132 Bobot++ is a powerful IRC bot written in C++. It can be used standalone
133 as a channel maintenence bot, or extended to do almost anything using
136 FIXME: Fill the intro in more?
139 File: bobot++.info, Node: Configuration, Next: Using the Bot, Prev: Introduction, Up: Top
144 Bobot++ is easy to configure. See the `examples' directory for an
145 example configuration.
147 The main configuration file is `bot.conf'. There are several
148 auxiliary configuration files (a user list, aliases file, ban list, and
153 * Configuration File Placement::
154 * Configuration Files::
157 File: bobot++.info, Node: Configuration File Placement, Next: Configuration Files, Prev: Configuration, Up: Configuration
159 2.1 Configuration File Placement
160 ================================
162 Bobot++ will look in `/etc/bobotpp/default/' for its default config if
163 none is specified on the command line. Put the configuration files you
164 want to be loaded by default in this directory. If you are not root, or
165 you want to have your own personal configuration, put it in
166 `~/.bobotpp/config/default/'.
169 File: bobot++.info, Node: Configuration Files, Prev: Configuration File Placement, Up: Configuration
171 2.2 Configuration Files
172 =======================
183 File: bobot++.info, Node: bot.conf, Next: bot.users, Prev: Configuration Files, Up: Configuration Files
188 `bot.conf' contains key value pairs separated by `='.
192 Comments are started with a `#' and cause the entire line to be
193 ignored. _Note that this only works when the `#' is the first character
196 bot.conf is the main configuration file for a Bobot++. The available
197 configuration variables are listed below in the format "VARIABLE
198 <default-value>: description"
200 A few of the options have more complex syntax, they are documented in
201 their own subsections.
208 * MAXNICKLENGTH <9>: The maximum length a valid nickname may be.
209 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.
214 * NICKNAME <Bobot>: The nickname of the bot (NICK is an alias for
217 * USERNAME <bobot>: The IRC username of the bot
219 * CMDCHAR <!>: The character that prefixes commands given to the bot
220 (COMMAND is an alias for CMDCHAR)
222 * IRCNAME <I'm a bobot++!>: The IRC name (or 'real name') of the bot
223 (REALNAME is an alias for IRCNAME)
225 * USERLIST <bot.users>: Name of the file where the userlist is stored
227 * AUTOEXECFILE <bot.autoexec>: Name of the file containing Scheme
228 code to be executed when the bot starts (only used if the bot is
229 compiled with scripting support)
231 * INITFILE <bot.init>: Name of the file containing the default
234 * SHITLIST <bot.shit>: Name of the file where the shitlist (ban
237 * LOGFILE <$LOGDIR/bot.log>: Location of the bot logfile (set this
238 to `/dev/null' to disable logging).
240 * SERVER <None>: This specifies the server to which the bot will
241 connect. Note that this has a special syntax *note server syntax::.
243 * CHANNEL <None>: This specifies the channels the bot will join when
244 it starts up. This has a special syntax *note channel syntax::.
248 File: bobot++.info, Node: server syntax, Next: channel syntax, Prev: bot.conf, Up: bot.conf
250 2.2.1.1 server syntax
251 .....................
253 The server syntax in `bot.conf' allows you to specify an alternate port
254 to connect on, and a password to send the server.
256 You may use more than one server line; Bobot++ will attempt to
257 connect to the first one, and will connect to the next one in the list
258 if it fails. The bot will continue cycling through the server list
259 until it is able to connect to one. There is a command (`!cycle') to
260 make the bot to cycle servers.
262 SERVER = SERVER_NAME [PORT [PASSWORD]]
264 This will make Bobot++ attempt to connect to SERVER_NAME on port
265 PORT with the password PASSWORD. SERVER_NAME should be the address of
266 the server. PORT and PASSWORD are optional.
269 File: bobot++.info, Node: channel syntax, Prev: server syntax, Up: bot.conf
271 2.2.1.2 channel syntax
272 ......................
274 The channel syntax in `bot.conf' allows you to specify the initial
275 modes the bot should set on a channel, the modes the bot should
276 maintain, and a key if the channel needs it.
278 You may have any number of channel lines. When Bobot++ starts it will
279 attempt to join and gain operator status in every channel listed.
281 CHANNEL = NAME:INITIAL_MODES:MODES_TO_KEEP:CHANNEL_KEY
283 The bot will join NAME and set the channel modes to INITIAL_MODES
284 (e.g. "nt") if it is able to gain operator status. It will then
285 maintain MODES_TO_KEEP. If the channel requires a key to enter simply
286 set CHANNEL_KEY. Every argument except for NAME is optional.
290 CHANNEL = #foo:nt:nt:bar
292 The bot will join `#foo' with the channel key `bar' and will then
293 maintain the modes `nt'.
297 The bot will join `#bar' and will not set any modes nor will it
298 attempt to maintain any modes.
301 File: bobot++.info, Node: bot.users, Next: bot.init, Prev: bot.conf, Up: Configuration Files
303 2.2.2 bot.users (User List)
304 ---------------------------
306 `bot.users' is the default file name of the userlist. It may be changed
307 in `bot.conf' via the USERLIST option. *You must add an entry for
308 yourself manually.* You will probably want to add other entries using
309 the IRC command interface as it is more intuitive than editing the file
312 The file contains lines with the format:
314 `HOST_MASK:CHANNEL_MASK:LEVEL:PROTECTION:AUTO-OP:EXPIRATION:PASSWORD'
316 * HOST_MASK is the host mask (e.g. `*!*username
317 .domain.com') of the user
319 * CHANNEL_MASK is a channel mask of the channels that the user has
320 priviliges to use the bot in (e.g. `*' for all channels, `#*' for
321 all non-local channel, `#foo*' for all channels starting with
322 "foo," `#bar' for channel "#bar" only, etc.)
324 * LEVEL is the user level of the user (*Note User Levels::).
326 * PROTECTION is the protection level of the user (*Note
329 * AUTO-OP is set to control whether a user is automatically given
330 operator priviliges on channel entry (*Note Automatic Op::).
332 * EXPIRATION is the UNIX timestamp of when the user entry becomes
333 invalid. Setting this to -1 will make the entry permanent.
335 * PASSWORD is the password the user must supply to the bot to
336 authenticate. This can be set to `*NONE*' to not have a password.
340 File: bobot++.info, Node: bot.init, Next: bot.autoexec, Prev: bot.users, Up: Configuration Files
342 2.2.3 bot.init (Command Aliases)
343 --------------------------------
345 This file stores a list of IRC command aliases. The filename may be
346 changed in `bot.conf' via the INITFILE option. You use this file to set
347 up aliases for IRC commands, e.g. to make `!a' call `!adduser'. This
348 way you can save typing for commonly used commands.
350 The format of a line in the file is: ALIAS COMMAND
352 This will make ALIAS call COMMAND. e.g. `t topic' will make `!t New
353 Topic' set the current channel's topic to "New Topic," just as if you
354 had used `!topic New Topic'.
357 File: bobot++.info, Node: bot.autoexec, Next: bot.shit, Prev: bot.init, Up: Configuration Files
359 2.2.4 bot.autoexec (Scheme Init File)
360 -------------------------------------
362 This file is only used when Bobot++ is compiled with scripting support.
363 The name of the autoexec file can be changed in `bot.conf' via the
366 The contents of this file are evaluated by Guile when the bot
367 starts. You can use this to do things like loading a few default
368 modules when the bot starts.
371 File: bobot++.info, Node: bot.shit, Prev: bot.autoexec, Up: Configuration Files
373 2.2.5 bot.shit (Ban/Shit List)
374 ------------------------------
376 This file stores the ban list. The name may be changed in `bot.conf'
377 via the SHITLIST option. You will most likely want to use the IRC
378 command interface to edit this file instead of editing it directly.
380 The file contains lines in the form:
382 `HOST_MASK:CHANNEL_MASK:LEVEL:EXPIRATION:REASON'
384 * HOST_MASK is the host mask (e.g. `*!*username
385 .domain.com') of the user
387 * CHANNEL_MASK is a channel mask of the channels that the user is
388 banned on (e.g. `*' for all channels, `#*' for all non-local
389 channel, `#foo*' for all channels starting with "foo," `#bar' for
390 channel "#bar" only, etc.
392 * LEVEL is a number specifying if the bot should not allow the user
393 to gain ops, to kick the user upon joining, or to prevent the user
394 from being debanned by other users. *Note Shit Levels:: for
395 information on the available levels.
397 * EXPIRATION is the UNIX timestamp of when the shit entry becomes
398 invalid. This may be set to -1 to make it valid forever.
400 * REASON is text that is sent to the user when they are kicked or
401 banned from the channel.
405 File: bobot++.info, Node: Using the Bot, Next: Scripting, Prev: Configuration, Up: Top
410 Using Bobot++ is easy. This chapter covers starting the bot, a few
411 Bobot++ specific concepts, and using the built-in commands of the bot.
417 * Built-In Commands::
420 File: bobot++.info, Node: Starting the Bot, Next: Concepts, Prev: Using the Bot, Up: Using the Bot
425 The bot is usually installed with the binary name `bobotpp'. It accepts
426 the following command line arguments.
428 * `[--help][-h]' - Shows detailed help and exits
430 * `[--version][-v]' - Shows version information and exits
432 * `[--no-background][-b]' - Run bobot++ in the foreground
434 * `[--config-file file][-f]' - Use file instead of `bot.conf'
436 * `[--config-dir dir][-d]' - Use dir as dir to load config file from
438 * `[--config dir][-c]' - Search your config path (defaults to
439 `$HOME/.bobotpp/config/' and then `/etc/bobotpp/') for dir and
440 then loads your config data using dir
442 * `[--sys-config dir][-s]' - Looks for config in `/etc/bobotpp/dir'.
443 Note that the user dir is still searched first
445 * `[--user-config dir][-u]' - Looks for config in
446 `$HOME/.bobotpp/config/dir/'. Note that the system dir is still
447 searched after this if dir is not found.
449 * `[--debug][-D]' Makes Bobot++ print debugging info and run in the
452 * `[--debug-scripts][-S]' Enables the Guile debugging evaluator for
453 verbose script errors and backtraces while still running the bot
456 The default configuration is read from
457 `$HOME/.bobotpp/config/default/' and then `/etc/bobotpp/default/' if
458 the user config is not found.
460 The bot defaults to running in the background as a daemon.
463 File: bobot++.info, Node: Concepts, Next: Built-In Commands, Prev: Starting the Bot, Up: Using the Bot
468 There are a few general concepts that a user of Bobot++ should know
479 File: bobot++.info, Node: User List, Next: Shit List, Prev: Concepts, Up: Concepts
485 File: bobot++.info, Node: Shit List, Next: Spy List, Prev: User List, Up: Concepts
491 File: bobot++.info, Node: Spy List, Next: Levels, Prev: Shit List, Up: Concepts
497 File: bobot++.info, Node: Levels, Prev: Spy List, Up: Concepts
510 File: bobot++.info, Node: User Levels, Next: Protection, Prev: Levels, Up: Levels
515 There are several user levels available in Bobot++ to provide gradated
516 access to commands. `!adduser' and `bot.users' use the numeric code;
517 Scheme uses the textual name for the level. By default (if the user is
518 not found in the userlist) a user has access to commands with the level
521 0. `bot:user-none' - No *built-in* commands may be executed _by
522 default_ (commands may be added from Scheme that can be executed
523 by users of level none and the level required to execute a command
524 may be changed from Scheme).
526 1. `bot:user-user' - Will be able to execute most commands but not
527 all and cannot use masks on kicks and bans.
529 2. `bot:user-trusted' - For built-ins with a default configuration
530 this user has access to the same set of commands as an `user' but
531 may use masks on kicks and bans. Scheme commands may be added
532 which require a user to be of this level.
534 3. `bot:user-friend' - In the default configuration a user who is a
535 friend will be able to do everything short of stopping the bot.
536 Again, there may be user added commands that require a higher user
539 4. `bot:user-master' - This is the highest user level and has access
540 to every feature of the bot.
544 File: bobot++.info, Node: Protection, Next: Automatic Op, Prev: User Levels, Up: Levels
549 A user added via Scheme, the `bot.users' file, or `!adduser' may be
550 protected from being deoped, kicked, or banned. The user list and IRC
551 commands use the numeric codes, Scheme uses the symbolic names.
553 0. `bot:protection/none' No protection
555 1. `bot:protection/no-ban' No ban. If a user is banned the bot will
558 2. `bot:protection/no-kick' No kick. The user may still be kicked but
559 the bot will kickban the user who kicked the protected user.
561 3. `bot:protection/no-deop' No deop. The bot will ensure that the
562 user always maintains operator status.
565 File: bobot++.info, Node: Automatic Op, Next: Shit Levels, Prev: Protection, Up: Levels
570 A user may be automatically given operator status upon entering a
571 channel. Scheme uses the symbolic name, the user list (`bot.users') and
572 IRC commands use the numeric value.
574 0. `bot:aop/no' Do not automatically op the user
576 1. `bot:aop/yes' Do automatically op the user
579 File: bobot++.info, Node: Shit Levels, Prev: Automatic Op, Up: Levels
584 The shit list and shit list related commands use different levels to
585 define how much the bot hates a user. Scheme uses the symbolic names,
586 the shit list and IRC commands use the numbers.
588 0. `bot:shit/none' The bot doesn't hate the user (this is the normal
591 1. `bot:shit/no-op' The bot will deop the user any time he gains
592 operator priviliges in the channel
594 2. `bot:shit/no-join' The bot will kick and ban the user when he
597 3. `bot:shit/no-deban' The bot will kick and ban usre when he joins
598 the channel, and will prevent other users from debanning him.
601 File: bobot++.info, Node: Built-In Commands, Prev: Concepts, Up: Using the Bot
603 3.3 Built-In Commands
604 =====================
606 Bobot++ has many built-in commands that make it useful without
607 scripting support. The reference leaves off the command char; remember
608 to use whatever you defined the command char to be in `bot.conf'.
610 If a command needs the channel name then you must specify the channel
611 as the first argument to the command when private messaging the bot a
612 command. If, however, you are using the command in a channel you may
613 omit the channel argument, and the bot will use the current channel.
617 * Bot Control Commands::
621 * User List Commands::
622 * Server List Commands::
623 * Shit List Commands::
625 * Scripting Commands::
626 * Authentication Commands::
627 * Miscellaneous Commands::
630 File: bobot++.info, Node: Bot Control Commands, Next: Message Commands, Prev: Built-In Commands, Up: Built-In Commands
632 3.3.1 Bot Control Commands
633 --------------------------
635 These commands are used to control the behaviour of the bot.
637 -- Command: cycle channel
638 Makes the bot leave and join CHANNEL.
641 Makes the bot stop immediately.
643 -- Command: join channel
644 Makes the bot join CHANNEL.
646 -- Command: nick newnick
647 Makes the bot use nickname NEW-NICK.
649 -- Command: setfloodrate messages-per-second
650 Sets the flood rate to MESSAGES-PER-SECOND. The bot will consider
651 users sending more than MESSAGES-PER-SECOND messges in a second to
652 be flooding and will ignore them.
654 -- Command: setversion version-info
655 Sets the string returned when someone requestions the version info
659 File: bobot++.info, Node: Message Commands, Next: Channel Control, Prev: Bot Control Commands, Up: Built-In Commands
661 3.3.2 Message Commands
662 ----------------------
664 These commands cause the bot to send messages (e.g. sending a message
665 to a channel or performing an action). For all commands TARGET may be
666 either a user or a channel.
668 -- Command: action target do
669 Makes the bot to perform the action DO in a message sent to TARGET.
671 -- Command: do command
672 Sends a raw irc command. COMMAND is the IRC command you wish to
673 send (e.g. `PRIVMSG #foo Hello!').
675 -- Command: msg target message
676 -- Command: say target message
677 Makes the bot say MESSAGE to TARGET.
680 File: bobot++.info, Node: Channel Control, Next: Spylist Commands, Prev: Message Commands, Up: Built-In Commands
682 3.3.3 Channel Control
683 ---------------------
685 -- Command: ban channel mask
686 Bans MASK from CHANNEL. You must be a trusted user to ban using a
687 host mask, but a normal user may ban individual nicks.
689 -- Command: deban channel mask
690 Debans MASK from CHANNEL. You must be a trusted user to deban with
693 -- Command: deop channel mask
694 Deops MASK on CHANNEL.
696 -- Command: invite nick channel
697 Invites NICK to CHANNEL.
699 -- Command: keep channel modes
700 Sets the MODES that the bot will keep for CHANNEL.
702 -- Command: kick channel mask reason
703 -- Command: kickban channel mask reason
704 Kicks MASK out of CHANNEL, because of REASON. `kickban' also bans
705 MASK.You must be a trusted user to use a mask.
707 -- Command: lock channel
708 Locks topic on CHANNEL
710 -- Command: mode channel modes
711 Sets mode of CHANNEL to the mode string MODES.
713 -- Command: op channel nick
716 -- Command: part channel
717 Makes the bot leave CHANNEL.
719 -- Command: tban channel mask time
720 -- Command: tkban channel mask time
721 Bans MASK from CHANNEL for TIME seconds. `tkban' also kicks the
722 user. You must be a trusted user to use a mask.
724 -- Command: topic channel [topic]
725 Sets the topic in CHANNEL to TOPIC. If TOPIC is not supplied the
726 current topic is sent as a notice to the user calling the command.
728 -- Command: unlock channel
729 Unlocks the topic on CHANNEL
732 File: bobot++.info, Node: Spylist Commands, Next: User List Commands, Prev: Channel Control, Up: Built-In Commands
734 3.3.4 Spylist Commands
735 ----------------------
737 * `spylist' Shows the bot's spylist.
739 * `spymessage' Adds you to the spylist
741 * `rspymessage' Removes you from the spy list.
745 File: bobot++.info, Node: User List Commands, Next: Server List Commands, Prev: Spylist Commands, Up: Built-In Commands
747 3.3.5 User List Commands
748 ------------------------
750 -- Command: adduser mask
753 `deluser' Removes NICK or MASK from the userlist.
758 `userlist' Shows the bot's userlist
761 File: bobot++.info, Node: Server List Commands, Next: Shit List Commands, Prev: User List Commands, Up: Built-In Commands
763 3.3.6 Server List Commands
764 --------------------------
766 * `addserver' Adds the server specified by HOST NAME or IP
767 ADDRESS to the server list.
769 * `delserver' Deletes server from server list whose number in the
770 server list is SERVER NUMBER.
772 * `nextserver' Makes the bot connect to the next server in its
775 * `reconnect' Makes the bot reconnect to its current server.
777 * `server' Select the server to connect to. SERVER NUMBER is the
778 number of the server in the serverlist.
780 * `serverlist' Shows the bot's serverlist.
784 File: bobot++.info, Node: Shit List Commands, Next: Channel Info, Prev: Server List Commands, Up: Built-In Commands
786 3.3.7 Shit List Commands
787 ------------------------
791 * `delshit' Removes NICK or MASK from the shitlist
793 * `shitlist' Shows the bot's shitlist.
797 File: bobot++.info, Node: Channel Info, Next: Scripting Commands, Prev: Shit List Commands, Up: Built-In Commands
804 * `channels' Prints the channel(s) where the bot is currently.
806 * `names' Yes Shows the nicknames and status of users on CHANNEL.
808 * `stats' Yes Gives CHANNEL's statistics.
811 File: bobot++.info, Node: Scripting Commands, Next: Authentication Commands, Prev: Channel Info, Up: Built-In Commands
813 3.3.9 Scripting Commands
814 ------------------------
816 * `execute' *Only available if scripting support is enabled*
818 * `load' Reloads the userlist from disk.
820 * `loadscript' *Only available if scripting support is enabled*
824 File: bobot++.info, Node: Authentication Commands, Next: Miscellaneous Commands, Prev: Scripting Commands, Up: Built-In Commands
826 3.3.10 Authentication Commands
827 ------------------------------
829 * `ident' Identifies you on the bot. Note that you should not use
830 this command in public ...
832 * `password' Changes your password on the bot. Use `NONE' as
833 password if you want to clear it. Do not use this command in
838 File: bobot++.info, Node: Miscellaneous Commands, Prev: Authentication Commands, Up: Built-In Commands
840 3.3.11 Miscellaneous Commands
841 -----------------------------
843 * `alias' Makes an alias, and adds the function NEW NAME, that
844 will do exactly the same command as OLD NAME.
846 * `dcclist' Gives the list of all DCC Chat connections.
850 * `nslookup' Does a nameserver query about NICK host, HOST or IP
853 * `who' Yes Show your level on CHANNEL
855 * `whois' Yes Shows information about NICK on CHANNEL
859 File: bobot++.info, Node: Scripting, Next: Concept Index, Prev: Using the Bot, Up: Top
864 Bobot++'s most powerful feature is its scripting system. You write
865 scripts using Guile Scheme. This manual does not cover how to use Guile
866 or how to learn Scheme. *Note Guile Reference Manual: (guile)Top, for
867 the Guile reference manual and
868 `http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html' for a
869 good tutorial on Scheme.
871 Note that in previous versions the scripting commands where in the
872 form `bot-FUNCTION'. They are now in the form `bot:FUNCTION'. The old
873 names are still available, but are deprecated and will be removed in
874 Bobot++ 3.0. New commands are only available with the `bot:' prefix.
875 The command `perl -pi -e ``s/bot-/bot:/g'' YOUR-FILES' should be enough
876 to convert your code to use the new functions.
878 *NOTE*: All arguments to functions and hooks called by the bot are
879 strings unless otherwise specified.
883 * Adding New Commands::
886 * Misc Scripting Stuff::
891 File: bobot++.info, Node: Adding New Commands, Next: Hooks, Prev: Scripting, Up: Scripting
893 4.1 Adding New Commands
894 =======================
896 Adding a new command is simple. To register a new command use
899 -- Function: bot:addcommand name func needs-channel? num-of-args
901 The NAME is a string representing the name of the command being
902 added. FUNC is a function accepting NUM-OF-ARGS arguments.
903 NEEDS-CHANNEL? is a bool that is true if the function needs the
904 channel name as its first arg, and false otherwise. NUM-OF-ARGS
905 is the number of args FUNC will take and must be within zero (0)
906 and twenty (20). MIN-LEVEL is one of the *Note User Levels::. A
907 user must be at least a MIN-LEVEL user to use the new command.
908 None of the arguments are guaranteed to be passed; if they aren't
909 they are set to the empty string `""'. An example of a new
912 (define (hello channel name)
913 (if (string=? name "")
914 (bot:say channel "Hello world!")
915 (bot:say channel (string-append "Hello " name "!")))
917 (bot:addcommand "hello" hello #t 2 0)
919 This will display "Hello World!" if called as `!hello' and "Hello
920 World USER" if called as `!hello USER'.
923 File: bobot++.info, Node: Hooks, Next: Sending Messages, Prev: Adding New Commands, Up: Scripting
928 Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
929 and tiny fugue (a MUD bot) hooks with a little bit of extra stuff added
930 in. A hook is called when a regular expression is matched against a
931 message sent to or by the bot.
933 Bobot++ uses different hook types for each IRC message type, and also
934 includes a hook for accessing raw irc messages. Hooks are tagged with a
935 priority and a flag that specifies whether to call the next hook that
936 matches after calling the current one or to stop processing.
938 Hooks are processed from the highest to lowest priority, with
939 fallthrough hooks of equal priority to non-fallthrough hooks being
948 File: bobot++.info, Node: Creating a Hook, Next: Hook Types, Prev: Hooks, Up: Hooks
950 4.2.1 Creating a Hook
951 ---------------------
953 To add a new hook you use the function `bot:addhook'.
955 -- Function: bot:addhook type regex function [pri fall name]
956 TYPE specifies the type of hook (the types of hooks are listed in
959 REGEX is a standard regular expression. If REGEX is matched,
960 FUNCTION will be called.
962 FUNCTION will take a different number of args depending on the
965 PRI specifies the priority of the hook--higher priority hooks are
966 executed first. This argument is optional and defaults to `0'.
968 FALL is `#t' if the hook is a fallthrough hook and `#f' is the
969 hook is not a fallthrough hook. This arg is also optional and
972 NAME is the optional name of the hook that defaults to
973 `"DEFAULT"'. If you set the name then you can have more than one
974 hook that matches the same regexp, as long as they have the same
975 name. E.g. in a log script you could have the regexps for the log
976 function all be `".*"' and set their names to `"log"' to avoid a
977 conflict with other hooks.
980 File: bobot++.info, Node: Hook Types, Prev: Creating a Hook, Up: Hooks
985 The following sections document the different hooks Bobot++ exposes.
987 The general format of each hook description is as if it were a
988 function to be defined, but these describe the function to be passed to
989 `bot:add-hook'. Do _not_ name your functions these names.
991 That said, here is the list of available hooks functions. FIXME:
996 * Received Message Hooks::
997 * Sent Message Hooks::
999 * Miscellaneous Hooks::
1002 File: bobot++.info, Node: Received Message Hooks, Next: Sent Message Hooks, Prev: Hook Types, Up: Hook Types
1004 4.2.2.1 Receieved Message Hooks
1005 ...............................
1007 The following hooks are triggered when a mesage is received by the bot.
1009 -- Function: hooks/action from to action
1010 This hook is triggered when someone performs an action.
1012 FROM is the nickname the person that performed the action.
1014 TO is the target of the action, which is either a channel or the
1015 Bot's nick if the user private messages the bot.
1017 ACTION is the text of the action. E.g. if someone did `* foobar
1018 does baz', then ACTION would be the string `"does baz"'.
1020 -- Function: hooks/nickname old-nick new-nick
1021 This hook is called when someone changes his nickname from
1022 OLD-NICK to NEW-NICK.
1024 -- Function: hooks/signoff nick message
1025 This hook is called when someone signs off of IRC.
1027 NICK is the nickname of the person signing off.
1029 MESSAGE is his quit message
1031 -- Function: hooks/ctcp nick to command rest
1032 This hook is called when a CTCP request is received by the bot.
1034 NICK is the nickname of the sender.
1036 TO is the target of the CTCP request. This will either be a
1037 channel the bot is in, or the nickname of the bot.
1039 COMMAND is the CTCP command issued.
1041 REST contains the arguments to the CTCP command.
1043 -- Function: hooks/ctcp-reply nick command rest
1044 This hook is called when a CTCP REPLY is received. This occurs when
1045 the bot has sent a CTCP request to another client. The CTCP REPLY
1046 is always addressed to the bot directly.
1048 NICK is the nickname of the person who replied.
1050 COMMAND is the command to which NICK is replying.
1052 REST contains the body of the reply.
1054 -- Function: hooks/disconnect server intentional
1055 This is called when the bot is disconnected from a server.
1057 SERVER is the hostname of the server from which the bot was
1060 INTENTIONAL is a flag set to `#t' when the bot disonnected from
1061 the server as the result of a command (issued by a user from IRC,
1062 SIGHUP, or from a script), or `#f' when the bot disconnected from
1063 the server unintentionally..
1065 -- Function: hooks/invite nick channel
1066 This hook is called when a user invited the bot to join a channel.
1068 NICK is the nickname of the user who sent the invite.
1070 CHANNEL is the channel to which the bot was invited.
1072 -- Function: hooks/join nick channel
1073 This is called when a user or the bot joins a channel.
1075 NICK is the nickname of the user who joined CHANNEL. This may be
1076 the bot's nickname (the IRC server sends the JOIN command back to
1077 the the bot after it joins a channel).
1079 CHANNEL is the channel that was joined
1081 -- Function: hooks/kick target from channel reason
1082 This hook is called when a user, including the bot, is kicked out
1085 TARGET is the nick of the user who was kicked. This may be the
1088 FROM is the nick of the user who issued the kick. This may also be
1091 CHANNEL is the channel the kick was issued in.
1093 REASON is the reason the user was kicked.
1095 -- Function: hooks/part nick channel
1096 This hook is called when a user parts a channel.
1098 NICK is the user who parted the channel. This may be the bot.
1100 CHANNEL is the channel from which the user parted.
1102 -- Function: hooks/mode nick target modes
1103 This hook is called when someone sets the modes of TARGET.
1105 NICK is the user who set the modes. This may be the bot.
1107 TARGET is the target of the MODE command. This may be a channel or
1108 a user. If it is a user, it may be the bot.
1110 MODES is the MODE string.
1112 -- Function: hooks/message nick message
1113 This hook is called when someone sends a private message to the
1116 NICK is the nickname of the user who sent the message.
1118 MESSAGE is the message the user sent.
1120 -- Function: hooks/notice nick message
1121 This hook is called when a user send a private notice to the bot.
1123 NICK is the user who sent the notice.
1125 MESSAGE is the message the user sent.
1127 -- Function: hooks/public nick channel message
1128 This hook is called when a user sends a normal message to a
1131 NICK is the user who sent the message.
1133 CHANNEL is the channel to which the message was sent.
1135 MESSAGE is the message that was sent.
1137 -- Function: hooks/public-notice nick channel message
1138 This hook is called when a user send a notice to a channel.
1140 NICK is the user who sent the notice.
1142 CHANNEL is the channel to which the notice was sent.
1144 MESSAGE is the message that was sent.
1146 -- Function: hooks/raw raw-message
1147 This hook is called every time a message is received. This matches
1148 on the raw message text and passes the hook function the raw IRC
1151 RAW-MESSAGE is the raw IRC message.
1153 -- Function: hooks/topic nick channel new-topic
1154 This hook is called when a user changes the topic in a channel.
1156 NICK is the user who set the topic. This may be the bot.
1158 CHANNEL is the channel that's topic was changed.
1160 NEW-TOPIC is the new topic.
1163 File: bobot++.info, Node: Sent Message Hooks, Next: DCC CHAT Hooks, Prev: Received Message Hooks, Up: Hook Types
1165 4.2.2.2 Sent Message Hooks
1166 ..........................
1168 These hooks are called when the bot sends a message. MYNICK is always
1169 the bot's nick and will not be documented in each hook description.
1171 -- Function: hooks/send/public mynick channel message
1172 This hook is called when the bot sends a normal message to a
1175 CHANNEL is the channel to which the bot sent the message.
1177 MESSAGE is the message the bot sent.
1179 -- Function: hooks/send/message mynick to message
1180 This hook is called when the bot sends a private message to a user.
1182 TO is the nick of the user to whom the message was sent.
1184 MESSAGE is the message that was sent.
1186 -- Function: hooks/send/action mynick to message
1187 This hook is called when the bot sents an action to a channel or a
1190 TO is the channel or nick of the user to which the action was sent.
1192 MESSAGE is the text of the action.
1194 -- Function: hooks/send/ctcp mynick to command message
1195 This hook is called when the bot sends a CTCP message _other than_
1196 an ACTION to a channel or user.
1198 TO is the channel or nick of the user to which the CTCP was sent.
1200 COMMAND is the CTCP command that was sent.
1202 MESSAGE is a string containing the arguments to the CTCP command.
1204 -- Function: hooks/send/who who
1205 This is called when the bot sends a WHO message. The regex is
1206 matched on WHO, which is also passed as the only argument to your
1209 WHO is the channel or nick that was WHOed.
1211 -- Function: hooks/send/whois nick
1212 This is called when the bot sends a WHOIS message. The regex is
1213 matched on NICK, which is also passed as the only argument to your
1216 NICK is the nickname of the person who was WHOISed.
1219 File: bobot++.info, Node: DCC CHAT Hooks, Next: Miscellaneous Hooks, Prev: Sent Message Hooks, Up: Hook Types
1221 4.2.2.3 DCC CHAT Hooks
1222 ......................
1224 These hooks are called when a user initializes a DCC CHAT and when the
1225 bot receives messages from the user in a DCC CHAT.
1227 -- Function: hooks/dcc/chat-begin from
1228 This hook is called when a user begins a DCC CHAT with the bot.
1229 FROM is the user's address in the form `nick!user@host'.
1231 -- Function: hooks/dcc/chat-end address
1232 This hook is called when a DCC CHAT is purged after being idle for
1233 a while, or when the user closes the DCC CHAT. As such, you cannot
1234 write any more data to the DCC CHAT.
1236 ADDRESS is the address (nick!user@host) of the person on the other
1239 -- Function: hooks/dcc/chat-message from message
1240 This hook is called when a user sends a message to the bot through
1243 FROM is the user's address in the form `nick!user@host'.
1245 MESSAGE is the message the user sent to the bot.
1248 File: bobot++.info, Node: Miscellaneous Hooks, Prev: DCC CHAT Hooks, Up: Hook Types
1250 4.2.2.4 Miscellaneous Hooks
1251 ...........................
1253 -- Function: hooks/flood nick
1254 This hook is called when a user is detected flooding the bot.
1256 NICK is the nickname of the user flooding the bot.
1258 -- Function: hooks/timer time
1259 This hook is called once a minute. The regex is *not* used.
1261 TIME is the in zero-padded `hh:mm' format.
1264 File: bobot++.info, Node: Sending Messages, Next: Misc Scripting Stuff, Prev: Hooks, Up: Scripting
1266 4.3 Sending Messages
1267 ====================
1269 There are several types of messages you can send with Bobot++ from
1270 scripts. They are split into High and Low level message sending
1271 functions. Most bots will only use the high level functions, but the
1272 low level ones are provided for when a bot needs to do things like send
1273 raw IRC messages or CTCP commands.
1277 * High Level Message Functions::
1278 * Low Level Message Functions::
1281 File: bobot++.info, Node: High Level Message Functions, Next: Low Level Message Functions, Prev: Sending Messages, Up: Sending Messages
1283 4.3.1 "High Level" Message Functions
1284 ------------------------------------
1286 -- Function: bot:action channel message
1287 Send an "action" type MESSAGE to CHANNEL
1289 -- Function: bot:msg target message
1290 -- Function: bot:say target message
1291 Send a public or private message to TARGET.
1293 TARGET may be a channel or a nickname.
1295 In versions of Bobot++ prior to 2.1.8 `bot:say' could only send to
1296 channels, and `bot:msg' could only send private messages to users.
1297 They are aliases of the same command now, but it may be worth
1298 using them as they used to for clarity.
1300 -- Function: bot:notice target message
1301 Sends MESSAGE as a NOTICE to TARGET. TARGET may be a user (nick)
1305 File: bobot++.info, Node: Low Level Message Functions, Prev: High Level Message Functions, Up: Sending Messages
1307 4.3.2 "Low Level" Message Functions
1308 -----------------------------------
1310 The "Low Level" messaging functions allow you to do things like send
1311 CTCP messages. You probably want to read rfc 2812 and the CTCP spec
1312 before using these. If you have no idea what these do, read rfc 2812
1313 (IRC Client Protocol) and CTCP spec. These functions all return
1314 `*unspecified*' always, so don't use the return value for anything.
1316 -- Function: bot:ctcp to command message
1317 TO is the target of your CTCP message, COMMAND is the CTCP
1318 command, and MESSAGE is the message (or arguments) of the command.
1319 Make sure to `bot:ctcp-quote' the message!
1321 -- Function: bot:ctcp-reply to command message
1322 TO is the target of your CTCP reply, COMMAND is the CTCP command,
1323 and MESSAGE is the message (or arguments) of the command. Make
1324 sure to `bot:ctcp-quote' the message!
1326 This is used to reply to a ctcp that the bot has received.
1329 File: bobot++.info, Node: Misc Scripting Stuff, Next: Scheme Commands, Prev: Sending Messages, Up: Scripting
1331 4.4 Misc. Scripting Stuff
1332 =========================
1334 These are a few useful things that I thought people writing scripts
1337 If you want to execute code when the bot exits, just do `add-hook!
1338 bot:exit-hook THUNK' where THUNK is an argumentless procedure (a
1339 thunk). When the bot exits your thunk will be called.
1347 File: bobot++.info, Node: Scheme Commands, Next: Query Functions, Prev: Misc Scripting Stuff, Up: Scripting
1352 These scheme functions are the same as the commands. They allow you to
1353 execute bot commands from scheme scripts.
1355 -- Function: bot:adduser nick-or-mask cbannel-mask level prot auto-op
1356 Adds an user to the userlist, for a `nick!user@host' matching the
1357 one given, on a channel matching the CHANNELMASK given.
1359 The LEVEL can be: The PROT can be: The AUTO-OP can be:
1360 0 - No level 0 - No protection 0 - No auto-op
1361 1 - User 1 - No ban 1 - Op on join
1362 2 - Trusted User 2 - No kick
1363 3 - Friend 3 - No deop
1367 -- Function: bot:addserver hostname ip-address [portnumber]
1368 Adds the server specified by HOSTNAME or IP-ADDRESS to the server
1371 -- Function: bot:addshit nick-or-mask channel-mask level [time reason]
1372 Adds an user to the shitlist, for a nick!user@host matching the
1373 one given, on a channel matching the CHANNELMASK given.
1378 2 - Kick and Ban on join
1379 3 - Kick and Ban on join, no deban
1382 -- Function: bot:ban channel mask-or-nick
1383 Bans MASK or NICK from CHANNEL. You must be a trusted user to ban
1386 -- Function: bot:change-command-level nick-or-mask channel-mask
1388 Gives NICK or MASK level NEW-LEVEL on channel(s) CHANNEL-MASK.
1389 Note that you can not change level for someone whose level is
1390 greater than yours, and that you can not give a level greater than
1393 -- Function: bot:cycle channel
1394 Makes the bot leave and join CHANNEL.
1396 -- Function: bot:deban channel mask-or-nick
1397 Debans MASK or NICK from CHANNEL. You must be a trusted user to
1400 -- Function: bot:delserver server-number
1401 Deletes server from server list whose number in the server list is
1404 -- Function: bot:deluser nick-or-mask channel-mask
1405 Removes NICK or MASK from the userlist.
1407 -- Function: bot:delshit nick-or-mask channel-mask
1408 Removes NICK or MASK from the shitlist.
1410 -- Function: bot:deop channel mask-or-nick
1411 Deops MASK or NICK on CHANNEL.
1413 -- Function: bot:die reason
1414 Makes the bot stop immediately.
1416 -- Function: bot:do ?
1418 -- Function: bot:invite channel nick
1419 Invites NICK on CHANNEL.
1421 -- Function: bot:join channel
1422 Makes the bot join CHANNEL.
1424 -- Function: bot:keep channel modes
1425 Sets the MODES that the bot will keep for CHANNEL. See also STATS.
1427 -- Function: bot:kick channel mask-or-nick [reason]
1428 Kicks MASK or NICK out of CHANNEL, because of REASON. You must be
1429 a trusted user to use a MASK.
1431 -- Function: bot:kickban channel mask-or-nick [reason]
1432 Bans then kicks MASK or NICK out of CHANNEL, because of REASON.
1433 You must be a trusted user to use a MASK.
1435 -- Function: bot:lock channel
1436 Locks topic on CHANNEL.
1438 -- Function: bot:mode channel mode-string
1439 Sends MODE-STRING as mode for CHANNEL.
1441 -- Function: bot:nextserver
1442 Makes the bot connect to the next server in its server list.
1444 -- Function: bot:nick nick
1445 Makes the bot use nickname NICK.
1447 -- Function: bot:op channel nick
1448 Ops NICK on CHANNEL.
1450 -- Function: bot:part channel
1451 Makes the bot leave CHANNEL.
1453 -- Function: bot:reconnect
1454 Makes the bot reconnect to its current server.
1456 -- Function: bot:server server-number
1457 Select the server to connect to. SERVER-NUMBER is the number of
1458 the server in the serverlist.
1460 -- Function: bot:setfloodrate ?
1462 -- Function: bot:setversion ?
1464 -- Function: bot:tban channel nick-or-mask time
1465 Bans NICK or MASK from CHANNEL for TIME seconds.
1467 -- Function: bot:tkban channel nick-or-mask time [reason]
1468 Bans NICK or MASK from CHANNEL for TIME seconds, then kicks
1469 him/them because of REASON.
1471 -- Function: bot:topic channel topic
1472 If no TOPIC is given, prints CHANNEL's topic. Otherwise, the bot
1473 will change CHANNEL's topic to TOPIC.
1475 -- Function: bot:unlock channel
1476 Makes the bot unlock topic on CHANNEL.
1478 -- Function: bot:who target
1479 Sends a WHO command to TARGET. TARGET may be either a channel or a
1482 -- Function: bot:whois nick
1483 Sends a WHOIS command to NICK. NICK *must* be a nickname, you
1484 cannot send a WHOIS to a channel.
1486 -- Function: bot:delcommand
1487 [ Probably deletes a command added with `bot:addcommand' ? ]
1490 File: bobot++.info, Node: Query Functions, Prev: Scheme Commands, Up: Scripting
1495 [ I didn't know where to put any of these, so I just stuck them in
1498 There probably needs to be several sections added, like dealing
1499 with users (kicking, added, etc), dealing with the bot (channels,
1500 nickname of the bot, etc), server issues (serverlist), useful
1501 tools (nslookup, whois), and do on. ]
1503 These functions allow scripts to get various bits of information.
1505 -- Function: bot:logport
1506 [ Probably returns the log port? ]
1508 -- Function: bot:getnickname
1509 [ Gets the bot's nickname? ]
1511 -- Function: bot:getserver
1513 -- Function: bot:getserverlist
1515 -- Function: bot:flush
1516 [ Flushes the socket to the server? ]
1518 -- Function: bot:flushport
1519 [ Flushes the log port? ]
1521 -- Function: bot:random ?
1522 [ Returns a random number? What range? Why? ]
1524 -- Function: bot:addtimer ? ?
1526 -- Function: bot:deltimer ?
1528 -- Function: bot:dcc-chat-send ? ?
1530 [ And what about the stuff defined in `bobot-utils.scm' ? I just
1531 added it here so it could be somewhere. There should also be a
1532 section dealing with modules. How to use them. What module
1533 scripts are in. What module bobot++ provided primites are in.
1536 -- Function: bot:log . messages
1537 Write as many MESSAGES as you want to the log. If the arg is a
1538 thunk it will be executed and it's output will be written to the
1541 -- Function: bot:load file
1543 -- Function: bot:load-module module-spec
1545 -- Function: bot:use-module module-spec
1547 -- Function: bot:match-not-channel regex
1548 `bot:match-not-channel' adds a prefix regex to your REGEX so it
1549 doesn't match the sender or channel in a PUBLIC message
1551 -- Function: bot:match-to-me regex
1552 `bot:match-to-me' matches text that was addressed to the bot with a
1553 ':', ',', or nothing after the bot name.
1555 -- Function: bot:sent-to-me? message
1557 -- Function: bot:ctcp-quote message
1558 Returns the CTCP quoted message Input _MUST NOT_ contain the
1559 trailing `\r\n' (it is added by the message sending code).
1561 -- Variable: %bot:loadpath
1563 -- Function: %bot:load-extensions
1566 File: bobot++.info, Node: Concept Index, Next: Function Index, Prev: Scripting, Up: Top