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::
96 * Adding New Commands::
99 * Misc Scripting Stuff::
108 * Received Message Hooks::
109 * Sent Message Hooks::
111 * Miscellaneous Hooks::
115 * High Level Message Functions::
116 * Low Level Message Functions::
121 @node Introduction, Configuration, Top, Top
122 @chapter Introduction
124 Bobot++ is a powerful IRC bot written in C++. It can be used
125 standalone as a channel maintenence bot, or extended to do almost
126 anything using Scheme scripts.
128 FIXME: Fill the intro in more?
130 @node Configuration, Using the Bot, Introduction, Top
131 @chapter Configuration
133 Bobot++ is easy to configure. See the @file{examples} directory for an
134 example configuration.
136 The main configuration file is @file{bot.conf}. There are several
137 auxiliary configuration files (a user list, aliases file, ban list,
138 and a script autoexec).
141 * Configuration File Placement::
142 * Configuration Files::
145 @node Configuration File Placement, Configuration Files, Configuration, Configuration
146 @section Configuration File Placement
148 Bobot++ will look in @file{/etc/bobotpp/default/} for its default
149 config if none is specified on the command line. Put the configuration
150 files you want to be loaded by default in this directory. If you are
151 not root, or you want to have your own personal configuration, put it
152 in @file{~/.bobotpp/config/default/}.
154 @node Configuration Files, , Configuration File Placement, Configuration
155 @section Configuration Files
163 @node bot.conf, bot.users, Configuration Files, Configuration Files
166 @file{bot.conf} contains key value pairs separated by @code{=}.
168 @code{<key> = <value>}
170 Comments are started with a @code{#} and cause the entire line to be
171 ignored. @emph{Note that this only works when the @code{#} is the first
172 character of the line}.
174 bot.conf is the main configuration file for a Bobot++. The available
175 configuration variables are listed below in the format ``@var{variable}
176 <default-value>: description''
178 A few of the options have more complex syntax, they are documented in
179 their own subsections.
188 @item @var{maxnicklength} <9>: The maximum length a valid nickname may
189 be. This should be set before setting the bot's nickname if it will be
190 more than nine characters long. Most IRC servers support nicknames
191 longer than nine characters, but Bobot++ still follows the old spec
192 and defaults to nine.
193 @item @var{nickname} <Bobot>: The nickname of the bot (@var{nick} is an
194 alias for @var{nickname})
195 @item @var{username} <bobot>: The IRC username of the bot
196 @item @var{cmdchar} <!>: The character that prefixes commands given to
197 the bot (@var{command} is an alias for @var{cmdchar})
198 @item @var{ircname} <I'm a bobot++!>: The IRC name (or 'real name') of
199 the bot (@var{realname} is an alias for @var{ircname})
200 @item @var{userlist} <bot.users>: Name of the file where the userlist is
202 @item @var{shitlist} <bot.shit>: Name of the file where the shitlist
204 @item @var{logfile} <$LOGDIR/bot.log>: Location of the bot logfile
205 (set this to @file{/dev/null} to disable logging).
206 @item @var{server} <None>: This specifies the server to which the bot
207 will connect. Note that this has a special syntax @pxref{server
209 @item @var{channel} <None>: This specifies the channels the bot will join
210 when it starts up. This has a special syntax @pxref{channel
215 @node server syntax, channel syntax, bot.conf, bot.conf
216 @subsubsection server syntax
218 The server syntax in @file{bot.conf} allows you to specify an
219 alternate port to connect on, and a password to send the server.
221 You may use more than one server line; Bobot++ will attempt to connect
222 to the first one, and will connect to the next one in the list if it
223 fails. The bot will continue cycling through the server list until it
224 is able to connect to one. There is a command (@code{!cycle}) to make
225 the bot to cycle servers.
227 @var{server} = @var{server_name} [@var{port} [@var{password}]]
229 This will make Bobot++ attempt to connect to @var{server_name} on port
230 @var{port} with the password @var{password}. @var{server_name} should
231 be the address of the server. @var{port} and @var{password} are
234 @node channel syntax, , server syntax, bot.conf
235 @subsubsection channel syntax
237 The channel syntax in @file{bot.conf} allows you to specify the
238 initial modes the bot should set on a channel, the modes the bot
239 should maintain, and a key if the channel needs it.
241 You may have any number of channel lines. When Bobot++ starts it will
242 attempt to join and gain operator status in every channel listed.
245 @var{name}:@var{initial_modes}:@var{modes_to_keep}:@var{channel_key}
247 The bot will join @var{name} and set the channel modes to
248 @var{initial_modes} (e.g. ``nt'') if it is able to gain operator
249 status. It will then maintain @var{modes_to_keep}. If the channel
250 requires a key to enter simply set @var{channel_key}. Every argument
251 except for @var{name} is optional.
256 @var{channel} = #foo:nt:nt:bar
259 The bot will join @code{#foo} with the channel key @code{bar} and will
260 then maintain the modes @code{nt}.
263 @var{channel} = #bar:::
266 The bot will join @code{#bar} and will not set any modes nor will it
267 attempt to maintain any modes.
269 @node bot.users, bot.shit, bot.conf, Configuration Files
270 @subsection bot.users (User List)
272 @file{bot.users} is the default file name of the userlist. It may be
273 changed in @file{bot.conf}. You must add an entry for yourself
274 manually. You will probably want to add other entries using the IRC
275 command interface as it is more intuitive than editing the file by
278 The file contains lines with the format:
280 @samp{@var{host_mask}:@var{channel_mask}:@var{level}:@var{protection}:@var{auto-op}:@var{expiration}:@var{password}}
284 @item @var{host_mask} is the host mask
285 (e.g. @samp{*!*username@*.domain.com}) of the user
287 @item @var{channel_mask} is a channel mask of the channels that the user
288 has priviliges to use the bot in (e.g. @samp{*} for all channels,
289 @samp{#*} for all non-local channel, @samp{#foo*} for all channels
290 starting with ``foo,'' @samp{#bar} for channel ``#bar'' only, etc.)
292 @item @var{level} is the user level of the user (@ref{User Levels}).
294 @item @var{protection} is the protection level of the user
297 @item @var{auto-op} is set to control whether a user is automatically
298 given operator priviliges on channel entry (@ref{Automatic Op}).
300 @item @var{expiration} is the UNIX timestamp of when the user entry
301 becomes invalid. Setting this to -1 will make the entry permanent.
303 @item @var{password} is the password the user must supply to the bot
304 to authenticate. This can be set to @code{*NONE*} to not have a password.
308 @node bot.shit, , bot.users, Configuration Files
309 @subsection bot.shit (Ban/Shit List)
311 This file stores the ban list. The name may be changed in
312 @file{bot.conf}. You will most likely want to use the IRC command
313 interface to edit this file instead of editing it directly.
315 The file contains lines in the form:
317 @samp{@var{host_mask}:@var{channel_mask}:@var{level}:@var{expiration}:@var{reason}}
321 @item @var{host_mask} is the host mask
322 (e.g. @samp{*!*username@*.domain.com}) of the user
324 @item @var{channel_mask} is a channel mask of the channels that the user
325 is banned on (e.g. @samp{*} for all channels,
326 @samp{#*} for all non-local channel, @samp{#foo*} for all channels
327 starting with ``foo,'' @samp{#bar} for channel ``#bar'' only, etc.
329 @item @var{level} is a number specifying if the bot should not allow
330 the user to gain ops, to kick the user upon joining, or to prevent the
331 user from being debanned by other users. @ref{Shit Levels} for
332 information on the available levels.
334 @item @var{expiration} is the UNIX timestamp of when the shit entry
335 becomes invalid. This may be set to -1 to make it valid forever.
337 @item @var{reason} is text that is sent to the user when they are
338 kicked or banned from the channel.
342 @node Using the Bot, Scripting, Configuration, Top
343 @chapter Using Bobot++
353 * Built-In Commands::
356 @node Starting the Bot, User Levels, Using the Bot, Using the Bot
357 @section Starting the Bot
359 The bot is usually installed with the binary name @file{bobotpp}. It
360 accepts the following command line arguments.
363 @item @code{[--help][-h]} - Shows detailed help and exits
364 @item @code{[--version][-v]} - Shows version information and exits
365 @item @code{[--no-background][-b]} - Run bobot++ in the foreground
366 @item @code{[--config-file file][-f]} - Use file instead of @file{bot.conf}
367 @item @code{[--config-dir dir][-d]} - Use dir as dir to load config file from
368 @item @code{[--config dir][-c]} - Search your config path (defaults to
369 @file{@var{$HOME}/.bobotpp/config/} and then @file{/etc/bobotpp/}) for
370 dir and then loads your config data using dir
371 @item @code{[--sys-config dir][-s]} - Looks for config in
372 @file{/etc/bobotpp/dir}. Note that the user dir is still searched
374 @item @code{[--user-config dir][-u]} - Looks for config in
375 @file{@var{$HOME}/.bobotpp/config/dir/}. Note that the system dir is
376 still searched after this if dir is not found.
377 @item @code{[--debug][-D]} Makes Bobot++ print debugging info and run
379 @item @code{[--debug-scripts][-S]} Enables the Guile debugging
380 evaluator for verbose script errors and backtraces while still running
381 the bot in the background.
384 The default configuration is read from
385 @file{@var{$HOME}/.bobotpp/config/default/} and then
386 @file{/etc/bobotpp/default/} if the user config is not found.
388 The bot defaults to running in the background as a daemon.
390 @node User Levels, Protection, Starting the Bot, Using the Bot
393 There are several user levels available in Bobot++ to provide gradated
394 access to commands. @command{!adduser} and @file{bot.users} use the
395 numeric code; Scheme uses the textual name for the level. By default
396 (if the user is not found in the userlist) a user has access to
397 commands with the level @code{bot:user-none}.
401 @item @code{bot:user-none} - No @strong{built-in} commands may be
402 executed @emph{by default} (commands may be added from Scheme that can
403 be executed by users of level none and the level required to execute a
404 command may be changed from Scheme).
406 @item @code{bot:user-user} - Will be able to execute most commands but
407 not all and cannot use masks on kicks and bans.
409 @item @code{bot:user-trusted} - For built-ins with a default
410 configuration this user has access to the same set of commands as an
411 @code{user} but may use masks on kicks and bans. Scheme commands may
412 be added which require a user to be of this level.
414 @item @code{bot:user-friend} - In the default configuration a user who
415 is a friend will be able to do everything short of stopping the
416 bot. Again, there may be user added commands that require a higher
419 @item @code{bot:user-master} - This is the highest user level and has
420 access to every feature of the bot.
424 @node Protection, Automatic Op, User Levels, Using the Bot
427 A user added via Scheme, the @file{bot.users} file, or
428 @command{!adduser} may be protected from being deoped, kicked, or
429 banned. The user list and IRC commands use the numeric codes, Scheme
430 uses the symbolic names.
433 @item @code{bot:protection/none} No protection
434 @item @code{bot:protection/no-ban} No ban. If a user is banned the bot will unban him..
435 @item @code{bot:protection/no-kick} No kick. The user may still be kicked but the bot will kickban
436 the user who kicked the protected user.
437 @item @code{bot:protection/no-deop} No deop. The bot will ensure that the user always maintains
441 @node Automatic Op, Shit Levels, Protection, Using the Bot
442 @section Automatic Op
444 A user may be automatically given operator status upon entering a
445 channel. Scheme uses the symbolic name, the user list
446 (@file{bot.users}) and IRC commands use the numeric value.
449 @item @code{bot:aop/no} Do not automatically op the user
450 @item @code{bot:aop/yes} Do automatically op the user
453 @node Shit Levels, Built-In Commands, Automatic Op, Using the Bot
456 The shit list and shit list related commands use different levels to
457 define how much the bot hates a user. Scheme uses the symbolic names,
458 the shit list and IRC commands use the numbers.
461 @item @code{bot:shit/none} The bot doesn't hate the user (this is the
463 @item @code{bot:shit/no-op} The bot will deop the user any time he
464 gains operator priviliges in the channel
465 @item @code{bot:shit/no-join} The bot will kick and ban the user when he
467 @item @code{bot:shit/no-deban} The bot will kick and ban usre when he
468 joins the channel, and will prevent other users from debanning him.
471 @node Built-In Commands, , Shit Levels, Using the Bot
472 @section Built-In Commands
474 Bobot++ has many built-in commands that make it useful without
475 scripting support. The reference leaves off the command char; remember
476 to use whatever you defined the command char to be in
477 @file{bot.conf}. If a command needs the channel name then you must
478 specify the channel as the first argument to the command when private
479 messaging the bot a command.
481 @multitable @columnfractions 0.20 0.15 0.15 0.50
482 @item @sc{command} @tab @sc{Needs Channel} @tab @sc{Min Level to Use} @tab @sc{Description}
484 @item @command{action} @option{do} @tab Yes @tab @var{USER} @tab
485 Causes the bot to perform the action @option{do} in the current
488 @item @command{adduser} @tab @tab @tab
490 @item @command{addserver} @tab @tab @tab Adds the server specified by
491 @var{host name} or @var{ip address} to the server list.
493 @item @command{addshit} @tab @tab @tab
495 @item @command{alias} @tab @tab @tab Makes an alias, and adds the
496 function @var{new name}, that will do exactly the same command as
499 @item @command{ban} @tab @tab @tab Bans @var{mask} or @var{nick} from
500 @var{channel}. You need to be a trusted user to ban with a
503 @item @command{banlist} @tab @tab @tab
505 @item @command{channels} @tab @tab @tab Prints the channel(s) where
506 the bot is currently.
508 @item @command{cycle} @tab Yes @tab @tab Makes the bot leave and join
511 @item @command{dcclist} @tab @tab @tab Gives the list of all DCC Chat
514 @item @command{deban} @tab Yes @tab @tab Debans @var{mask} or
515 @var{nick} from @var{channel}. You need to be a trusted user to deban
518 @item @command{delserver} @tab @tab @tab Deletes server from server
519 list whose number in the server list is @var{server number}.
521 @item @command{deluser} @tab @tab @tab Removes @var{nick} or
522 @var{mask} from the userlist.
524 @item @command{delshit} @tab @tab @tab Removes @var{nick} or
525 @var{mask} from the shitlist.
527 @item @command{deop} @tab Yes @tab @tab Deops @var{mask} or @var{nick}
530 @item @command{die} @tab @tab @tab Makes the bot stop immediately.
532 @item @command{do} @tab @tab @tab
534 @item @command{execute} @tab @tab @tab @strong{Only available if
535 scripting support is enabled}
537 @item @command{help} @tab @tab @tab
539 @item @command{ident} @tab @tab @tab Identifies you on the bot. Note
540 that you should not use this command in public @dots{}
542 @item @command{invite} @tab Yes @tab @tab Invites @var{nick} on
545 @item @command{join} @tab @tab @tab Makes the bot join @var{channel}.
547 @item @command{keep} @tab Yes @tab @tab Sets the @var{modes} that the
548 bot will keep for @var{channel}.
550 @item @command{kick} @tab Yes @tab @tab Kicks @var{mask} or @var{nick}
551 out of @var{channel}, because of @var{reason}. You need to be a
552 trusted user to use a @var{mask}.
554 @item @command{kickban} @tab Yes @tab @tab Bans then kicks @var{mask}
555 or @var{nick} out of @var{channel}, because of @var{reason}. You need
556 to be a trusted user to use a @var{mask}.
558 @item @command{load} @tab @tab @tab Reloads the userlist from disk.
560 @item @command{loadscript} @tab @tab @tab @strong{Only available if
561 scripting support is enabled}
563 @item @command{lock} @tab @tab @tab Locks topic on @var{channel}.
565 @item @command{mode} @tab Yes @tab @tab Sends @var{mode string} as
566 mode for @var{channel}.
568 @item @command{msg} @tab @tab @tab
570 @item @command{names} @tab Yes @tab @tab Shows the nicknames and
571 status of users on @var{channel}.
573 @item @command{nextserver} @tab @tab @tab Makes the bot connect to the
574 next server in its server list.
576 @item @command{nick} @tab @tab @tab Makes the bot use nickname @var{nick}.
578 @item @command{nslookup} @tab @tab @tab Does a nameserver query about
579 @var{nick} host, @var{host} or @var{ip address}.
581 @item @command{op} @tab Yes @tab @tab Ops @var{nick} on @var{channel}.
583 @item @command{part} @tab Yes @tab @tab Makes the bot leave @var{channel}.
585 @item @command{password} @tab @tab @tab Changes your password on the
586 bot. Use @code{NONE} as password if you want to clear it. Do not use this
589 @item @command{reconnect} @tab @tab @tab Makes the bot reconnect to
592 @item @command{rspymessage} @tab @tab @tab Removes you from the spy
595 @item @command{save} @tab @tab @tab Saves the userlist.
597 @item @command{say} @tab Yes @tab @tab Makes the bot say @var{message}
600 @item @command{server} @tab @tab @tab Select the server to connect
601 to. @var{server number} is the number of the server in the serverlist.
603 @item @command{serverlist} @tab @tab @tab Shows the bot's serverlist.
605 @item @command{setfloodrate} @tab @tab @tab
607 @item @command{setversion} @tab @tab @tab
609 @item @command{shitlist} @tab @tab @tab Shows the bot's shitlist.
611 @item @command{spylist} @tab @tab @tab Shows the bot's spylist.
613 @item @command{spymessage} @tab @tab @tab Adds you to the spylist
615 @item @command{stats} @tab Yes @tab @tab Gives @var{channel}'s statistics.
617 @item @command{tban} @tab Yes @tab @tab Bans @var{nick} or @var{mask}
618 from @var{channel} for @var{time} seconds.
620 @item @command{tkban} @tab Yes @tab @tab Bans @var{nick} or @var{mask}
621 from @var{channel} for @var{time} seconds, then kicks him/them because
624 @item @command{topic} @tab Yes @tab @tab If no @var{topic}is given,
625 prints @var{channel}'s topic. Otherwise, the bot will change
626 @var{channel}'s topic to @var{topic}.
628 @item @command{unlock} @tab Yes @tab @tab Makes the bot unlock topic
631 @item @command{userlist} @tab @tab @tab Shows the bot's userlist
633 @item @command{who} @tab Yes @tab @tab Show your level on @var{channel}
635 @item @command{whois} @tab Yes @tab @tab Shows information about
636 @var{nick} on @var{channel}
640 @node Scripting, Concept Index, Using the Bot, Top
643 Bobot++'s most powerful feature is its scripting system. You write
644 scripts using Guile Scheme. This manual does not cover how to use
645 Guile or how to learn Scheme. @xref{Top, , Guile Reference Manual,
646 guile, The Guile Reference Manual}, for the Guile reference manual and
647 @url{http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html} for
648 a good tutorial on Scheme.
650 Note that in previous versions the scripting commands where in the
651 form @code{bot-@var{function}}. They are now in the form
652 @code{bot:@var{function}}. The old names are still available, but are
653 deprecated and will be removed in Bobot++ 3.0. New commands are only
654 available with the @code{bot:} prefix. The command @command{perl -pi
655 -e ``s/bot-/bot:/g'' @var{your-files}} should be enough to convert
656 your code to use the new functions.
658 @strong{NOTE}: All arguments to functions and hooks called by the bot
659 are strings unless otherwise specified.
662 * Adding New Commands::
665 * Misc Scripting Stuff::
668 @node Adding New Commands, Hooks, Scripting, Scripting
669 @section Adding New Commands
671 Adding a new command is simple. To register a new command use
672 @code{bot:addcommand}.
674 @defun bot:addcommand name func needs-channel? num-of-args min-level
676 The @var{name} is a string representing the name of the command being
677 added. @var{func} is a function accepting @var{num-of-args}
678 arguments. @var{needs-channel?} is a bool that is true if the function
679 needs the channel name as its first arg, and false otherwise.
680 @var{num-of-args} is the number of args @var{func} will take and must
681 be within zero (0) and twenty (20). @var{min-level} is one of the
682 @ref{User Levels}. A user must be at least a @var{min-level} user to
683 use the new command. None of the arguments are guaranteed to be
684 passed; if they aren't they are set to the empty string @code{""}. An
685 example of a new command would be:
688 (define (hello channel name)
689 (if (string=? name "")
690 (bot:say channel "Hello world!")
691 (bot:say channel (string-append "Hello " name "!")))
693 (bot:addcommand "hello" hello #t 2 0)
696 This will display ``Hello World!'' if called as @kbd{!hello} and
697 ``Hello World @var{USER}'' if called as @kbd{!hello @var{USER}}.
700 @node Hooks, Sending Messages, Adding New Commands, Scripting
703 @cindex Background on Hooks
704 Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
705 and tiny fugue (a MUD bot) hooks with a little bit of extra stuff
706 added in. A hook is called when a regular expression is matched
707 against a message sent to or by the bot.
709 Bobot++ uses different hook types for each IRC message type, and also
710 includes a hook for accessing raw irc messages. Hooks are tagged with
711 a priority and a flag that specifies whether to call the next hook
712 that matches after calling the current one or to stop
715 Hooks are processed from the highest to lowest priority, with
716 fallthrough hooks of equal priority to non-fallthrough hooks being
724 @node Creating a Hook, Hook Types, Hooks, Hooks
725 @subsection Creating a Hook
727 To add a new hook you use the function @code{bot:addhook}.
729 @defun bot:addhook type regex function [pri fall name]
730 @var{type} specifies the type of hook (the types of hooks are listed
731 in @ref{Hook Types}).
733 @var{regex} is a standard regular expression. If
734 @var{regex} is matched, @var{function} will be called.
736 @var{function} will take a different number of args depending on the
739 @var{pri} specifies the priority of the hook---higher priority hooks
740 are executed first. This argument is optional and defaults to
743 @var{fall} is @code{#t} if the hook is a fallthrough hook and
744 @code{#f} is the hook is not a fallthrough hook. This arg is also
745 optional and defaults to @code{#t}.
747 @var{name} is the optional name of the hook that defaults to
748 @code{"DEFAULT"}. If you set the name then you can have more than
749 one hook that matches the same regexp, as long as they have the same
750 name. E.g. in a log script you could have the regexps for the log
751 function all be @code{".*"} and set their names to @code{"log"} to
752 avoid a conflict with other hooks.
755 @node Hook Types, , Creating a Hook, Hooks
756 @subsection Hook Types
758 The following sections document the different hooks Bobot++ exposes.
760 The general format of each hook description is as if it were a
761 function to be defined, but these describe the function to be passed
762 to @code{bot:add-hook}. Do @emph{not} name your functions these
765 That said, here is the list of available hooks functions.
769 * Received Message Hooks::
770 * Sent Message Hooks::
772 * Miscellaneous Hooks::
775 @node Received Message Hooks, Sent Message Hooks, Hook Types, Hook Types
776 @subsubsection Receieved Message Hooks
778 The following hooks are triggered when a mesage is received by the bot.
780 @defun hooks/action from to action
781 This hook is triggered when someone performs an action.
783 @var{from} is the nickname the person that performed the
786 @var{to} is the target of the action, which is either a channel or the
787 Bot's nick if the user private messages the bot.
789 @var{action} is the text of the action. E.g. if someone did @samp{*
790 foobar does baz}, then @var{action} would be the string @code{"does
794 @defun hooks/nickname old-nick new-nick
795 This hook is called when someone changes his nickname from
796 @var{old-nick} to @var{new-nick}.
799 @defun hooks/signoff nick message
800 This hook is called when someone signs off of IRC.
802 @var{nick} is the nickname of the person signing off.
804 @var{message} is his quit message
807 @defun hooks/ctcp nick to command rest
808 This hook is called when a CTCP request is received by the bot.
810 @var{nick} is the nickname of the sender.
812 @var{to} is the target of the CTCP request. This will either be a
813 channel the bot is in, or the nickname of the bot.
815 @var{command} is the CTCP command issued.
817 @var{rest} contains the arguments to the CTCP command.
820 @defun hooks/ctcp-reply nick command rest
821 This hook is called when a CTCP REPLY is received. This occurs when
822 the bot has sent a CTCP request to another client. The CTCP REPLY is
823 always addressed to the bot directly.
825 @var{nick} is the nickname of the person who replied.
827 @var{command} is the command to which @var{nick} is replying.
829 @var{rest} contains the body of the reply.
832 @defun hooks/disconnect server intentional
833 This is called when the bot is disconnected from a server.
835 @var{server} is the hostname of the server from which the bot was
838 @var{intentional} is a flag set to @code{#t} when the bot disonnected
839 from the server as the result of a command (issued by a user from IRC,
840 SIGHUP, or from a script), or @code{#f} when the bot disconnected from
841 the server unintentionally..
844 @defun hooks/invite nick channel
845 This hook is called when a user invited the bot to join a channel.
847 @var{nick} is the nickname of the user who sent the invite.
849 @var{channel} is the channel to which the bot was invited.
852 @defun hooks/join nick channel
853 This is called when a user or the bot joins a channel.
855 @var{nick} is the nickname of the user who joined @var{channel}. This
856 may be the bot's nickname (the IRC server sends the JOIN command back
857 to the the bot after it joins a channel).
859 @var{channel} is the channel that was joined
862 @defun hooks/kick target from channel reason
863 This hook is called when a user, including the bot, is kicked out of a
866 @var{target} is the nick of the user who was kicked. This may be the
869 @var{from} is the nick of the user who issued the kick. This may also
872 @var{channel} is the channel the kick was issued in.
874 @var{reason} is the reason the user was kicked.
877 @defun hooks/part nick channel
878 This hook is called when a user parts a channel.
880 @var{nick} is the user who parted the channel. This may be the bot.
882 @var{channel} is the channel from which the user parted.
885 @defun hooks/mode nick target modes
886 This hook is called when someone sets the modes of @var{target}.
888 @var{nick} is the user who set the modes. This may be the bot.
890 @var{target} is the target of the MODE command. This may be a
891 channel or a user. If it is a user, it may be the bot.
893 @var{modes} is the MODE string.
896 @defun hooks/message nick message
897 This hook is called when someone sends a private message to the bot.
899 @var{nick} is the nickname of the user who sent the message.
901 @var{message} is the message the user sent.
904 @defun hooks/notice nick message
905 This hook is called when a user send a private notice to the bot.
907 @var{nick} is the user who sent the notice.
909 @var{message} is the message the user sent.
912 @defun hooks/public nick channel message
913 This hook is called when a user sends a normal message to a channel.
915 @var{nick} is the user who sent the message.
917 @var{channel} is the channel to which the message was sent.
919 @var{message} is the message that was sent.
922 @defun hooks/public-notice nick channel message
923 This hook is called when a user send a notice to a channel.
925 @var{nick} is the user who sent the notice.
927 @var{channel} is the channel to which the notice was sent.
929 @var{message} is the message that was sent.
932 @defun hooks/raw raw-message
933 This hook is called every time a message is received. This matches on
934 the raw message text and passes the hook function the raw IRC message.
936 @var{raw-message} is the raw IRC message.
939 @defun hooks/topic nick channel new-topic
940 This hook is called when a user changes the topic in a channel.
942 @var{nick} is the user who set the topic. This may be the bot.
944 @var{channel} is the channel that's topic was changed.
946 @var{new-topic} is the new topic.
949 @node Sent Message Hooks, DCC CHAT Hooks, Received Message Hooks, Hook Types
950 @subsubsection Sent Message Hooks
952 These hooks are called when the bot sends a message. @var{mynick} is
953 always the bot's nick and will not be documented in each hook
956 @defun hooks/send/public mynick channel message
957 This hook is called when the bot sends a normal message to a channel.
959 @var{channel} is the channel to which the bot sent the message.
961 @var{message} is the message the bot sent.
964 @defun hooks/send/message mynick to message
965 This hook is called when the bot sends a private message to a user.
967 @var{to} is the nick of the user to whom the message was sent.
969 @var{message} is the message that was sent.
972 @defun hooks/send/action mynick to message
973 This hook is called when the bot sents an action to a channel or a
976 @var{to} is the channel or nick of the user to which the action was
979 @var{message} is the text of the action.
982 @defun hooks/send/ctcp mynick to command message
983 This hook is called when the bot sends a CTCP message @emph{other
984 than} an ACTION to a channel or user.
986 @var{to} is the channel or nick of the user to which the CTCP was
989 @var{command} is the CTCP command that was sent.
991 @var{message} is a string containing the arguments to the CTCP command.
994 @defun hooks/send/who who
995 This is called when the bot sends a WHO message. The regex is matched
996 on @var{who}, which is also passed as the only argument to your
999 @var{who} is the channel or nick that was WHOed.
1002 @defun hooks/send/whois nick
1003 This is called when the bot sends a WHOIS message. The regex is
1004 matched on @var{nick}, which is also passed as the only argument to
1007 @var{nick} is the nickname of the person who was WHOISed.
1010 @node DCC CHAT Hooks, Miscellaneous Hooks, Sent Message Hooks, Hook Types
1011 @subsubsection DCC CHAT Hooks
1013 These hooks are called when a user initializes a DCC CHAT and when the
1014 bot receives messages from the user in a DCC CHAT.
1016 @defun hooks/dcc/chat-begin from
1017 This hook is called when a user begins a DCC CHAT with the bot.
1018 @var{from} is the user's address in the form @samp{nick!user@@host}.
1021 @defun hooks/dcc/chat-end address
1022 This hook is called when a DCC CHAT is purged after being idle for a
1023 while, or when the user closes the DCC CHAT. As such, you cannot write
1024 any more data to the DCC CHAT.
1026 @var{address} is the address (nick!user@@host) of the person on the
1027 other side of the DCC.
1030 @defun hooks/dcc/chat-message from message
1031 This hook is called when a user sends a message to the bot through
1034 @var{from} is the user's address in the form @samp{nick!user@@host}.
1036 @var{message} is the message the user sent to the bot.
1039 @node Miscellaneous Hooks, , DCC CHAT Hooks, Hook Types
1040 @subsubsection Miscellaneous Hooks
1042 @defun hooks/flood nick
1043 This hook is called when a user is detected flooding the bot.
1045 @var{nick} is the nickname of the user flooding the bot.
1048 @defun hooks/timer time
1049 This hook is called once a minute. The regex is @strong{not} used.
1051 @var{time} is the in zero-padded @code{hh:mm} format.
1055 @node Sending Messages, Misc Scripting Stuff, Hooks, Scripting
1056 @section Sending Messages
1058 There are several types of messages you can send with Bobot++ from
1059 scripts. They are split into High and Low level message sending
1060 functions. Most bots will only use the high level functions, but the
1061 low level ones are provided for when a bot needs to do things like
1062 send raw IRC messages or CTCP commands.
1065 * High Level Message Functions::
1066 * Low Level Message Functions::
1069 @node High Level Message Functions, Low Level Message Functions, Sending Messages, Sending Messages
1070 @subsection ``High Level'' Message Functions
1072 @defun bot:say channel message
1073 Send a public or private @var{message} to @var{channel}.
1075 Sends a normal text message, as if a user had typed it in. The
1076 @var{dest} can be a nickname or a channel.
1079 @defun bot:action channel message
1080 Send an ``action'' type @var{message} to @var{channel}
1084 @defun bot:msg target message
1085 @defunx bot:say target message
1086 Send a public or private message to @var{target}.
1088 @var{target} may be a channel or a nickname.
1090 In versions of Bobot++ prior to 2.1.8 @code{bot:say} could only send
1091 to channels, and @code{bot:msg} could only send private messages to
1092 users. They are aliases of the same command now, but it may be worth
1093 using them as they used to for clarity.
1096 @defun bot:notice target message
1097 Sends @var{message} as a NOTICE to @var{target}. @var{target} may be a
1098 user (nick) or a channel.
1101 @node Low Level Message Functions, , High Level Message Functions, Sending Messages
1102 @subsection ``Low Level'' Message Functions
1104 @c Add a url for rfc2812
1105 The ``Low Level'' messaging functions allow you to do things like send
1106 CTCP messages. You probably want to read rfc 2812 and the CTCP spec
1107 before using these. If you have no idea what these do, read rfc 2812
1108 (IRC Client Protocol) and CTCP spec. These functions all return
1109 @code{*unspecified*} always, so don't use the return value for
1112 @defun bot:ctcp to command message
1113 @var{to} is the target of your CTCP message, @var{command} is the
1114 CTCP command, and @var{message} is the message (or arguments) of the
1115 command. Make sure to @code{bot:ctcp-quote} the message!
1118 @defun bot:ctcp-reply to command message
1119 @var{to} is the target of your CTCP reply, @var{command} is the
1120 CTCP command, and @var{message} is the message (or arguments) of the
1121 command. Make sure to @code{bot:ctcp-quote} the message!
1123 This is used to reply to a ctcp that the bot has received.
1126 @node Misc Scripting Stuff, , Sending Messages, Scripting
1127 @section Misc. Scripting Stuff
1129 These are a few useful things that I thought people writing scripts
1133 If you want to execute code when the bot exits, just do
1134 @code{add-hook! bot:exit-hook @var{thunk}} where @var{thunk} is an
1135 argumentless procedure (a thunk). When the bot exits your thunk will
1139 [ I didn't know where to put any of these, so I just stuck them in
1142 There probably needs to be several sections added, like dealing with
1143 users (kicking, added, etc), dealing with the bot (channels, nickname
1144 of the bot, etc), server issues (serverlist), useful tools (nslookup,
1145 whois), and do on. ]
1149 @defun bot:adduser nick-or-mask cbannel-mask level prot auto-op
1150 Adds an user to the userlist, for a @code{nick!user@@host} matching the
1151 one given, on a channel matching the @var{channelMask} given.
1153 @multitable @columnfractions 0.33 0.33 0.33
1154 @item The @var{level} can be: @tab The @var{prot} can be: @tab The @var{auto-op} can be:
1155 @item 0 - No level @tab 0 - No protection @tab 0 - No auto-op
1156 @item 1 - User @tab 1 - No ban @tab 1 - Op on join
1157 @item 2 - Trusted User @tab 2 - No kick @tab
1158 @item 3 - Friend @tab 3 - No deop @tab
1159 @item 4 - Master @tab @tab
1165 @defun bot:addserver hostname ip-address [portnumber]
1166 Adds the server specified by @var{hostname} or @var{ip-address} to
1171 @defun bot:addshit nick-or-mask channel-mask level [time reason]
1172 Adds an user to the shitlist, for a nick!user@@host matching the
1173 one given, on a channel matching the @var{channelMask} given.
1176 The @var{level} can be:
1179 2 - Kick and Ban on join
1180 3 - Kick and Ban on join, no deban
1186 @defun bot:ban channel mask-or-nick
1187 Bans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
1188 user to ban with a @var{mask}.
1192 @defun bot:change-command-level nick-or-mask channel-mask new-level
1193 Gives @var{nick} or @var{mask} level @var{new-level} on channel(s)
1194 @var{channel-mask}. Note that you can not change level for someone
1195 whose level is greater than yours, and that you can not give a
1196 level greater than yours.
1200 @defun bot:cycle channel
1201 Makes the bot leave and join @var{channel}.
1205 @defun bot:deban channel mask-or-nick
1206 Debans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
1207 user to deban with a @var{mask}.
1211 @defun bot:delserver server-number
1212 Deletes server from server list whose number in the server list
1213 is @var{server-number}
1217 @defun bot:deluser nick-or-mask channel-mask
1218 Removes @var{nick} or @var{mask} from the userlist.
1222 @defun bot:delshit nick-or-mask channel-mask
1223 Removes @var{nick} or @var{mask} from the shitlist.
1227 @defun bot:deop channel mask-or-nick
1228 Deops @var{mask} or @var{nick} on @var{channel}.
1232 @defun bot:die reason
1233 Makes the bot stop immediately.
1241 @defun bot:invite channel nick
1242 Invites @var{nick} on @var{channel}.
1246 @defun bot:join channel
1247 Makes the bot join @var{channel}.
1251 @defun bot:keep channel modes
1252 Sets the @var{modes} that the bot will keep for @var{channel}.
1257 @defun bot:kick channel mask-or-nick [reason]
1258 Kicks @var{mask} or @var{nick} out of @var{channel}, because of @var{reason}.
1259 You need to be a trusted user to use a @var{mask}.
1263 @defun bot:kickban channel mask-or-nick [reason]
1264 Bans then kicks @var{mask} or @var{nick} out of @var{channel},
1265 because of @var{reason}.
1266 You need to be a trusted user to use a @var{mask}.
1270 @defun bot:lock channel
1271 Locks topic on @var{channel}.
1276 [ Probably returns the log port? ]
1280 @defun bot:mode channel mode-string
1281 Sends @var{mode-string} as mode for @var{channel}.
1285 @defun bot:nextserver
1286 Makes the bot connect to the next server in its server list.
1290 @defun bot:nick nick
1291 Makes the bot use nickname @var{nick}.
1295 @defun bot:op channel nick
1296 Ops @var{nick} on @var{channel}.
1300 @defun bot:part channel
1301 Makes the bot leave @var{channel}.
1305 @defun bot:reconnect
1306 Makes the bot reconnect to its current server.
1310 @defun bot:server server-number
1311 Select the server to connect to. @var{server-number} is the number of
1312 the server in the serverlist.
1316 @defun bot:setfloodrate ?
1320 @defun bot:setversion ?
1324 @defun bot:tban channel nick-or-mask time
1325 Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds.
1329 @defun bot:tkban channel nick-or-mask time [reason]
1330 Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds,
1331 then kicks him/them because of @var{reason}.
1335 @defun bot:topic channel topic
1336 If no @var{topic} is given, prints @var{channel}'s topic. Otherwise,
1337 the bot will change @var{channel}'s topic to @var{topic}.
1340 @defun bot:unlock channel
1341 Makes the bot unlock topic on @var{channel}.
1344 @defun bot:who target
1345 Sends a WHO command to @var{target}. @var{target} may be either a
1349 @defun bot:whois nick
1350 Sends a WHOIS command to @var{nick}. @var{nick} @strong{must} be a
1351 nickname, you cannot send a WHOIS to a channel.
1355 @defun bot:getnickname
1356 [ Gets the bot's nickname? ]
1360 @defun bot:getserver
1364 @defun bot:getserverlist
1369 [ Flushes the socket to the server? ]
1373 @defun bot:flushport
1374 [ Flushes the log port? ]
1379 [ Returns a random number? What range? Why? ]
1383 @defun bot:delcommand
1384 [ Probably deletes a command added with @code{bot:addcommand} ? ]
1388 @defun bot:addtimer ? ?
1392 @defun bot:deltimer ?
1396 @defun bot:dcc-chat-send ? ?
1400 [ And what about the stuff defined in @file{bobot-utils.scm} ? I just
1401 added it here so it could be somewhere. There should also be a
1402 section dealing with modules. How to use them. What module scripts
1403 are in. What module bobot++ provided primites are in. And so on. ]
1406 @defun bot:log . messages
1407 Write as many @var{messages} as you want to the log. If the arg is a
1408 thunk it will be executed and it's output will be written to the log.
1411 @defun bot:load file
1414 @defun bot:load-module module-spec
1417 @defun bot:use-module module-spec
1420 @defun bot:match-not-channel regex
1421 match-not-channel adds a prefix regex to your @var{regex} so it
1422 doesn't match the sender or channel in a PUBLIC message
1425 @defun bot:match-to-me regex
1426 match-to-me matches text that was addressed to the bot with a
1427 ':', ',', or nothing after the bot name.
1430 @defun bot:sent-to-me? message
1433 @defun bot:ctcp-quote message
1434 Returns the CTCP quoted message
1435 Input @emph{MUST NOT} contain the trailing @code{\r\n}
1436 (it is added by the message sending code).
1440 @defvar %bot:loadpath
1443 @defun %bot:load-extensions
1448 @node Concept Index, Function Index, Scripting, Top
1449 @unnumbered Concept Index
1452 @node Function Index, Variable Index, Concept Index, Top
1453 @unnumbered Function Index
1456 @node Variable Index, , Function Index, Top
1457 @unnumbered Variable Index