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.1.5 of the program named
48 Copyright 2002,2004 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 * High Level Message Functions::
108 * Low Level Message Functions::
113 @node Introduction, Configuration, Top, Top
114 @chapter Introduction
116 This manual feels abused and neglected because it has almost no
119 @node Configuration, Using the Bot, Introduction, Top
120 @chapter Configuration
122 Bobot++ is easy to configure. See the @file{examples} directory for an
123 example configuration.
126 * Configuration File Placement::
127 * Configuration Files::
130 @node Configuration File Placement, Configuration Files, Configuration, Configuration
131 @section Configuration File Placement
133 Bobot++ will look in @file{/etc/bobotpp/default/} for its default
134 config if none is specified on the command line. Put the configuration
135 files you want to be loaded by default in this directory. If you are
136 not root or you want to have your own personal configuration, put it
137 in @file{~/.bobotpp/config/default/}.
139 @node Configuration Files, , Configuration File Placement, Configuration
140 @section Configuration Files
147 @node bot.conf, bot.users, Configuration Files, Configuration Files
155 @file{bot.conf} contains key value pairs separated by @code{=}.
157 @code{<key> = <value>}
159 Comments are started with a @code{#} and cause the entire line to be
160 ignored. @emph{Note that this only works when the @code{#} is the first
161 character of the line}.
163 bot.conf is the main configuration file for a Bobot++. The available
164 configuration variables are listed below in the format ``@var{variable}
165 <default-value>: description''
169 @item @var{nickname} <Bobot>: The nickname of the bot (@var{nick} is an
170 alias for @var{nickname})
171 @item @var{username} <bobot>: The IRC username of the bot
172 @item @var{cmdchar} <!>: The character that prefixes commands given to
173 the bot (@var{command} is an alias for @var{cmdchar})
174 @item @var{ircname} <I'm a bobot++!>: The IRC name (or 'real name') of
175 the bot (@var{realname} is an alias for @var{ircname})
176 @item @var{userlist} <bot.users>: Name of the file where the userlist is
178 @item @var{shitlist} <bot.shit>: Name of the file where the shitlist is
180 @item @var{logfile} <$LOGDIR/bot.log>: Location of the bot logfile
181 (set this to @file{/dev/null} to disable logging).
182 @item @var{server} <None>: This specifies the server to connect
183 to. Note that this has a special syntax.
184 @item @var{channel} <None>: This specifies a channel the bot will join
185 when it starts up. This also has a special syntax.
189 @node server syntax, channel syntax, bot.conf, bot.conf
190 @subsubsection server syntax
192 @var{server} = @var{server_name} [@var{port} [@var{password}]]
194 This will make Bobot++ attempt to connect to @var{server_name} on port
195 @var{port} with the password @var{password}. @var{server_name} should
196 be the address of the server. @var{port} and @var{password} are
197 optional. You may use more than one server line; Bobot++ will attempt
198 to connect to the first one and, if it fails, will connect to the next
199 one in the list. There is also a command to cause the bot to cycle
200 servers. At the present time Bobot++ cannot connect to more than one
201 server at a time. This is a planned feature of 3.0 (which is a very
202 long way away; the current structure of the program would make it very
203 difficult to add support for connecting to multiple servers at a time
206 @node channel syntax, , server syntax, bot.conf
207 @subsubsection channel syntax
210 @var{name}:@var{initial_modes}:@var{modes_to_keep}:@var{channel_key}
212 You may have any number of channel lines. When Bobot++ starts it will
213 attempt to join and gain ops in every channel listed. It will join
214 @var{name} and set the channel modes to @var{initial_modes}
215 (e.g. ``nt'') if it is able to gain operator status. It will then
216 maintain @var{modes_to_keep}. If the channel requires a key to enter
217 simply set @var{channel_key}. Every argument except for @var{name} is
222 @code{@var{channel} = #foo:nt:nt:bar}
224 The bot will join @code{#foo} with the channel key @code{bar} and will
225 then maintain the modes @code{nt}.
227 @code{@var{channel} = #bar:::}
229 The bot will join @code{#bar} and will not set any modes nor will it
230 attempt to maintain any modes.
232 @node bot.users, , bot.conf, Configuration Files
233 @subsection bot.users
235 @file{bot.users} is the default file name of the userlist. It may be
236 changed in @file{bot.conf}. The file contains lines with the format:
238 @samp{@var{mask}:@var{channel}:@var{level}:@var{protection}:@var{auto-op}}
242 @item @var{mask} is the host mask
243 (e.g. @samp{*!*username@*.domain.com}) of the user
245 @item @var{channel} is a channel mask of the channels that the user
246 has priviliges to use the bot in (e.g. @samp{*} for all channels,
247 @samp{#*} for all non-local channel, @samp{#foo*} for all channels
248 starting with ``foo,'' @samp{#bar} for channel ``#bar'' only, etc.)
250 @item @var{level} is the user level of the user (@ref{User Levels}).
252 @item @var{protection} is the protection level of the user
255 @item @var{auto-op} is set to control whether a user is automatically
256 given operator priviliges on channel entry (@ref{Automatic Op}).
260 @node Using the Bot, Scripting, Configuration, Top
261 @chapter Using Bobot++
270 * Built-In Commands::
273 @node Starting the Bot, User Levels, Using the Bot, Using the Bot
274 @section Starting the Bot
276 The bot is usually installed with the binary name @file{bobotpp}. It
277 accepts the following command line arguments:
280 @item @code{[--help][-h]} - Shows detailed help and exits
281 @item @code{[--version][-v]} - Shows version information and exits
282 @item @code{[--no-background][-b]} - Run bobot++ in the foreground
283 @item @code{[--config-file file][-f]} - Use file instead of @file{bot.conf}
284 @item @code{[--config-dir dir][-d]} - Use dir as dir to load config file from
285 @item @code{[--config dir][-c]} - Search your config path (defaults to
286 @file{@var{$HOME}/.bobotpp/config/} and then @file{/etc/bobotpp/}) for
287 dir and then loads your config data using dir
288 @item @code{[--sys-config dir][-s]} - Looks for config in
289 @file{/etc/bobotpp/dir}. Note that the user dir is still searched
291 @item @code{[--user-config dir][-u]} - Looks for config in
292 @file{@var{$HOME}/.bobotpp/config/dir/}. Note that the system dir is
293 still searched after this if dir is not found.
294 @item @code{[--debug][-D]} Makes Bobot++ print debugging info and run
296 @item @code{[--debug-scripts][-S]} Enabled the Guile debugging
297 evaluator for verbose script errors and backtraces while still running
298 the bot in the background.
301 The default configuration is read from
302 @file{@var{$HOME}/.bobotpp/config/default/} and then
303 @file{/etc/bobotpp/default/} if the user config is not found.
305 The bot defaults to running in the background as a daemon.
307 @node User Levels, Protection, Starting the Bot, Using the Bot
310 There are several user levels available in Bobot++ to provide gradated
311 access to commands. @command{!adduser} and @file{bot.users} use the
312 numeric code; Scheme uses the textual name for the level. By default
313 (if no catch-all setting is found in @xref{bot.users}.) a user is not
314 even a @code{bot:user-none} and cannot execute @strong{any} commands,
315 even commands available to @code{bot:user-none}.
319 @item @code{bot:user-none} - No @strong{built-in} commands may be
320 executed @emph{by default} (commands may be added from Scheme that can
321 be executed by users of level none and the level required to execute a
322 command may be changed from Scheme).
324 @item @code{bot:user-user} - Will be able to execute most commands but
325 not all and cannot use masks on kicks and bans.
327 @item @code{bot:user-trusted} - For built-ins with a default
328 configuration this user has access to the same set of commands as an
329 @code{user} but may use masks on kicks and bans. Scheme commands may
330 be added which require a user to be of this level.
332 @item @code{bot:user-friend} - In the default configuration a user who
333 is a friend will be able to do everything short of stopping the
334 bot. Again, there may be user added commands that require a higher
337 @item @code{bot:user-master} - This is the highest user level and has
338 access to every feature of the bot.
342 @node Protection, Automatic Op, User Levels, Using the Bot
345 A user added via Scheme, the @file{bot.users} file, or
346 @command{!adduser} may be protected from being deoped, kicked, or
347 banned. There are currently no symbolic levels in Scheme; just use the
352 @item No ban. If a user is banned the bot will unban him..
353 @item No kick. The user may still be kicked but the bot will kickban
354 the user who kicked the protected user.
355 @item No deop. The bot will ensure that the user always maintains
359 @node Automatic Op, Built-In Commands, Protection, Using the Bot
360 @section Automatic Op
362 A user may be automatically given operator status upon entering a
363 channel. Set the @var{aop} field to ``0'' to disable auto-op or ``1''
366 @node Built-In Commands, , Automatic Op, Using the Bot
367 @section Built-In Commands
369 Bobot++ has many built-in commands that make it useful without
370 scripting support. The reference leaves off the command char; remember
371 to use whatever you defined the command char to be in
372 @file{bot.conf}. If a command needs the channel name then you must
373 specify the channel as the first argument to the command when private
374 messaging the bot a command.
376 @multitable @columnfractions 0.20 0.15 0.15 0.50
377 @item @sc{command} @tab @sc{Needs Channel} @tab @sc{Min Level to Use} @tab @sc{Description}
379 @item @command{action} @option{do} @tab Yes @tab @var{USER} @tab
380 Causes the bot to perform the action @option{do} in the current
383 @item @command{adduser} @tab @tab @tab
385 @item @command{addserver} @tab @tab @tab Adds the server specified by
386 @var{host name} or @var{ip address} to the server list.
388 @item @command{addshit} @tab @tab @tab
390 @item @command{alias} @tab @tab @tab Makes an alias, and adds the
391 function @var{new name}, that will do exactly the same command as
394 @item @command{ban} @tab @tab @tab Bans @var{mask} or @var{nick} from
395 @var{channel}. You need to be a trusted user to ban with a
398 @item @command{banlist} @tab @tab @tab
400 @item @command{channels} @tab @tab @tab Prints the channel(s) where
401 the bot is currently.
403 @item @command{cycle} @tab Yes @tab @tab Makes the bot leave and join
406 @item @command{dcclist} @tab @tab @tab Gives the list of all DCC Chat
409 @item @command{deban} @tab Yes @tab @tab Debans @var{mask} or
410 @var{nick} from @var{channel}. You need to be a trusted user to deban
413 @item @command{delserver} @tab @tab @tab Deletes server from server
414 list whose number in the server list is @var{server number}.
416 @item @command{deluser} @tab @tab @tab Removes @var{nick} or
417 @var{mask} from the userlist.
419 @item @command{delshit} @tab @tab @tab Removes @var{nick} or
420 @var{mask} from the shitlist.
422 @item @command{deop} @tab Yes @tab @tab Deops @var{mask} or @var{nick}
425 @item @command{die} @tab @tab @tab Makes the bot stop immediately.
427 @item @command{do} @tab @tab @tab
429 @item @command{execute} @tab @tab @tab @strong{Only available if
430 scripting support is enabled}
432 @item @command{help} @tab @tab @tab
434 @item @command{ident} @tab @tab @tab Identifies you on the bot. Note
435 that you should not use this command in public @dots{}
437 @item @command{invite} @tab Yes @tab @tab Invites @var{nick} on
440 @item @command{join} @tab @tab @tab Makes the bot join @var{channel}.
442 @item @command{keep} @tab Yes @tab @tab Sets the @var{modes} that the
443 bot will keep for @var{channel}.
445 @item @command{kick} @tab Yes @tab @tab Kicks @var{mask} or @var{nick}
446 out of @var{channel}, because of @var{reason}. You need to be a
447 trusted user to use a @var{mask}.
449 @item @command{kickban} @tab Yes @tab @tab Bans then kicks @var{mask}
450 or @var{nick} out of @var{channel}, because of @var{reason}. You need
451 to be a trusted user to use a @var{mask}.
453 @item @command{load} @tab @tab @tab Reloads the userlist from disk.
455 @item @command{loadscript} @tab @tab @tab @strong{Only available if
456 scripting support is enabled}
458 @item @command{lock} @tab @tab @tab Locks topic on @var{channel}.
460 @item @command{mode} @tab Yes @tab @tab Sends @var{mode string} as
461 mode for @var{channel}.
463 @item @command{msg} @tab @tab @tab
465 @item @command{names} @tab Yes @tab @tab Shows the nicknames and
466 status of users on @var{channel}.
468 @item @command{nextserver} @tab @tab @tab Makes the bot connect to the
469 next server in its server list.
471 @item @command{nick} @tab @tab @tab Makes the bot use nickname @var{nick}.
473 @item @command{nslookup} @tab @tab @tab Does a nameserver query about
474 @var{nick} host, @var{host} or @var{ip address}.
476 @item @command{op} @tab Yes @tab @tab Ops @var{nick} on @var{channel}.
478 @item @command{part} @tab Yes @tab @tab Makes the bot leave @var{channel}.
480 @item @command{password} @tab @tab @tab Changes your password on the
481 bot. Use @code{NONE} as password if you want to clear it. Do not use this
484 @item @command{reconnect} @tab @tab @tab Makes the bot reconnect to
487 @item @command{rspymessage} @tab @tab @tab Removes you from the spy
490 @item @command{save} @tab @tab @tab Saves the userlist.
492 @item @command{say} @tab Yes @tab @tab Makes the bot say @var{message}
495 @item @command{server} @tab @tab @tab Select the server to connect
496 to. @var{server number} is the number of the server in the serverlist.
498 @item @command{serverlist} @tab @tab @tab Shows the bot's serverlist.
500 @item @command{setfloodrate} @tab @tab @tab
502 @item @command{setversion} @tab @tab @tab
504 @item @command{shitlist} @tab @tab @tab Shows the bot's shitlist.
506 @item @command{spylist} @tab @tab @tab Shows the bot's spylist.
508 @item @command{spymessage} @tab @tab @tab Adds you to the spylist
510 @item @command{stats} @tab Yes @tab @tab Gives @var{channel}'s statistics.
512 @item @command{tban} @tab Yes @tab @tab Bans @var{nick} or @var{mask}
513 from @var{channel} for @var{time} seconds.
515 @item @command{tkban} @tab Yes @tab @tab Bans @var{nick} or @var{mask}
516 from @var{channel} for @var{time} seconds, then kicks him/them because
519 @item @command{topic} @tab Yes @tab @tab If no @var{topic}is given,
520 prints @var{channel}'s topic. Otherwise, the bot will change
521 @var{channel}'s topic to @var{topic}.
523 @item @command{unlock} @tab Yes @tab @tab Makes the bot unlock topic
526 @item @command{userlist} @tab @tab @tab Shows the bot's userlist
528 @item @command{who} @tab Yes @tab @tab Show your level on @var{channel}
530 @item @command{whois} @tab Yes @tab @tab Shows information about
531 @var{nick} on @var{channel}
535 @node Scripting, Concept Index, Using the Bot, Top
538 Bobot++'s most powerful feature is its scripting system. You write
539 scripts using Guile Scheme. This manual does not cover how to use
540 Guile or how to learn Scheme. @xref{Top, , Guile Reference Manual,
541 guile, The Guile Reference Manual}, for the Guile reference manual and
542 @url{http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html} for
543 a good tutorial on Scheme.
545 Note that in previous versions the scripting commands where in the
546 form @code{bot-@var{function}}. They are now in the form
547 @code{bot:@var{function}}. The old names are still available, but are
548 deprecated and will be removed in Bobot++ 3.0. New commands are only
549 available with the @code{bot:} prefix. The command @command{perl -pi
550 -e ``s/bot-/bot:/g'' @var{your-files}} should be enough to convert
551 your code to use the new functions.
554 * Adding New Commands::
556 * Scheme User Levels::
558 * Misc Scripting Stuff::
561 @node Adding New Commands, Hooks, Scripting, Scripting
562 @section Adding New Commands
564 Adding a new command is simple. To register a new command use
565 @code{bot:addcommand}.
567 @defun bot:addcommand name func needs-channel? num-of-args min-level
569 The @var{name} is a string representing the name of the command being
570 added. @var{func} is a function accepting @var{num-of-args}
571 arguments. @var{needs-channel?} is a bool that is true if the function
572 needs the channel name as its first arg, and false otherwise.
573 @var{num-of-args} is the number of args @var{func} will take and must
574 be within zero (0) and twenty (20). @var{min-level} is one of the
575 @ref{Scheme User Levels}. A user must be at least a @code{min-level}
576 user to use the new command. None of the arguments are guaranteed to
577 be passed; if they aren't they are set to the empty string @code{""}.
578 An example of a new command would be:
581 (define (hello channel name)
582 (if (string=? name "")
583 (bot:say channel "Hello world!")
584 (bot:say channel (string-append "Hello " name "!")))
586 (bot:addcommand "hello" hello #t 2 0)
589 This will display ``Hello World!'' if called as @kbd{!hello} and
590 ``Hello World @code{USER}'' if called as @kbd{!hello @var{USER}}.
593 @node Hooks, Scheme User Levels, Adding New Commands, Scripting
596 @cindex Background on Hooks
597 Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
598 and tiny fugue (a MUD bot) hooks with a little bit of extra stuff
599 added in. A hook is called when a regular expression is matched
600 against a message sent to or by the bot.
602 Bobot++ uses different hook types for each IRC message type, and also
603 includes a hook for accessing raw irc messages. Hooks are tagged with
604 a priority and a flag that specifies whether to call the next hook
605 that matches after calling the current one or to stop
608 Hooks are processed from the highest to lowest priority, with
609 fallthrough hooks of equal priority to non-fallthrough hooks being
617 @node Creating a Hook, Hook Types, Hooks, Hooks
618 @subsection Creating a Hook
620 To add a new hook you use the function @code{bot:addhook}.
622 @defun bot:addhook type regex function [pri fall name]
623 @var{type} specifies the type of hook (the types of hooks are listed
624 in @ref{Hook Types}). @var{regex} is a standard regular expression. If
625 @var{regex} is matched, @var{function} will be called. @var{function}
626 will take a different number of args depending on the hook
627 type. @var{pri} specifies the priority of the hook---higher priority
628 hooks are executed first. This argument is optional and defaults to
629 @code{0}. @var{fall} is @code{#t} if the hook is a fallthrough hook
630 and @code{#f} is the hook is not a fallthrough hook. This arg is also
631 optional and default to @code{#t}. @var{name} is the optional name of
632 the hook that defaults to ``DEFAULT''. If you set the name then you
633 can have more than one hook that matches the same regexp, as long as
634 they have the same name. E.g. in a log script you could have the
635 regexps for the log function all be @code{".*"} and set their names to
636 @code{"log"} to avoid a conflict with other hooks.
639 @node Hook Types, , Creating a Hook, Hooks
640 @subsection Hook Types
642 Here is a list of the various hooks funtions and notes on each
643 one. The general format of each hook description is as if it were a
644 function to be defined, but these describe the function to be passwd
645 to @code{bot:add-hook}. Do @emph{not} name your functions these
648 That said, here is the list of available hooks functions.
651 @defun hooks/action from to action
652 This hook is triggered when someone performs an action. @var{from} is
653 the address of the person that performed the action in the form
654 @samp{@var{nick} ! @var{user} @@ @var{host}} (without the spaces).
655 @var{to} is the target of the action, which is either a channel or the
656 Bot's nick. @var{action} is the text of the action. E.g. if someone
657 did @samp{* foobar does baz}, then @var{action} would be the string
662 @defun hooks/nickname old-nick new-nick
663 This hook gets called when someone changes thir nickname from
664 @var{old-nick} to @var{new-nick}.
667 @defun hooks/signoff nick rest
670 @defun hooks/ctcp nick to command rest
673 @defun hooks/ctcp-reply nick command rest
676 @defun hooks/disconnect server
677 This is called when the bot is disconnected from a server
678 unintentionally. @code{hooks/signoff} is called when the bot purposefully
679 disconnected. The hook function is passed the hostname of the
680 server it was disconnected from.
683 @defun hooks/flood nick
686 @defun hooks/invite nick channel
689 @defun hooks/join nick channel
692 @defun hooks/kick target from channel reason
695 @defun hooks/leave nick channel
696 @defunx hooks/part nick channel
699 @defun hooks/mode nick channel modes
702 @defun hooks/message from message
705 @defun hooks/notice nick message
708 @defun hooks/public from to message
711 @defun hooks/public-notice nick to message
714 @defun hooks/raw raw-message
717 @defun hooks/timer time
718 This hook seems to be called once a minute. @var{time} is in
722 @defun hooks/topic nick channel new-topic
725 @defun hooks/send/public mynick dest message
728 @defun hooks/send/message botnick message
731 @defun hooks/send/action mynick to message
734 @defun hooks/send/ctcp mynick to command message
737 @defun hooks/dcc/chat-begin from
738 This hook is triggered when a user begins a DCC CHAT with the bot.
739 @var{from} is the user's address in the form @samp{nick!user@@host}.
742 @defun hooks/dcc/chat-message from message
743 This hook is triggered when a user sends a message to the bot through
744 a DCC CHAT @var{from} is the user's address in the form
745 @samp{nick!user@@host}. @var{message} is the message the user sent to
749 @node Scheme User Levels, Sending Messages, Hooks, Scripting
750 @section Scheme User Levels
757 There are five levels that a user may be when interfacing with a bot:
758 @var{none}, @var{user}, @var{trusted_user}, @var{friend},
759 @var{master}. The Scheme variables for the user levels are
760 @code{bot:user-none}, @code{bot:user-user}, @code{bot:user-trusted},
761 @code{bot:user-friend}, and @code{bot:user-master}. See @ref{User
762 Levels} for more information on User Levels.
764 When adding a new command, think about who should be able to use
765 it. Is your command a general purpose command that helps the channel
766 (e.g. @code{!seen}) that everyone should be able to use? Or is it
767 something that should be restricted? See @ref{User Levels} for
768 information on what level users can do what with the built in bot
769 commands and think about what level a user your command is targetted
770 towards. You must be @emph{very} careful when giving new commands to
771 lower level users because you can do basically everything the bot can
772 do with a script. As the scripting interface becomes more powerful,
773 you must think more about what users can use new commands you add.
775 @node Sending Messages, Misc Scripting Stuff, Scheme User Levels, Scripting
776 @section Sending Messages
778 There are several types of messages you can send with Bobot++ from
779 scripts. There is the simple, but rather limited, @code{bot:say},
780 @code{bot:action} and @code{bot:msg}, and the more powerful, but lower
781 level, @code{bot:send-MESSAGE} functions. Most bots will probably only
782 need the higher level functions, but for the sake of why-not Bobot++
783 lets you use the lower level functions (in progress).
786 * High Level Message Functions::
787 * Low Level Message Functions::
790 @node High Level Message Functions, Low Level Message Functions, Sending Messages, Sending Messages
791 @subsection ``High Level'' Message Functions
793 @defun bot:say channel message
794 Send a public or private @var{message} to @var{channel}.
796 Sends a normal text message, as if a user had typed it in. The
797 @var{dest} can be a nickname or a channel.
800 @defun bot:action channel message
801 Send an ``action'' type @var{message} to @var{channel}
804 @defun bot:msg nick message
805 The same as if a user typed @code{/msg nick message} to their IRC client.
808 @defun bot:notice target message
809 Sends @var{message} as a NOTICE to @var{target}. @var{target} may be a
810 user (nick) or a channel. This returns 0 on success.
813 @node Low Level Message Functions, , High Level Message Functions, Sending Messages
814 @subsection ``Low Level'' Message Functions
816 @c Add a url for rfc2812
817 The ``Low Level'' messaging functions allow you to do things like send
818 CTCP messages. You probably want to read rfc 2812 and the CTCP spec
819 before using these. If you have no idea what these do, read rfc 2812
820 (IRC Client Protocol) and CTCP spec. These functions all return
821 @code{*unspecified*} always, so don't use the return value for
824 @defun bot:send-ctcp to command message
825 @code{to} is the target of your CTCP message, @code{command} is the
826 CTCP command, and @code{message} is the message (or arguments) of the
827 command. Make sure to @code{bot:ctcp-quote} the message!
830 @defun bot:send-ctcp-reply to command message
831 @code{to} is the target of your CTCP reply, @code{command} is the
832 CTCP command, and @code{message} is the message (or arguments) of the
833 command. Make sure to @code{bot:ctcp-quote} the message!
835 This is used to reply to a ctcp that the bot has received.
838 @node Misc Scripting Stuff, , Sending Messages, Scripting
839 @section Misc. Scripting Stuff
841 These are a few useful things that I thought people writing scripts
845 If you want to execute code when the bot exits, just do
846 @code{add-hook! bot:exit-hook @var{thunk}} where @var{thunk} is an
847 argumentless procedure (a thunk). When the bot exits your thunk will
851 [ I didn't know where to put any of these, so I jsut stuck them in
854 There probably needs to be several sections added, like dealing with
855 users (kicking, added, etc), dealing with the bot (channels, nickname
856 of the bot, etc), server issues (serverlist), useful tools (nslookup,
861 @defun bot:adduser nick-or-mask cbannel-mask level prot auto-op
862 Adds an user to the userlist, for a @code{nick!user@@host} matching the
863 one given, on a channel matching the @var{channelMask} given.
865 @multitable @columnfractions 0.33 0.33 0.33
866 @item The @var{level} can be: @tab The @var{prot} can be: @tab The @var{auto-op} can be:
867 @item 0 - No level @tab 0 - No protection @tab 0 - No auto-op
868 @item 1 - User @tab 1 - No ban @tab 1 - Op on join
869 @item 2 - Trusted User @tab 2 - No kick @tab
870 @item 3 - Friend @tab 3 - No deop @tab
871 @item 4 - Master @tab @tab
877 @defun bot:addserver hostname ip-address [portnumber]
878 Adds the server specified by @var{hostname} or @var{ip-address} to
883 @defun bot:addshit nick-or-mask channel-mask level [time reason]
884 Adds an user to the shitlist, for a nick!user@@host matching the
885 one given, on a channel matching the @var{channelMask} given.
888 The @var{level} can be:
891 2 - Kick and Ban on join
892 3 - Kick and Ban on join, no deban
898 @defun bot:ban channel mask-or-nick
899 Bans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
900 user to ban with a @var{mask}.
904 @defun bot:change-command-level nick-or-mask channel-mask new-level
905 Gives @var{nick} or @var{mask} level @var{new-level} on channel(s)
906 @var{channel-mask}. Note that you can not change level for someone
907 whose level is greater than yours, and that you can not give a
908 level greater than yours.
912 @defun bot:cycle channel
913 Makes the bot leave and join @var{channel}.
917 @defun bot:deban channel mask-or-nick
918 Debans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
919 user to deban with a @var{mask}.
923 @defun bot:delserver server-number
924 Deletes server from server list whose number in the server list
925 is @var{server-number}
929 @defun bot:deluser nick-or-mask channel-mask
930 Removes @var{nick} or @var{mask} from the userlist.
934 @defun bot:delshit nick-or-mask channel-mask
935 Removes @var{nick} or @var{mask} from the shitlist.
939 @defun bot:deop channel mask-or-nick
940 Deops @var{mask} or @var{nick} on @var{channel}.
944 @defun bot:die reason
945 Makes the bot stop immediately.
953 @defun bot:invite channel nick
954 Invites @var{nick} on @var{channel}.
958 @defun bot:join channel
959 Makes the bot join @var{channel}.
963 @defun bot:keep channel modes
964 Sets the @var{modes} that the bot will keep for @var{channel}.
969 @defun bot:kick channel mask-or-nick [reason]
970 Kicks @var{mask} or @var{nick} out of @var{channel}, because of @var{reason}.
971 You need to be a trusted user to use a @var{mask}.
975 @defun bot:kickban channel mask-or-nick [reason]
976 Bans then kicks @var{mask} or @var{nick} out of @var{channel},
977 because of @var{reason}.
978 You need to be a trusted user to use a @var{mask}.
982 @defun bot:lock channel
983 Locks topic on @var{channel}.
988 [ Probably returns the log port? ]
992 @defun bot:mode channel mode-string
993 Sends @var{mode-string} as mode for @var{channel}.
997 @defun bot:nextserver
998 Makes the bot connect to the next server in its server list.
1002 @defun bot:nick nick
1003 Makes the bot use nickname @var{nick}.
1007 @defun bot:op channel nick
1008 Ops @var{nick} on @var{channel}.
1012 @defun bot:part channel
1013 Makes the bot leave @var{channel}.
1017 @defun bot:reconnect
1018 Makes the bot reconnect to its current server.
1022 @defun bot:server server-number
1023 Select the server to connect to. @var{server-number} is the number of
1024 the server in the serverlist.
1028 @defun bot:setfloodrate ?
1032 @defun bot:setversion ?
1036 @defun bot:tban channel nick-or-mask time
1037 Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds.
1041 @defun bot:tkban channel nick-or-mask time [reason]
1042 Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds,
1043 then kicks him/them because of @var{reason}.
1047 @defun bot:topic channel topic
1048 If no @var{topic} is given, prints @var{channel}'s topic. Otherwise,
1049 the bot will change @var{channel}'s topic to @var{topic}.
1052 @defun bot:unlock channel
1053 Makes the bot unlock topic on @var{channel}.
1057 @defun bot:getnickname
1058 [ Gets the bot's nickname? ]
1062 @defun bot:getserver
1066 @defun bot:getserverlist
1071 [ Flushes the socket to the server? ]
1075 @defun bot:flushport
1076 [ Flushes the log port? ]
1081 [ Returns a random number? What range? Why? ]
1085 @defun bot:delcommand
1086 [ Probably deletes a command added with @code{bot:addcommand} ? ]
1090 @defun bot:addtimer ? ?
1094 @defun bot:deltimer ?
1098 @defun bot:dcc-chat-send ? ?
1102 [ And what about the stuff defined in @file{bobot-utils.scm} ? I just
1103 added it here so it could be somewhere. There should also be a
1104 section dealing with modules. How to use them. What module scripts
1105 are in. What module bobot++ provided primites are in. And so on. ]
1108 @defun bot:log . messages
1109 Write as many @var{messages} as you want to the log. If the arg is a
1110 thunk it will be executed and it's output will be written to the log.
1113 @defun bot:load file
1116 @defun bot:load-module module-spec
1119 @defun bot:use-module module-spec
1122 @defun bot:match-not-channel regex
1123 match-not-channel adds a prefix regex to your @var{regex} so it
1124 doesn't match the sender or channel in a PUBLIC message
1127 @defun bot:match-to-me regex
1128 match-to-me matches text that was addressed to the bot with a
1129 ':', ',', or nothing after the bot name.
1132 @defun bot:sent-to-me? message
1135 @defun bot:ctcp-quote message
1136 Returns the CTCP quoted message
1137 Input @emph{MUST NOT} contain the trailing @code{\r\n}
1138 (it is added by the message sending code).
1142 @defvar %bot:loadpath
1145 @defun %bot:load-extensions
1150 @node Concept Index, Function Index, Scripting, Top
1151 @unnumbered Concept Index
1154 @node Function Index, Variable Index, Concept Index, Top
1155 @unnumbered Function Index
1158 @node Variable Index, , Function Index, Top
1159 @unnumbered Variable Index