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 (original author, no longer works on 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 (original author, no longer works on 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.
133 * Configuration File Placement::
134 * Configuration Files::
137 @node Configuration File Placement, Configuration Files, Configuration, Configuration
138 @section Configuration File Placement
140 Bobot++ will look in @file{/etc/bobotpp/default/} for its default
141 config if none is specified on the command line. Put the configuration
142 files you want to be loaded by default in this directory. If you are
143 not root or you want to have your own personal configuration, put it
144 in @file{~/.bobotpp/config/default/}.
146 @node Configuration Files, , Configuration File Placement, Configuration
147 @section Configuration Files
154 @node bot.conf, bot.users, Configuration Files, Configuration Files
162 @file{bot.conf} contains key value pairs separated by @code{=}.
164 @code{<key> = <value>}
166 Comments are started with a @code{#} and cause the entire line to be
167 ignored. @emph{Note that this only works when the @code{#} is the first
168 character of the line}.
170 bot.conf is the main configuration file for a Bobot++. The available
171 configuration variables are listed below in the format ``@var{variable}
172 <default-value>: description''
176 @item @var{nickname} <Bobot>: The nickname of the bot (@var{nick} is an
177 alias for @var{nickname})
178 @item @var{username} <bobot>: The IRC username of the bot
179 @item @var{cmdchar} <!>: The character that prefixes commands given to
180 the bot (@var{command} is an alias for @var{cmdchar})
181 @item @var{ircname} <I'm a bobot++!>: The IRC name (or 'real name') of
182 the bot (@var{realname} is an alias for @var{ircname})
183 @item @var{userlist} <bot.users>: Name of the file where the userlist is
185 @item @var{shitlist} <bot.shit>: Name of the file where the shitlist is
187 @item @var{logfile} <$LOGDIR/bot.log>: Location of the bot logfile
188 (set this to @file{/dev/null} to disable logging).
189 @item @var{server} <None>: This specifies the server to connect
190 to. Note that this has a special syntax.
191 @item @var{channel} <None>: This specifies a channel the bot will join
192 when it starts up. This also has a special syntax.
196 @node server syntax, channel syntax, bot.conf, bot.conf
197 @subsubsection server syntax
199 @var{server} = @var{server_name} [@var{port} [@var{password}]]
201 This will make Bobot++ attempt to connect to @var{server_name} on port
202 @var{port} with the password @var{password}. @var{server_name} should
203 be the address of the server. @var{port} and @var{password} are
204 optional. You may use more than one server line; Bobot++ will attempt
205 to connect to the first one and, if it fails, will connect to the next
206 one in the list. There is also a command to cause the bot to cycle
207 servers. At the present time Bobot++ cannot connect to more than one
208 server at a time. This is a planned feature of 3.0 (which is a very
209 long way away; the current structure of the program would make it very
210 difficult to add support for connecting to multiple servers at a time
213 @node channel syntax, , server syntax, bot.conf
214 @subsubsection channel syntax
217 @var{name}:@var{initial_modes}:@var{modes_to_keep}:@var{channel_key}
219 You may have any number of channel lines. When Bobot++ starts it will
220 attempt to join and gain ops in every channel listed. It will join
221 @var{name} and set the channel modes to @var{initial_modes}
222 (e.g. ``nt'') if it is able to gain operator status. It will then
223 maintain @var{modes_to_keep}. If the channel requires a key to enter
224 simply set @var{channel_key}. Every argument except for @var{name} is
229 @code{@var{channel} = #foo:nt:nt:bar}
231 The bot will join @code{#foo} with the channel key @code{bar} and will
232 then maintain the modes @code{nt}.
234 @code{@var{channel} = #bar:::}
236 The bot will join @code{#bar} and will not set any modes nor will it
237 attempt to maintain any modes.
239 @node bot.users, , bot.conf, Configuration Files
240 @subsection bot.users
242 @file{bot.users} is the default file name of the userlist. It may be
243 changed in @file{bot.conf}. The file contains lines with the format:
245 @samp{@var{mask}:@var{channel}:@var{level}:@var{protection}:@var{auto-op}}
249 @item @var{mask} is the host mask
250 (e.g. @samp{*!*username@*.domain.com}) of the user
252 @item @var{channel} is a channel mask of the channels that the user
253 has priviliges to use the bot in (e.g. @samp{*} for all channels,
254 @samp{#*} for all non-local channel, @samp{#foo*} for all channels
255 starting with ``foo,'' @samp{#bar} for channel ``#bar'' only, etc.)
257 @item @var{level} is the user level of the user (@ref{User Levels}).
259 @item @var{protection} is the protection level of the user
262 @item @var{auto-op} is set to control whether a user is automatically
263 given operator priviliges on channel entry (@ref{Automatic Op}).
267 @node Using the Bot, Scripting, Configuration, Top
268 @chapter Using Bobot++
277 * Built-In Commands::
280 @node Starting the Bot, User Levels, Using the Bot, Using the Bot
281 @section Starting the Bot
283 The bot is usually installed with the binary name @file{bobotpp}. It
284 accepts the following command line arguments:
287 @item @code{[--help][-h]} - Shows detailed help and exits
288 @item @code{[--version][-v]} - Shows version information and exits
289 @item @code{[--no-background][-b]} - Run bobot++ in the foreground
290 @item @code{[--config-file file][-f]} - Use file instead of @file{bot.conf}
291 @item @code{[--config-dir dir][-d]} - Use dir as dir to load config file from
292 @item @code{[--config dir][-c]} - Search your config path (defaults to
293 @file{@var{$HOME}/.bobotpp/config/} and then @file{/etc/bobotpp/}) for
294 dir and then loads your config data using dir
295 @item @code{[--sys-config dir][-s]} - Looks for config in
296 @file{/etc/bobotpp/dir}. Note that the user dir is still searched
298 @item @code{[--user-config dir][-u]} - Looks for config in
299 @file{@var{$HOME}/.bobotpp/config/dir/}. Note that the system dir is
300 still searched after this if dir is not found.
301 @item @code{[--debug][-D]} Makes Bobot++ print debugging info and run
303 @item @code{[--debug-scripts][-S]} Enabled the Guile debugging
304 evaluator for verbose script errors and backtraces while still running
305 the bot in the background.
308 The default configuration is read from
309 @file{@var{$HOME}/.bobotpp/config/default/} and then
310 @file{/etc/bobotpp/default/} if the user config is not found.
312 The bot defaults to running in the background as a daemon.
314 @node User Levels, Protection, Starting the Bot, Using the Bot
317 There are several user levels available in Bobot++ to provide gradated
318 access to commands. @command{!adduser} and @file{bot.users} use the
319 numeric code; Scheme uses the textual name for the level. By default
320 (if no catch-all setting is found in @xref{bot.users}.) a user has
321 access to commands with the level @code{bot:user-none}.
325 @item @code{bot:user-none} - No @strong{built-in} commands may be
326 executed @emph{by default} (commands may be added from Scheme that can
327 be executed by users of level none and the level required to execute a
328 command may be changed from Scheme).
330 @item @code{bot:user-user} - Will be able to execute most commands but
331 not all and cannot use masks on kicks and bans.
333 @item @code{bot:user-trusted} - For built-ins with a default
334 configuration this user has access to the same set of commands as an
335 @code{user} but may use masks on kicks and bans. Scheme commands may
336 be added which require a user to be of this level.
338 @item @code{bot:user-friend} - In the default configuration a user who
339 is a friend will be able to do everything short of stopping the
340 bot. Again, there may be user added commands that require a higher
343 @item @code{bot:user-master} - This is the highest user level and has
344 access to every feature of the bot.
348 @node Protection, Automatic Op, User Levels, Using the Bot
351 A user added via Scheme, the @file{bot.users} file, or
352 @command{!adduser} may be protected from being deoped, kicked, or
353 banned. There are currently no symbolic levels in Scheme; just use the
358 @item No ban. If a user is banned the bot will unban him..
359 @item No kick. The user may still be kicked but the bot will kickban
360 the user who kicked the protected user.
361 @item No deop. The bot will ensure that the user always maintains
365 @node Automatic Op, Built-In Commands, Protection, Using the Bot
366 @section Automatic Op
368 A user may be automatically given operator status upon entering a
369 channel. Set the @var{aop} field to ``0'' to disable auto-op or ``1''
372 @node Built-In Commands, , Automatic Op, Using the Bot
373 @section Built-In Commands
375 Bobot++ has many built-in commands that make it useful without
376 scripting support. The reference leaves off the command char; remember
377 to use whatever you defined the command char to be in
378 @file{bot.conf}. If a command needs the channel name then you must
379 specify the channel as the first argument to the command when private
380 messaging the bot a command.
382 @multitable @columnfractions 0.20 0.15 0.15 0.50
383 @item @sc{command} @tab @sc{Needs Channel} @tab @sc{Min Level to Use} @tab @sc{Description}
385 @item @command{action} @option{do} @tab Yes @tab @var{USER} @tab
386 Causes the bot to perform the action @option{do} in the current
389 @item @command{adduser} @tab @tab @tab
391 @item @command{addserver} @tab @tab @tab Adds the server specified by
392 @var{host name} or @var{ip address} to the server list.
394 @item @command{addshit} @tab @tab @tab
396 @item @command{alias} @tab @tab @tab Makes an alias, and adds the
397 function @var{new name}, that will do exactly the same command as
400 @item @command{ban} @tab @tab @tab Bans @var{mask} or @var{nick} from
401 @var{channel}. You need to be a trusted user to ban with a
404 @item @command{banlist} @tab @tab @tab
406 @item @command{channels} @tab @tab @tab Prints the channel(s) where
407 the bot is currently.
409 @item @command{cycle} @tab Yes @tab @tab Makes the bot leave and join
412 @item @command{dcclist} @tab @tab @tab Gives the list of all DCC Chat
415 @item @command{deban} @tab Yes @tab @tab Debans @var{mask} or
416 @var{nick} from @var{channel}. You need to be a trusted user to deban
419 @item @command{delserver} @tab @tab @tab Deletes server from server
420 list whose number in the server list is @var{server number}.
422 @item @command{deluser} @tab @tab @tab Removes @var{nick} or
423 @var{mask} from the userlist.
425 @item @command{delshit} @tab @tab @tab Removes @var{nick} or
426 @var{mask} from the shitlist.
428 @item @command{deop} @tab Yes @tab @tab Deops @var{mask} or @var{nick}
431 @item @command{die} @tab @tab @tab Makes the bot stop immediately.
433 @item @command{do} @tab @tab @tab
435 @item @command{execute} @tab @tab @tab @strong{Only available if
436 scripting support is enabled}
438 @item @command{help} @tab @tab @tab
440 @item @command{ident} @tab @tab @tab Identifies you on the bot. Note
441 that you should not use this command in public @dots{}
443 @item @command{invite} @tab Yes @tab @tab Invites @var{nick} on
446 @item @command{join} @tab @tab @tab Makes the bot join @var{channel}.
448 @item @command{keep} @tab Yes @tab @tab Sets the @var{modes} that the
449 bot will keep for @var{channel}.
451 @item @command{kick} @tab Yes @tab @tab Kicks @var{mask} or @var{nick}
452 out of @var{channel}, because of @var{reason}. You need to be a
453 trusted user to use a @var{mask}.
455 @item @command{kickban} @tab Yes @tab @tab Bans then kicks @var{mask}
456 or @var{nick} out of @var{channel}, because of @var{reason}. You need
457 to be a trusted user to use a @var{mask}.
459 @item @command{load} @tab @tab @tab Reloads the userlist from disk.
461 @item @command{loadscript} @tab @tab @tab @strong{Only available if
462 scripting support is enabled}
464 @item @command{lock} @tab @tab @tab Locks topic on @var{channel}.
466 @item @command{mode} @tab Yes @tab @tab Sends @var{mode string} as
467 mode for @var{channel}.
469 @item @command{msg} @tab @tab @tab
471 @item @command{names} @tab Yes @tab @tab Shows the nicknames and
472 status of users on @var{channel}.
474 @item @command{nextserver} @tab @tab @tab Makes the bot connect to the
475 next server in its server list.
477 @item @command{nick} @tab @tab @tab Makes the bot use nickname @var{nick}.
479 @item @command{nslookup} @tab @tab @tab Does a nameserver query about
480 @var{nick} host, @var{host} or @var{ip address}.
482 @item @command{op} @tab Yes @tab @tab Ops @var{nick} on @var{channel}.
484 @item @command{part} @tab Yes @tab @tab Makes the bot leave @var{channel}.
486 @item @command{password} @tab @tab @tab Changes your password on the
487 bot. Use @code{NONE} as password if you want to clear it. Do not use this
490 @item @command{reconnect} @tab @tab @tab Makes the bot reconnect to
493 @item @command{rspymessage} @tab @tab @tab Removes you from the spy
496 @item @command{save} @tab @tab @tab Saves the userlist.
498 @item @command{say} @tab Yes @tab @tab Makes the bot say @var{message}
501 @item @command{server} @tab @tab @tab Select the server to connect
502 to. @var{server number} is the number of the server in the serverlist.
504 @item @command{serverlist} @tab @tab @tab Shows the bot's serverlist.
506 @item @command{setfloodrate} @tab @tab @tab
508 @item @command{setversion} @tab @tab @tab
510 @item @command{shitlist} @tab @tab @tab Shows the bot's shitlist.
512 @item @command{spylist} @tab @tab @tab Shows the bot's spylist.
514 @item @command{spymessage} @tab @tab @tab Adds you to the spylist
516 @item @command{stats} @tab Yes @tab @tab Gives @var{channel}'s statistics.
518 @item @command{tban} @tab Yes @tab @tab Bans @var{nick} or @var{mask}
519 from @var{channel} for @var{time} seconds.
521 @item @command{tkban} @tab Yes @tab @tab Bans @var{nick} or @var{mask}
522 from @var{channel} for @var{time} seconds, then kicks him/them because
525 @item @command{topic} @tab Yes @tab @tab If no @var{topic}is given,
526 prints @var{channel}'s topic. Otherwise, the bot will change
527 @var{channel}'s topic to @var{topic}.
529 @item @command{unlock} @tab Yes @tab @tab Makes the bot unlock topic
532 @item @command{userlist} @tab @tab @tab Shows the bot's userlist
534 @item @command{who} @tab Yes @tab @tab Show your level on @var{channel}
536 @item @command{whois} @tab Yes @tab @tab Shows information about
537 @var{nick} on @var{channel}
541 @node Scripting, Concept Index, Using the Bot, Top
544 Bobot++'s most powerful feature is its scripting system. You write
545 scripts using Guile Scheme. This manual does not cover how to use
546 Guile or how to learn Scheme. @xref{Top, , Guile Reference Manual,
547 guile, The Guile Reference Manual}, for the Guile reference manual and
548 @url{http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html} for
549 a good tutorial on Scheme.
551 Note that in previous versions the scripting commands where in the
552 form @code{bot-@var{function}}. They are now in the form
553 @code{bot:@var{function}}. The old names are still available, but are
554 deprecated and will be removed in Bobot++ 3.0. New commands are only
555 available with the @code{bot:} prefix. The command @command{perl -pi
556 -e ``s/bot-/bot:/g'' @var{your-files}} should be enough to convert
557 your code to use the new functions.
559 @strong{NOTE}: All arguments to functions and hooks called by the bot
560 are strings unless otherwise specified.
563 * Adding New Commands::
565 * Scheme User Levels::
567 * Misc Scripting Stuff::
570 @node Adding New Commands, Hooks, Scripting, Scripting
571 @section Adding New Commands
573 Adding a new command is simple. To register a new command use
574 @code{bot:addcommand}.
576 @defun bot:addcommand name func needs-channel? num-of-args min-level
578 The @var{name} is a string representing the name of the command being
579 added. @var{func} is a function accepting @var{num-of-args}
580 arguments. @var{needs-channel?} is a bool that is true if the function
581 needs the channel name as its first arg, and false otherwise.
582 @var{num-of-args} is the number of args @var{func} will take and must
583 be within zero (0) and twenty (20). @var{min-level} is one of the
584 @ref{Scheme User Levels}. A user must be at least a @code{min-level}
585 user to use the new command. None of the arguments are guaranteed to
586 be passed; if they aren't they are set to the empty string @code{""}.
587 An example of a new command would be:
590 (define (hello channel name)
591 (if (string=? name "")
592 (bot:say channel "Hello world!")
593 (bot:say channel (string-append "Hello " name "!")))
595 (bot:addcommand "hello" hello #t 2 0)
598 This will display ``Hello World!'' if called as @kbd{!hello} and
599 ``Hello World @var{USER}'' if called as @kbd{!hello @var{USER}}.
602 @node Hooks, Scheme User Levels, Adding New Commands, Scripting
605 @cindex Background on Hooks
606 Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
607 and tiny fugue (a MUD bot) hooks with a little bit of extra stuff
608 added in. A hook is called when a regular expression is matched
609 against a message sent to or by the bot.
611 Bobot++ uses different hook types for each IRC message type, and also
612 includes a hook for accessing raw irc messages. Hooks are tagged with
613 a priority and a flag that specifies whether to call the next hook
614 that matches after calling the current one or to stop
617 Hooks are processed from the highest to lowest priority, with
618 fallthrough hooks of equal priority to non-fallthrough hooks being
626 @node Creating a Hook, Hook Types, Hooks, Hooks
627 @subsection Creating a Hook
629 To add a new hook you use the function @code{bot:addhook}.
631 @defun bot:addhook type regex function [pri fall name]
632 @var{type} specifies the type of hook (the types of hooks are listed
633 in @ref{Hook Types}).
635 @var{regex} is a standard regular expression. If
636 @var{regex} is matched, @var{function} will be called.
638 @var{function} will take a different number of args depending on the
641 @var{pri} specifies the priority of the hook---higher priority hooks
642 are executed first. This argument is optional and defaults to
645 @var{fall} is @code{#t} if the hook is a fallthrough hook and
646 @code{#f} is the hook is not a fallthrough hook. This arg is also
647 optional and defaults to @code{#t}.
649 @var{name} is the optional name of the hook that defaults to
650 @code{"DEFAULT"}. If you set the name then you can have more than
651 one hook that matches the same regexp, as long as they have the same
652 name. E.g. in a log script you could have the regexps for the log
653 function all be @code{".*"} and set their names to @code{"log"} to
654 avoid a conflict with other hooks.
657 @node Hook Types, , Creating a Hook, Hooks
658 @subsection Hook Types
660 The following sections document the different hooks Bobot++ exposes.
662 The general format of each hook description is as if it were a
663 function to be defined, but these describe the function to be passwd
664 to @code{bot:add-hook}. Do @emph{not} name your functions these
667 That said, here is the list of available hooks functions.
671 * Received Message Hooks::
672 * Sent Message Hooks::
674 * Miscellaneous Hooks::
677 @node Received Message Hooks, Sent Message Hooks, Hook Types, Hook Types
678 @subsubsection Receieved Message Hooks
680 The following hooks are triggered when a mesage is received by the bot.
682 @defun hooks/action from to action
683 This hook is triggered when someone performs an action.
685 @var{from} is the nickname the person that performed the
688 @var{to} is the target of the action, which is either a channel or the
689 Bot's nick if the user private messages the bot.
691 @var{action} is the text of the action. E.g. if someone did @samp{*
692 foobar does baz}, then @var{action} would be the string @code{"does
696 @defun hooks/nickname old-nick new-nick
697 This hook is called when someone changes his nickname from
698 @var{old-nick} to @var{new-nick}.
701 @defun hooks/signoff nick message
702 This hook is called when someone signs off of IRC.
704 @var{nick} is the nickname of the person signing off.
706 @var{message} is his quit message
709 @defun hooks/ctcp nick to command rest
710 This hook is called when a CTCP request is received by the bot.
712 @var{nick} is the nickname of the sender.
714 @var{to} is the target of the CTCP request. This will either be a
715 channel the bot is in, or the nickname of the bot.
717 @var{command} is the CTCP command issued.
719 @var{rest} contains the arguments to the CTCP command.
722 @defun hooks/ctcp-reply nick command rest
723 This hook is called when a CTCP REPLY is received. This occurs when
724 the bot has sent a CTCP request to another client. The CTCP REPLY is
725 always addressed to the bot directly.
727 @var{nick} is the nickname of the person who replied.
729 @var{command} is the command to which @var{nick} is replying.
731 @var{rest} contains the body of the reply.
734 @defun hooks/disconnect server intentional
735 This is called when the bot is disconnected from a server.
737 @var{server} is the hostname of the server from which the bot was
740 @var{intentional} is a flag set to @code{#t} when the bot disonnected
741 from the server as the result of a command (issued by a user from IRC,
742 SIGHUP, or from a script), or @code{#f} when the bot disconnected from
743 the server unintentionally..
746 @defun hooks/invite nick channel
747 This hook is called when a user invited the bot to join a channel.
749 @var{nick} is the nickname of the user who sent the invite.
751 @var{channel} is the channel to which the bot was invited.
754 @defun hooks/join nick channel
755 This is called when a user or the bot joins a channel.
757 @var{nick} is the nickname of the user who joined @var{channel}. This
758 may be the bot's nickname (the IRC server sends the JOIN command back
759 to the the bot after it joins a channel).
761 @var{channel} is the channel that was joined
764 @defun hooks/kick target from channel reason
765 This hook is called when a user, including the bot, is kicked out of a
768 @var{target} is the nick of the user who was kicked. This may be the
771 @var{from} is the nick of the user who issued the kick. This may also
774 @var{channel} is the channel the kick was issued in.
776 @var{reason} is the reason the user was kicked.
779 @defun hooks/part nick channel
780 This hook is called when a user parts a channel.
782 @var{nick} is the user who parted the channel. This may be the bot.
784 @var{channel} is the channel from which the user parted.
787 @defun hooks/mode nick target modes
788 This hook is called when someone sets the modes of @var{target}.
790 @var{nick} is the user who set the modes. This may be the bot.
792 @var{target} is the target of the MODE command. This may be a
793 channel or a user. If it is a user, it may be the bot.
795 @var{modes} is the MODE string.
798 @defun hooks/message nick message
799 This hook is called when someone sends a private message to the bot.
801 @var{nick} is the nickname of the user who sent the message.
803 @var{message} is the message the user sent.
806 @defun hooks/notice nick message
807 This hook is called when a user send a private notice to the bot.
809 @var{nick} is the user who sent the notice.
811 @var{message} is the message the user sent.
814 @defun hooks/public nick channel message
815 This hook is called when a user sends a normal message to a channel.
817 @var{nick} is the user who sent the message.
819 @var{channel} is the channel to which the message was sent.
821 @var{message} is the message that was sent.
824 @defun hooks/public-notice nick channel message
825 This hook is called when a user send a notice to a channel.
827 @var{nick} is the user who sent the notice.
829 @var{channel} is the channel to which the notice was sent.
831 @var{message} is the message that was sent.
834 @defun hooks/raw raw-message
835 This hook is called every time a message is received. This matches on
836 the raw message text and passes the hook function the raw IRC message.
838 @var{raw-message} is the raw IRC message.
841 @defun hooks/topic nick channel new-topic
842 This hook is called when a user changes the topic in a channel.
844 @var{nick} is the user who set the topic. This may be the bot.
846 @var{channel} is the channel that's topic was changed.
848 @var{new-topic} is the new topic.
851 @node Sent Message Hooks, DCC CHAT Hooks, Received Message Hooks, Hook Types
852 @subsubsection Sent Message Hooks
854 These hooks are called when the bot sends a message. @var{mynick} is
855 always the bot's nick and will not be documented in each hook
858 @defun hooks/send/public mynick channel message
859 This hook is called when the bot sends a normal message to a channel.
861 @var{channel} is the channel to which the bot sent the message.
863 @var{message} is the message the bot sent.
866 @defun hooks/send/message mynick to message
867 This hook is called when the bot sends a private message to a user.
869 @var{to} is the nick of the user to whom the message was sent.
871 @var{message} is the message that was sent.
874 @defun hooks/send/action mynick to message
875 This hook is called when the bot sents an action to a channel or a
878 @var{to} is the channel or nick of the user to which the action was
881 @var{message} is the text of the action.
884 @defun hooks/send/ctcp mynick to command message
885 This hook is called when the bot sends a CTCP message @emph{other
886 than} an ACTION to a channel or user.
888 @var{to} is the channel or nick of the user to which the CTCP was
891 @var{command} is the CTCP command that was sent.
893 @var{message} is a string containing the arguments to the CTCP command.
896 @node DCC CHAT Hooks, Miscellaneous Hooks, Sent Message Hooks, Hook Types
897 @subsubsection DCC CHAT Hooks
899 These hooks are called when a user initializes a DCC CHAT and when the
900 bot receives messages from the user in a DCC CHAT.
902 @defun hooks/dcc/chat-begin from
903 This hook is called when a user begins a DCC CHAT with the bot.
904 @var{from} is the user's address in the form @samp{nick!user@@host}.
907 @defun hooks/dcc/chat-message from message
908 This hook is called when a user sends a message to the bot through
911 @var{from} is the user's address in the form @samp{nick!user@@host}.
913 @var{message} is the message the user sent to the bot.
916 @node Miscellaneous Hooks, , DCC CHAT Hooks, Hook Types
917 @subsubsection Miscellaneous Hooks
919 @defun hooks/flood nick
920 This hook is called when a user is detected flooding the bot.
922 @var{nick} is the nickname of the user flooding the bot.
925 @defun hooks/timer time
926 This hook is called once a minute. The regex is @strong{not} used.
928 @var{time} is the in zero-padded @code{hh:mm} format.
931 @node Scheme User Levels, Sending Messages, Hooks, Scripting
932 @section Scheme User Levels
939 There are five levels that a user may be when interfacing with a bot:
940 @var{none}, @var{user}, @var{trusted_user}, @var{friend},
941 @var{master}. The Scheme variables for the user levels are
942 @code{bot:user-none}, @code{bot:user-user}, @code{bot:user-trusted},
943 @code{bot:user-friend}, and @code{bot:user-master}. See @ref{User
944 Levels} for more information on User Levels.
946 When adding a new command, think about who should be able to use
947 it. Is your command a general purpose command that helps the channel
948 (e.g. @code{!seen}) that everyone should be able to use? Or is it
949 something that should be restricted? See @ref{User Levels} for
950 information on what level users can do what with the built in bot
951 commands and think about what level a user your command is targetted
952 towards. You must be @emph{very} careful when giving new commands to
953 lower level users because you can do basically everything the bot can
954 do with a script. As the scripting interface becomes more powerful,
955 you must think more about what users can use new commands you add.
957 @node Sending Messages, Misc Scripting Stuff, Scheme User Levels, Scripting
958 @section Sending Messages
960 There are several types of messages you can send with Bobot++ from
961 scripts. There is the simple, but rather limited, @code{bot:say},
962 @code{bot:action} and @code{bot:msg}, and the more powerful, but lower
963 level, @code{bot:send-MESSAGE} functions. Most bots will probably only
964 need the higher level functions, but for the sake of why-not Bobot++
965 lets you use the lower level functions (in progress).
968 * High Level Message Functions::
969 * Low Level Message Functions::
972 @node High Level Message Functions, Low Level Message Functions, Sending Messages, Sending Messages
973 @subsection ``High Level'' Message Functions
975 @defun bot:say channel message
976 Send a public or private @var{message} to @var{channel}.
978 Sends a normal text message, as if a user had typed it in. The
979 @var{dest} can be a nickname or a channel.
982 @defun bot:action channel message
983 Send an ``action'' type @var{message} to @var{channel}
986 @defun bot:msg nick message
987 The same as if a user typed @code{/msg nick message} to their IRC client.
990 @defun bot:notice target message
991 Sends @var{message} as a NOTICE to @var{target}. @var{target} may be a
992 user (nick) or a channel. This returns 0 on success.
995 @node Low Level Message Functions, , High Level Message Functions, Sending Messages
996 @subsection ``Low Level'' Message Functions
998 @c Add a url for rfc2812
999 The ``Low Level'' messaging functions allow you to do things like send
1000 CTCP messages. You probably want to read rfc 2812 and the CTCP spec
1001 before using these. If you have no idea what these do, read rfc 2812
1002 (IRC Client Protocol) and CTCP spec. These functions all return
1003 @code{*unspecified*} always, so don't use the return value for
1006 @defun bot:send-ctcp to command message
1007 @var{to} is the target of your CTCP message, @var{command} is the
1008 CTCP command, and @var{message} is the message (or arguments) of the
1009 command. Make sure to @code{bot:ctcp-quote} the message!
1012 @defun bot:send-ctcp-reply to command message
1013 @var{to} is the target of your CTCP reply, @var{command} is the
1014 CTCP command, and @var{message} is the message (or arguments) of the
1015 command. Make sure to @code{bot:ctcp-quote} the message!
1017 This is used to reply to a ctcp that the bot has received.
1020 @node Misc Scripting Stuff, , Sending Messages, Scripting
1021 @section Misc. Scripting Stuff
1023 These are a few useful things that I thought people writing scripts
1027 If you want to execute code when the bot exits, just do
1028 @code{add-hook! bot:exit-hook @var{thunk}} where @var{thunk} is an
1029 argumentless procedure (a thunk). When the bot exits your thunk will
1033 [ I didn't know where to put any of these, so I just stuck them in
1036 There probably needs to be several sections added, like dealing with
1037 users (kicking, added, etc), dealing with the bot (channels, nickname
1038 of the bot, etc), server issues (serverlist), useful tools (nslookup,
1039 whois), and do on. ]
1043 @defun bot:adduser nick-or-mask cbannel-mask level prot auto-op
1044 Adds an user to the userlist, for a @code{nick!user@@host} matching the
1045 one given, on a channel matching the @var{channelMask} given.
1047 @multitable @columnfractions 0.33 0.33 0.33
1048 @item The @var{level} can be: @tab The @var{prot} can be: @tab The @var{auto-op} can be:
1049 @item 0 - No level @tab 0 - No protection @tab 0 - No auto-op
1050 @item 1 - User @tab 1 - No ban @tab 1 - Op on join
1051 @item 2 - Trusted User @tab 2 - No kick @tab
1052 @item 3 - Friend @tab 3 - No deop @tab
1053 @item 4 - Master @tab @tab
1059 @defun bot:addserver hostname ip-address [portnumber]
1060 Adds the server specified by @var{hostname} or @var{ip-address} to
1065 @defun bot:addshit nick-or-mask channel-mask level [time reason]
1066 Adds an user to the shitlist, for a nick!user@@host matching the
1067 one given, on a channel matching the @var{channelMask} given.
1070 The @var{level} can be:
1073 2 - Kick and Ban on join
1074 3 - Kick and Ban on join, no deban
1080 @defun bot:ban channel mask-or-nick
1081 Bans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
1082 user to ban with a @var{mask}.
1086 @defun bot:change-command-level nick-or-mask channel-mask new-level
1087 Gives @var{nick} or @var{mask} level @var{new-level} on channel(s)
1088 @var{channel-mask}. Note that you can not change level for someone
1089 whose level is greater than yours, and that you can not give a
1090 level greater than yours.
1094 @defun bot:cycle channel
1095 Makes the bot leave and join @var{channel}.
1099 @defun bot:deban channel mask-or-nick
1100 Debans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
1101 user to deban with a @var{mask}.
1105 @defun bot:delserver server-number
1106 Deletes server from server list whose number in the server list
1107 is @var{server-number}
1111 @defun bot:deluser nick-or-mask channel-mask
1112 Removes @var{nick} or @var{mask} from the userlist.
1116 @defun bot:delshit nick-or-mask channel-mask
1117 Removes @var{nick} or @var{mask} from the shitlist.
1121 @defun bot:deop channel mask-or-nick
1122 Deops @var{mask} or @var{nick} on @var{channel}.
1126 @defun bot:die reason
1127 Makes the bot stop immediately.
1135 @defun bot:invite channel nick
1136 Invites @var{nick} on @var{channel}.
1140 @defun bot:join channel
1141 Makes the bot join @var{channel}.
1145 @defun bot:keep channel modes
1146 Sets the @var{modes} that the bot will keep for @var{channel}.
1151 @defun bot:kick channel mask-or-nick [reason]
1152 Kicks @var{mask} or @var{nick} out of @var{channel}, because of @var{reason}.
1153 You need to be a trusted user to use a @var{mask}.
1157 @defun bot:kickban channel mask-or-nick [reason]
1158 Bans then kicks @var{mask} or @var{nick} out of @var{channel},
1159 because of @var{reason}.
1160 You need to be a trusted user to use a @var{mask}.
1164 @defun bot:lock channel
1165 Locks topic on @var{channel}.
1170 [ Probably returns the log port? ]
1174 @defun bot:mode channel mode-string
1175 Sends @var{mode-string} as mode for @var{channel}.
1179 @defun bot:nextserver
1180 Makes the bot connect to the next server in its server list.
1184 @defun bot:nick nick
1185 Makes the bot use nickname @var{nick}.
1189 @defun bot:op channel nick
1190 Ops @var{nick} on @var{channel}.
1194 @defun bot:part channel
1195 Makes the bot leave @var{channel}.
1199 @defun bot:reconnect
1200 Makes the bot reconnect to its current server.
1204 @defun bot:server server-number
1205 Select the server to connect to. @var{server-number} is the number of
1206 the server in the serverlist.
1210 @defun bot:setfloodrate ?
1214 @defun bot:setversion ?
1218 @defun bot:tban channel nick-or-mask time
1219 Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds.
1223 @defun bot:tkban channel nick-or-mask time [reason]
1224 Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds,
1225 then kicks him/them because of @var{reason}.
1229 @defun bot:topic channel topic
1230 If no @var{topic} is given, prints @var{channel}'s topic. Otherwise,
1231 the bot will change @var{channel}'s topic to @var{topic}.
1234 @defun bot:unlock channel
1235 Makes the bot unlock topic on @var{channel}.
1239 @defun bot:getnickname
1240 [ Gets the bot's nickname? ]
1244 @defun bot:getserver
1248 @defun bot:getserverlist
1253 [ Flushes the socket to the server? ]
1257 @defun bot:flushport
1258 [ Flushes the log port? ]
1263 [ Returns a random number? What range? Why? ]
1267 @defun bot:delcommand
1268 [ Probably deletes a command added with @code{bot:addcommand} ? ]
1272 @defun bot:addtimer ? ?
1276 @defun bot:deltimer ?
1280 @defun bot:dcc-chat-send ? ?
1284 [ And what about the stuff defined in @file{bobot-utils.scm} ? I just
1285 added it here so it could be somewhere. There should also be a
1286 section dealing with modules. How to use them. What module scripts
1287 are in. What module bobot++ provided primites are in. And so on. ]
1290 @defun bot:log . messages
1291 Write as many @var{messages} as you want to the log. If the arg is a
1292 thunk it will be executed and it's output will be written to the log.
1295 @defun bot:load file
1298 @defun bot:load-module module-spec
1301 @defun bot:use-module module-spec
1304 @defun bot:match-not-channel regex
1305 match-not-channel adds a prefix regex to your @var{regex} so it
1306 doesn't match the sender or channel in a PUBLIC message
1309 @defun bot:match-to-me regex
1310 match-to-me matches text that was addressed to the bot with a
1311 ':', ',', or nothing after the bot name.
1314 @defun bot:sent-to-me? message
1317 @defun bot:ctcp-quote message
1318 Returns the CTCP quoted message
1319 Input @emph{MUST NOT} contain the trailing @code{\r\n}
1320 (it is added by the message sending code).
1324 @defvar %bot:loadpath
1327 @defun %bot:load-extensions
1332 @node Concept Index, Function Index, Scripting, Top
1333 @unnumbered Concept Index
1336 @node Function Index, Variable Index, Concept Index, Top
1337 @unnumbered Function Index
1340 @node Variable Index, , Function Index, Top
1341 @unnumbered Variable Index