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::
94 * Adding New Commands::
96 * Scheme User Levels::
98 * Misc Scripting Stuff::
107 * Received Message Hooks::
108 * Sent Message Hooks::
110 * Miscellaneous Hooks::
114 * High Level Message Functions::
115 * Low Level Message Functions::
120 @node Introduction, Configuration, Top, Top
121 @chapter Introduction
123 This manual feels abused and neglected because it has almost no
126 @node Configuration, Using the Bot, Introduction, Top
127 @chapter Configuration
129 Bobot++ is easy to configure. See the @file{examples} directory for an
130 example configuration.
132 The main configuration file is @file{bot.conf}. There are several
133 auxiliary configuration files (a user list, aliases file, ban list,
134 and a script autoexec).
137 * Configuration File Placement::
138 * Configuration Files::
141 @node Configuration File Placement, Configuration Files, Configuration, Configuration
142 @section Configuration File Placement
144 Bobot++ will look in @file{/etc/bobotpp/default/} for its default
145 config if none is specified on the command line. Put the configuration
146 files you want to be loaded by default in this directory. If you are
147 not root, or you want to have your own personal configuration, put it
148 in @file{~/.bobotpp/config/default/}.
150 @node Configuration Files, , Configuration File Placement, Configuration
151 @section Configuration Files
158 @node bot.conf, bot.users, Configuration Files, Configuration Files
161 @file{bot.conf} contains key value pairs separated by @code{=}.
163 @code{<key> = <value>}
165 Comments are started with a @code{#} and cause the entire line to be
166 ignored. @emph{Note that this only works when the @code{#} is the first
167 character of the line}.
169 bot.conf is the main configuration file for a Bobot++. The available
170 configuration variables are listed below in the format ``@var{variable}
171 <default-value>: description''
173 A few of the options have more complex syntax, they are documented in
174 their own subsections.
183 @item @var{nickname} <Bobot>: The nickname of the bot (@var{nick} is an
184 alias for @var{nickname})
185 @item @var{username} <bobot>: The IRC username of the bot
186 @item @var{cmdchar} <!>: The character that prefixes commands given to
187 the bot (@var{command} is an alias for @var{cmdchar})
188 @item @var{ircname} <I'm a bobot++!>: The IRC name (or 'real name') of
189 the bot (@var{realname} is an alias for @var{ircname})
190 @item @var{userlist} <bot.users>: Name of the file where the userlist is
192 @item @var{shitlist} <bot.shit>: Name of the file where the shitlist
194 @item @var{logfile} <$LOGDIR/bot.log>: Location of the bot logfile
195 (set this to @file{/dev/null} to disable logging).
196 @item @var{server} <None>: This specifies the server to which the bot
197 will connect. Note that this has a special syntax @pxref{server
199 @item @var{channel} <None>: This specifies the channels the bot will join
200 when it starts up. This has a special syntax @pxref{channel
205 @node server syntax, channel syntax, bot.conf, bot.conf
206 @subsubsection server syntax
208 The server syntax in @file{bot.conf} allows you to specify an
209 alternate port to connect on, and a password to send the server.
211 You may use more than one server line; Bobot++ will attempt to connect
212 to the first one, and will connect to the next one in the list if it
213 fails. The bot will continue cycling through the server list until it
214 is able to connect to one. There is a command (@code{!cycle}) to make
215 the bot to cycle servers.
217 @var{server} = @var{server_name} [@var{port} [@var{password}]]
219 This will make Bobot++ attempt to connect to @var{server_name} on port
220 @var{port} with the password @var{password}. @var{server_name} should
221 be the address of the server. @var{port} and @var{password} are
224 @node channel syntax, , server syntax, bot.conf
225 @subsubsection channel syntax
227 The channel syntax in @file{bot.conf} allows you to specify the
228 initial modes the bot should set on a channel, the modes the bot
229 should maintain, and a key if the channel needs it.
231 You may have any number of channel lines. When Bobot++ starts it will
232 attempt to join and gain operator status in every channel listed.
235 @var{name}:@var{initial_modes}:@var{modes_to_keep}:@var{channel_key}
237 The bot will join @var{name} and set the channel modes to
238 @var{initial_modes} (e.g. ``nt'') if it is able to gain operator
239 status. It will then maintain @var{modes_to_keep}. If the channel
240 requires a key to enter simply set @var{channel_key}. Every argument
241 except for @var{name} is optional.
246 @var{channel} = #foo:nt:nt:bar
249 The bot will join @code{#foo} with the channel key @code{bar} and will
250 then maintain the modes @code{nt}.
253 @var{channel} = #bar:::
256 The bot will join @code{#bar} and will not set any modes nor will it
257 attempt to maintain any modes.
259 @node bot.users, , bot.conf, Configuration Files
260 @subsection bot.users
262 @file{bot.users} is the default file name of the userlist. It may be
263 changed in @file{bot.conf}. The file contains lines with the format:
265 @samp{@var{mask}:@var{channel}:@var{level}:@var{protection}:@var{auto-op}}
269 @item @var{mask} is the host mask
270 (e.g. @samp{*!*username@*.domain.com}) of the user
272 @item @var{channel} is a channel mask of the channels that the user
273 has priviliges to use the bot in (e.g. @samp{*} for all channels,
274 @samp{#*} for all non-local channel, @samp{#foo*} for all channels
275 starting with ``foo,'' @samp{#bar} for channel ``#bar'' only, etc.)
277 @item @var{level} is the user level of the user (@ref{User Levels}).
279 @item @var{protection} is the protection level of the user
282 @item @var{auto-op} is set to control whether a user is automatically
283 given operator priviliges on channel entry (@ref{Automatic Op}).
287 @node Using the Bot, Scripting, Configuration, Top
288 @chapter Using Bobot++
297 * Built-In Commands::
300 @node Starting the Bot, User Levels, Using the Bot, Using the Bot
301 @section Starting the Bot
303 The bot is usually installed with the binary name @file{bobotpp}. It
304 accepts the following command line arguments.
307 @item @code{[--help][-h]} - Shows detailed help and exits
308 @item @code{[--version][-v]} - Shows version information and exits
309 @item @code{[--no-background][-b]} - Run bobot++ in the foreground
310 @item @code{[--config-file file][-f]} - Use file instead of @file{bot.conf}
311 @item @code{[--config-dir dir][-d]} - Use dir as dir to load config file from
312 @item @code{[--config dir][-c]} - Search your config path (defaults to
313 @file{@var{$HOME}/.bobotpp/config/} and then @file{/etc/bobotpp/}) for
314 dir and then loads your config data using dir
315 @item @code{[--sys-config dir][-s]} - Looks for config in
316 @file{/etc/bobotpp/dir}. Note that the user dir is still searched
318 @item @code{[--user-config dir][-u]} - Looks for config in
319 @file{@var{$HOME}/.bobotpp/config/dir/}. Note that the system dir is
320 still searched after this if dir is not found.
321 @item @code{[--debug][-D]} Makes Bobot++ print debugging info and run
323 @item @code{[--debug-scripts][-S]} Enabled the Guile debugging
324 evaluator for verbose script errors and backtraces while still running
325 the bot in the background.
328 The default configuration is read from
329 @file{@var{$HOME}/.bobotpp/config/default/} and then
330 @file{/etc/bobotpp/default/} if the user config is not found.
332 The bot defaults to running in the background as a daemon.
334 @node User Levels, Protection, Starting the Bot, Using the Bot
337 There are several user levels available in Bobot++ to provide gradated
338 access to commands. @command{!adduser} and @file{bot.users} use the
339 numeric code; Scheme uses the textual name for the level. By default
340 (if the user is not found in the userlist) a user has access to
341 commands with the level @code{bot:user-none}.
345 @item @code{bot:user-none} - No @strong{built-in} commands may be
346 executed @emph{by default} (commands may be added from Scheme that can
347 be executed by users of level none and the level required to execute a
348 command may be changed from Scheme).
350 @item @code{bot:user-user} - Will be able to execute most commands but
351 not all and cannot use masks on kicks and bans.
353 @item @code{bot:user-trusted} - For built-ins with a default
354 configuration this user has access to the same set of commands as an
355 @code{user} but may use masks on kicks and bans. Scheme commands may
356 be added which require a user to be of this level.
358 @item @code{bot:user-friend} - In the default configuration a user who
359 is a friend will be able to do everything short of stopping the
360 bot. Again, there may be user added commands that require a higher
363 @item @code{bot:user-master} - This is the highest user level and has
364 access to every feature of the bot.
368 @node Protection, Automatic Op, User Levels, Using the Bot
371 A user added via Scheme, the @file{bot.users} file, or
372 @command{!adduser} may be protected from being deoped, kicked, or
373 banned. The user list and IRC commands use the numeric codes, Scheme
374 uses the symbolic names.
377 @item @code{bot:protection/none} No protection
378 @item @code{bot:protection/no-ban} No ban. If a user is banned the bot will unban him..
379 @item @code{bot:protection/no-kick} No kick. The user may still be kicked but the bot will kickban
380 the user who kicked the protected user.
381 @item @code{bot:protection/no-deop} No deop. The bot will ensure that the user always maintains
385 @node Automatic Op, Built-In Commands, Protection, Using the Bot
386 @section Automatic Op
388 A user may be automatically given operator status upon entering a
389 channel. Scheme uses the symbolic name, the user list
390 (@file{bot.users}) and IRC commands use the numeric value.
393 @item @code{bot:aop/no} Do not automatically op the user
394 @item @code{bot:aop/yes} Do automatically op the user
397 @node Built-In Commands, , Automatic Op, Using the Bot
398 @section Built-In Commands
400 Bobot++ has many built-in commands that make it useful without
401 scripting support. The reference leaves off the command char; remember
402 to use whatever you defined the command char to be in
403 @file{bot.conf}. If a command needs the channel name then you must
404 specify the channel as the first argument to the command when private
405 messaging the bot a command.
407 @multitable @columnfractions 0.20 0.15 0.15 0.50
408 @item @sc{command} @tab @sc{Needs Channel} @tab @sc{Min Level to Use} @tab @sc{Description}
410 @item @command{action} @option{do} @tab Yes @tab @var{USER} @tab
411 Causes the bot to perform the action @option{do} in the current
414 @item @command{adduser} @tab @tab @tab
416 @item @command{addserver} @tab @tab @tab Adds the server specified by
417 @var{host name} or @var{ip address} to the server list.
419 @item @command{addshit} @tab @tab @tab
421 @item @command{alias} @tab @tab @tab Makes an alias, and adds the
422 function @var{new name}, that will do exactly the same command as
425 @item @command{ban} @tab @tab @tab Bans @var{mask} or @var{nick} from
426 @var{channel}. You need to be a trusted user to ban with a
429 @item @command{banlist} @tab @tab @tab
431 @item @command{channels} @tab @tab @tab Prints the channel(s) where
432 the bot is currently.
434 @item @command{cycle} @tab Yes @tab @tab Makes the bot leave and join
437 @item @command{dcclist} @tab @tab @tab Gives the list of all DCC Chat
440 @item @command{deban} @tab Yes @tab @tab Debans @var{mask} or
441 @var{nick} from @var{channel}. You need to be a trusted user to deban
444 @item @command{delserver} @tab @tab @tab Deletes server from server
445 list whose number in the server list is @var{server number}.
447 @item @command{deluser} @tab @tab @tab Removes @var{nick} or
448 @var{mask} from the userlist.
450 @item @command{delshit} @tab @tab @tab Removes @var{nick} or
451 @var{mask} from the shitlist.
453 @item @command{deop} @tab Yes @tab @tab Deops @var{mask} or @var{nick}
456 @item @command{die} @tab @tab @tab Makes the bot stop immediately.
458 @item @command{do} @tab @tab @tab
460 @item @command{execute} @tab @tab @tab @strong{Only available if
461 scripting support is enabled}
463 @item @command{help} @tab @tab @tab
465 @item @command{ident} @tab @tab @tab Identifies you on the bot. Note
466 that you should not use this command in public @dots{}
468 @item @command{invite} @tab Yes @tab @tab Invites @var{nick} on
471 @item @command{join} @tab @tab @tab Makes the bot join @var{channel}.
473 @item @command{keep} @tab Yes @tab @tab Sets the @var{modes} that the
474 bot will keep for @var{channel}.
476 @item @command{kick} @tab Yes @tab @tab Kicks @var{mask} or @var{nick}
477 out of @var{channel}, because of @var{reason}. You need to be a
478 trusted user to use a @var{mask}.
480 @item @command{kickban} @tab Yes @tab @tab Bans then kicks @var{mask}
481 or @var{nick} out of @var{channel}, because of @var{reason}. You need
482 to be a trusted user to use a @var{mask}.
484 @item @command{load} @tab @tab @tab Reloads the userlist from disk.
486 @item @command{loadscript} @tab @tab @tab @strong{Only available if
487 scripting support is enabled}
489 @item @command{lock} @tab @tab @tab Locks topic on @var{channel}.
491 @item @command{mode} @tab Yes @tab @tab Sends @var{mode string} as
492 mode for @var{channel}.
494 @item @command{msg} @tab @tab @tab
496 @item @command{names} @tab Yes @tab @tab Shows the nicknames and
497 status of users on @var{channel}.
499 @item @command{nextserver} @tab @tab @tab Makes the bot connect to the
500 next server in its server list.
502 @item @command{nick} @tab @tab @tab Makes the bot use nickname @var{nick}.
504 @item @command{nslookup} @tab @tab @tab Does a nameserver query about
505 @var{nick} host, @var{host} or @var{ip address}.
507 @item @command{op} @tab Yes @tab @tab Ops @var{nick} on @var{channel}.
509 @item @command{part} @tab Yes @tab @tab Makes the bot leave @var{channel}.
511 @item @command{password} @tab @tab @tab Changes your password on the
512 bot. Use @code{NONE} as password if you want to clear it. Do not use this
515 @item @command{reconnect} @tab @tab @tab Makes the bot reconnect to
518 @item @command{rspymessage} @tab @tab @tab Removes you from the spy
521 @item @command{save} @tab @tab @tab Saves the userlist.
523 @item @command{say} @tab Yes @tab @tab Makes the bot say @var{message}
526 @item @command{server} @tab @tab @tab Select the server to connect
527 to. @var{server number} is the number of the server in the serverlist.
529 @item @command{serverlist} @tab @tab @tab Shows the bot's serverlist.
531 @item @command{setfloodrate} @tab @tab @tab
533 @item @command{setversion} @tab @tab @tab
535 @item @command{shitlist} @tab @tab @tab Shows the bot's shitlist.
537 @item @command{spylist} @tab @tab @tab Shows the bot's spylist.
539 @item @command{spymessage} @tab @tab @tab Adds you to the spylist
541 @item @command{stats} @tab Yes @tab @tab Gives @var{channel}'s statistics.
543 @item @command{tban} @tab Yes @tab @tab Bans @var{nick} or @var{mask}
544 from @var{channel} for @var{time} seconds.
546 @item @command{tkban} @tab Yes @tab @tab Bans @var{nick} or @var{mask}
547 from @var{channel} for @var{time} seconds, then kicks him/them because
550 @item @command{topic} @tab Yes @tab @tab If no @var{topic}is given,
551 prints @var{channel}'s topic. Otherwise, the bot will change
552 @var{channel}'s topic to @var{topic}.
554 @item @command{unlock} @tab Yes @tab @tab Makes the bot unlock topic
557 @item @command{userlist} @tab @tab @tab Shows the bot's userlist
559 @item @command{who} @tab Yes @tab @tab Show your level on @var{channel}
561 @item @command{whois} @tab Yes @tab @tab Shows information about
562 @var{nick} on @var{channel}
566 @node Scripting, Concept Index, Using the Bot, Top
569 Bobot++'s most powerful feature is its scripting system. You write
570 scripts using Guile Scheme. This manual does not cover how to use
571 Guile or how to learn Scheme. @xref{Top, , Guile Reference Manual,
572 guile, The Guile Reference Manual}, for the Guile reference manual and
573 @url{http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html} for
574 a good tutorial on Scheme.
576 Note that in previous versions the scripting commands where in the
577 form @code{bot-@var{function}}. They are now in the form
578 @code{bot:@var{function}}. The old names are still available, but are
579 deprecated and will be removed in Bobot++ 3.0. New commands are only
580 available with the @code{bot:} prefix. The command @command{perl -pi
581 -e ``s/bot-/bot:/g'' @var{your-files}} should be enough to convert
582 your code to use the new functions.
584 @strong{NOTE}: All arguments to functions and hooks called by the bot
585 are strings unless otherwise specified.
588 * Adding New Commands::
590 * Scheme User Levels::
592 * Misc Scripting Stuff::
595 @node Adding New Commands, Hooks, Scripting, Scripting
596 @section Adding New Commands
598 Adding a new command is simple. To register a new command use
599 @code{bot:addcommand}.
601 @defun bot:addcommand name func needs-channel? num-of-args min-level
603 The @var{name} is a string representing the name of the command being
604 added. @var{func} is a function accepting @var{num-of-args}
605 arguments. @var{needs-channel?} is a bool that is true if the function
606 needs the channel name as its first arg, and false otherwise.
607 @var{num-of-args} is the number of args @var{func} will take and must
608 be within zero (0) and twenty (20). @var{min-level} is one of the
609 @ref{Scheme User Levels}. A user must be at least a @code{min-level}
610 user to use the new command. None of the arguments are guaranteed to
611 be passed; if they aren't they are set to the empty string @code{""}.
612 An example of a new command would be:
615 (define (hello channel name)
616 (if (string=? name "")
617 (bot:say channel "Hello world!")
618 (bot:say channel (string-append "Hello " name "!")))
620 (bot:addcommand "hello" hello #t 2 0)
623 This will display ``Hello World!'' if called as @kbd{!hello} and
624 ``Hello World @var{USER}'' if called as @kbd{!hello @var{USER}}.
627 @node Hooks, Scheme User Levels, Adding New Commands, Scripting
630 @cindex Background on Hooks
631 Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
632 and tiny fugue (a MUD bot) hooks with a little bit of extra stuff
633 added in. A hook is called when a regular expression is matched
634 against a message sent to or by the bot.
636 Bobot++ uses different hook types for each IRC message type, and also
637 includes a hook for accessing raw irc messages. Hooks are tagged with
638 a priority and a flag that specifies whether to call the next hook
639 that matches after calling the current one or to stop
642 Hooks are processed from the highest to lowest priority, with
643 fallthrough hooks of equal priority to non-fallthrough hooks being
651 @node Creating a Hook, Hook Types, Hooks, Hooks
652 @subsection Creating a Hook
654 To add a new hook you use the function @code{bot:addhook}.
656 @defun bot:addhook type regex function [pri fall name]
657 @var{type} specifies the type of hook (the types of hooks are listed
658 in @ref{Hook Types}).
660 @var{regex} is a standard regular expression. If
661 @var{regex} is matched, @var{function} will be called.
663 @var{function} will take a different number of args depending on the
666 @var{pri} specifies the priority of the hook---higher priority hooks
667 are executed first. This argument is optional and defaults to
670 @var{fall} is @code{#t} if the hook is a fallthrough hook and
671 @code{#f} is the hook is not a fallthrough hook. This arg is also
672 optional and defaults to @code{#t}.
674 @var{name} is the optional name of the hook that defaults to
675 @code{"DEFAULT"}. If you set the name then you can have more than
676 one hook that matches the same regexp, as long as they have the same
677 name. E.g. in a log script you could have the regexps for the log
678 function all be @code{".*"} and set their names to @code{"log"} to
679 avoid a conflict with other hooks.
682 @node Hook Types, , Creating a Hook, Hooks
683 @subsection Hook Types
685 The following sections document the different hooks Bobot++ exposes.
687 The general format of each hook description is as if it were a
688 function to be defined, but these describe the function to be passwd
689 to @code{bot:add-hook}. Do @emph{not} name your functions these
692 That said, here is the list of available hooks functions.
696 * Received Message Hooks::
697 * Sent Message Hooks::
699 * Miscellaneous Hooks::
702 @node Received Message Hooks, Sent Message Hooks, Hook Types, Hook Types
703 @subsubsection Receieved Message Hooks
705 The following hooks are triggered when a mesage is received by the bot.
707 @defun hooks/action from to action
708 This hook is triggered when someone performs an action.
710 @var{from} is the nickname the person that performed the
713 @var{to} is the target of the action, which is either a channel or the
714 Bot's nick if the user private messages the bot.
716 @var{action} is the text of the action. E.g. if someone did @samp{*
717 foobar does baz}, then @var{action} would be the string @code{"does
721 @defun hooks/nickname old-nick new-nick
722 This hook is called when someone changes his nickname from
723 @var{old-nick} to @var{new-nick}.
726 @defun hooks/signoff nick message
727 This hook is called when someone signs off of IRC.
729 @var{nick} is the nickname of the person signing off.
731 @var{message} is his quit message
734 @defun hooks/ctcp nick to command rest
735 This hook is called when a CTCP request is received by the bot.
737 @var{nick} is the nickname of the sender.
739 @var{to} is the target of the CTCP request. This will either be a
740 channel the bot is in, or the nickname of the bot.
742 @var{command} is the CTCP command issued.
744 @var{rest} contains the arguments to the CTCP command.
747 @defun hooks/ctcp-reply nick command rest
748 This hook is called when a CTCP REPLY is received. This occurs when
749 the bot has sent a CTCP request to another client. The CTCP REPLY is
750 always addressed to the bot directly.
752 @var{nick} is the nickname of the person who replied.
754 @var{command} is the command to which @var{nick} is replying.
756 @var{rest} contains the body of the reply.
759 @defun hooks/disconnect server intentional
760 This is called when the bot is disconnected from a server.
762 @var{server} is the hostname of the server from which the bot was
765 @var{intentional} is a flag set to @code{#t} when the bot disonnected
766 from the server as the result of a command (issued by a user from IRC,
767 SIGHUP, or from a script), or @code{#f} when the bot disconnected from
768 the server unintentionally..
771 @defun hooks/invite nick channel
772 This hook is called when a user invited the bot to join a channel.
774 @var{nick} is the nickname of the user who sent the invite.
776 @var{channel} is the channel to which the bot was invited.
779 @defun hooks/join nick channel
780 This is called when a user or the bot joins a channel.
782 @var{nick} is the nickname of the user who joined @var{channel}. This
783 may be the bot's nickname (the IRC server sends the JOIN command back
784 to the the bot after it joins a channel).
786 @var{channel} is the channel that was joined
789 @defun hooks/kick target from channel reason
790 This hook is called when a user, including the bot, is kicked out of a
793 @var{target} is the nick of the user who was kicked. This may be the
796 @var{from} is the nick of the user who issued the kick. This may also
799 @var{channel} is the channel the kick was issued in.
801 @var{reason} is the reason the user was kicked.
804 @defun hooks/part nick channel
805 This hook is called when a user parts a channel.
807 @var{nick} is the user who parted the channel. This may be the bot.
809 @var{channel} is the channel from which the user parted.
812 @defun hooks/mode nick target modes
813 This hook is called when someone sets the modes of @var{target}.
815 @var{nick} is the user who set the modes. This may be the bot.
817 @var{target} is the target of the MODE command. This may be a
818 channel or a user. If it is a user, it may be the bot.
820 @var{modes} is the MODE string.
823 @defun hooks/message nick message
824 This hook is called when someone sends a private message to the bot.
826 @var{nick} is the nickname of the user who sent the message.
828 @var{message} is the message the user sent.
831 @defun hooks/notice nick message
832 This hook is called when a user send a private notice to the bot.
834 @var{nick} is the user who sent the notice.
836 @var{message} is the message the user sent.
839 @defun hooks/public nick channel message
840 This hook is called when a user sends a normal message to a channel.
842 @var{nick} is the user who sent the message.
844 @var{channel} is the channel to which the message was sent.
846 @var{message} is the message that was sent.
849 @defun hooks/public-notice nick channel message
850 This hook is called when a user send a notice to a channel.
852 @var{nick} is the user who sent the notice.
854 @var{channel} is the channel to which the notice was sent.
856 @var{message} is the message that was sent.
859 @defun hooks/raw raw-message
860 This hook is called every time a message is received. This matches on
861 the raw message text and passes the hook function the raw IRC message.
863 @var{raw-message} is the raw IRC message.
866 @defun hooks/topic nick channel new-topic
867 This hook is called when a user changes the topic in a channel.
869 @var{nick} is the user who set the topic. This may be the bot.
871 @var{channel} is the channel that's topic was changed.
873 @var{new-topic} is the new topic.
876 @node Sent Message Hooks, DCC CHAT Hooks, Received Message Hooks, Hook Types
877 @subsubsection Sent Message Hooks
879 These hooks are called when the bot sends a message. @var{mynick} is
880 always the bot's nick and will not be documented in each hook
883 @defun hooks/send/public mynick channel message
884 This hook is called when the bot sends a normal message to a channel.
886 @var{channel} is the channel to which the bot sent the message.
888 @var{message} is the message the bot sent.
891 @defun hooks/send/message mynick to message
892 This hook is called when the bot sends a private message to a user.
894 @var{to} is the nick of the user to whom the message was sent.
896 @var{message} is the message that was sent.
899 @defun hooks/send/action mynick to message
900 This hook is called when the bot sents an action to a channel or a
903 @var{to} is the channel or nick of the user to which the action was
906 @var{message} is the text of the action.
909 @defun hooks/send/ctcp mynick to command message
910 This hook is called when the bot sends a CTCP message @emph{other
911 than} an ACTION to a channel or user.
913 @var{to} is the channel or nick of the user to which the CTCP was
916 @var{command} is the CTCP command that was sent.
918 @var{message} is a string containing the arguments to the CTCP command.
921 @node DCC CHAT Hooks, Miscellaneous Hooks, Sent Message Hooks, Hook Types
922 @subsubsection DCC CHAT Hooks
924 These hooks are called when a user initializes a DCC CHAT and when the
925 bot receives messages from the user in a DCC CHAT.
927 @defun hooks/dcc/chat-begin from
928 This hook is called when a user begins a DCC CHAT with the bot.
929 @var{from} is the user's address in the form @samp{nick!user@@host}.
932 @defun hooks/dcc/chat-end address
933 This hook is called when a DCC CHAT is purged after being idle for a
934 while, or when the user closes the DCC CHAT. As such, you cannot write
935 any more data to the DCC CHAT.
937 @var{address} is the address (nick!user@@host) of the person on the
938 other side of the DCC.
941 @defun hooks/dcc/chat-message from message
942 This hook is called when a user sends a message to the bot through
945 @var{from} is the user's address in the form @samp{nick!user@@host}.
947 @var{message} is the message the user sent to the bot.
950 @node Miscellaneous Hooks, , DCC CHAT Hooks, Hook Types
951 @subsubsection Miscellaneous Hooks
953 @defun hooks/flood nick
954 This hook is called when a user is detected flooding the bot.
956 @var{nick} is the nickname of the user flooding the bot.
959 @defun hooks/timer time
960 This hook is called once a minute. The regex is @strong{not} used.
962 @var{time} is the in zero-padded @code{hh:mm} format.
965 @node Scheme User Levels, Sending Messages, Hooks, Scripting
966 @section Scheme User Levels
973 There are five levels that a user may be when interfacing with a bot:
974 @var{none}, @var{user}, @var{trusted_user}, @var{friend},
975 @var{master}. The Scheme variables for the user levels are
976 @code{bot:user-none}, @code{bot:user-user}, @code{bot:user-trusted},
977 @code{bot:user-friend}, and @code{bot:user-master}. See @ref{User
978 Levels} for more information on User Levels.
980 When adding a new command, think about who should be able to use
981 it. Is your command a general purpose command that helps the channel
982 (e.g. @code{!seen}) that everyone should be able to use? Or is it
983 something that should be restricted? See @ref{User Levels} for
984 information on what level users can do what with the built in bot
985 commands and think about what level a user your command is targetted
986 towards. You must be @emph{very} careful when giving new commands to
987 lower level users because you can do basically everything the bot can
988 do with a script. As the scripting interface becomes more powerful,
989 you must think more about what users can use new commands you add.
991 @node Sending Messages, Misc Scripting Stuff, Scheme User Levels, Scripting
992 @section Sending Messages
994 There are several types of messages you can send with Bobot++ from
995 scripts. There is the simple, but rather limited, @code{bot:say},
996 @code{bot:action} and @code{bot:msg}, and the more powerful, but lower
997 level, @code{bot:send-MESSAGE} functions. Most bots will probably only
998 need the higher level functions, but for the sake of why-not Bobot++
999 lets you use the lower level functions (in progress).
1002 * High Level Message Functions::
1003 * Low Level Message Functions::
1006 @node High Level Message Functions, Low Level Message Functions, Sending Messages, Sending Messages
1007 @subsection ``High Level'' Message Functions
1009 @defun bot:say channel message
1010 Send a public or private @var{message} to @var{channel}.
1012 Sends a normal text message, as if a user had typed it in. The
1013 @var{dest} can be a nickname or a channel.
1016 @defun bot:action channel message
1017 Send an ``action'' type @var{message} to @var{channel}
1020 @defun bot:msg nick message
1021 The same as if a user typed @code{/msg nick message} to their IRC client.
1024 @defun bot:notice target message
1025 Sends @var{message} as a NOTICE to @var{target}. @var{target} may be a
1026 user (nick) or a channel. This returns 0 on success.
1029 @node Low Level Message Functions, , High Level Message Functions, Sending Messages
1030 @subsection ``Low Level'' Message Functions
1032 @c Add a url for rfc2812
1033 The ``Low Level'' messaging functions allow you to do things like send
1034 CTCP messages. You probably want to read rfc 2812 and the CTCP spec
1035 before using these. If you have no idea what these do, read rfc 2812
1036 (IRC Client Protocol) and CTCP spec. These functions all return
1037 @code{*unspecified*} always, so don't use the return value for
1040 @defun bot:send-ctcp to command message
1041 @var{to} is the target of your CTCP message, @var{command} is the
1042 CTCP command, and @var{message} is the message (or arguments) of the
1043 command. Make sure to @code{bot:ctcp-quote} the message!
1046 @defun bot:send-ctcp-reply to command message
1047 @var{to} is the target of your CTCP reply, @var{command} is the
1048 CTCP command, and @var{message} is the message (or arguments) of the
1049 command. Make sure to @code{bot:ctcp-quote} the message!
1051 This is used to reply to a ctcp that the bot has received.
1054 @node Misc Scripting Stuff, , Sending Messages, Scripting
1055 @section Misc. Scripting Stuff
1057 These are a few useful things that I thought people writing scripts
1061 If you want to execute code when the bot exits, just do
1062 @code{add-hook! bot:exit-hook @var{thunk}} where @var{thunk} is an
1063 argumentless procedure (a thunk). When the bot exits your thunk will
1067 [ I didn't know where to put any of these, so I just stuck them in
1070 There probably needs to be several sections added, like dealing with
1071 users (kicking, added, etc), dealing with the bot (channels, nickname
1072 of the bot, etc), server issues (serverlist), useful tools (nslookup,
1073 whois), and do on. ]
1077 @defun bot:adduser nick-or-mask cbannel-mask level prot auto-op
1078 Adds an user to the userlist, for a @code{nick!user@@host} matching the
1079 one given, on a channel matching the @var{channelMask} given.
1081 @multitable @columnfractions 0.33 0.33 0.33
1082 @item The @var{level} can be: @tab The @var{prot} can be: @tab The @var{auto-op} can be:
1083 @item 0 - No level @tab 0 - No protection @tab 0 - No auto-op
1084 @item 1 - User @tab 1 - No ban @tab 1 - Op on join
1085 @item 2 - Trusted User @tab 2 - No kick @tab
1086 @item 3 - Friend @tab 3 - No deop @tab
1087 @item 4 - Master @tab @tab
1093 @defun bot:addserver hostname ip-address [portnumber]
1094 Adds the server specified by @var{hostname} or @var{ip-address} to
1099 @defun bot:addshit nick-or-mask channel-mask level [time reason]
1100 Adds an user to the shitlist, for a nick!user@@host matching the
1101 one given, on a channel matching the @var{channelMask} given.
1104 The @var{level} can be:
1107 2 - Kick and Ban on join
1108 3 - Kick and Ban on join, no deban
1114 @defun bot:ban channel mask-or-nick
1115 Bans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
1116 user to ban with a @var{mask}.
1120 @defun bot:change-command-level nick-or-mask channel-mask new-level
1121 Gives @var{nick} or @var{mask} level @var{new-level} on channel(s)
1122 @var{channel-mask}. Note that you can not change level for someone
1123 whose level is greater than yours, and that you can not give a
1124 level greater than yours.
1128 @defun bot:cycle channel
1129 Makes the bot leave and join @var{channel}.
1133 @defun bot:deban channel mask-or-nick
1134 Debans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
1135 user to deban with a @var{mask}.
1139 @defun bot:delserver server-number
1140 Deletes server from server list whose number in the server list
1141 is @var{server-number}
1145 @defun bot:deluser nick-or-mask channel-mask
1146 Removes @var{nick} or @var{mask} from the userlist.
1150 @defun bot:delshit nick-or-mask channel-mask
1151 Removes @var{nick} or @var{mask} from the shitlist.
1155 @defun bot:deop channel mask-or-nick
1156 Deops @var{mask} or @var{nick} on @var{channel}.
1160 @defun bot:die reason
1161 Makes the bot stop immediately.
1169 @defun bot:invite channel nick
1170 Invites @var{nick} on @var{channel}.
1174 @defun bot:join channel
1175 Makes the bot join @var{channel}.
1179 @defun bot:keep channel modes
1180 Sets the @var{modes} that the bot will keep for @var{channel}.
1185 @defun bot:kick channel mask-or-nick [reason]
1186 Kicks @var{mask} or @var{nick} out of @var{channel}, because of @var{reason}.
1187 You need to be a trusted user to use a @var{mask}.
1191 @defun bot:kickban channel mask-or-nick [reason]
1192 Bans then kicks @var{mask} or @var{nick} out of @var{channel},
1193 because of @var{reason}.
1194 You need to be a trusted user to use a @var{mask}.
1198 @defun bot:lock channel
1199 Locks topic on @var{channel}.
1204 [ Probably returns the log port? ]
1208 @defun bot:mode channel mode-string
1209 Sends @var{mode-string} as mode for @var{channel}.
1213 @defun bot:nextserver
1214 Makes the bot connect to the next server in its server list.
1218 @defun bot:nick nick
1219 Makes the bot use nickname @var{nick}.
1223 @defun bot:op channel nick
1224 Ops @var{nick} on @var{channel}.
1228 @defun bot:part channel
1229 Makes the bot leave @var{channel}.
1233 @defun bot:reconnect
1234 Makes the bot reconnect to its current server.
1238 @defun bot:server server-number
1239 Select the server to connect to. @var{server-number} is the number of
1240 the server in the serverlist.
1244 @defun bot:setfloodrate ?
1248 @defun bot:setversion ?
1252 @defun bot:tban channel nick-or-mask time
1253 Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds.
1257 @defun bot:tkban channel nick-or-mask time [reason]
1258 Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds,
1259 then kicks him/them because of @var{reason}.
1263 @defun bot:topic channel topic
1264 If no @var{topic} is given, prints @var{channel}'s topic. Otherwise,
1265 the bot will change @var{channel}'s topic to @var{topic}.
1268 @defun bot:unlock channel
1269 Makes the bot unlock topic on @var{channel}.
1273 @defun bot:getnickname
1274 [ Gets the bot's nickname? ]
1278 @defun bot:getserver
1282 @defun bot:getserverlist
1287 [ Flushes the socket to the server? ]
1291 @defun bot:flushport
1292 [ Flushes the log port? ]
1297 [ Returns a random number? What range? Why? ]
1301 @defun bot:delcommand
1302 [ Probably deletes a command added with @code{bot:addcommand} ? ]
1306 @defun bot:addtimer ? ?
1310 @defun bot:deltimer ?
1314 @defun bot:dcc-chat-send ? ?
1318 [ And what about the stuff defined in @file{bobot-utils.scm} ? I just
1319 added it here so it could be somewhere. There should also be a
1320 section dealing with modules. How to use them. What module scripts
1321 are in. What module bobot++ provided primites are in. And so on. ]
1324 @defun bot:log . messages
1325 Write as many @var{messages} as you want to the log. If the arg is a
1326 thunk it will be executed and it's output will be written to the log.
1329 @defun bot:load file
1332 @defun bot:load-module module-spec
1335 @defun bot:use-module module-spec
1338 @defun bot:match-not-channel regex
1339 match-not-channel adds a prefix regex to your @var{regex} so it
1340 doesn't match the sender or channel in a PUBLIC message
1343 @defun bot:match-to-me regex
1344 match-to-me matches text that was addressed to the bot with a
1345 ':', ',', or nothing after the bot name.
1348 @defun bot:sent-to-me? message
1351 @defun bot:ctcp-quote message
1352 Returns the CTCP quoted message
1353 Input @emph{MUST NOT} contain the trailing @code{\r\n}
1354 (it is added by the message sending code).
1358 @defvar %bot:loadpath
1361 @defun %bot:load-extensions
1366 @node Concept Index, Function Index, Scripting, Top
1367 @unnumbered Concept Index
1370 @node Function Index, Variable Index, Concept Index, Top
1371 @unnumbered Function Index
1374 @node Variable Index, , Function Index, Top
1375 @unnumbered Variable Index