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 has
314 access to commands with the level @code{bot:user-none}.
318 @item @code{bot:user-none} - No @strong{built-in} commands may be
319 executed @emph{by default} (commands may be added from Scheme that can
320 be executed by users of level none and the level required to execute a
321 command may be changed from Scheme).
323 @item @code{bot:user-user} - Will be able to execute most commands but
324 not all and cannot use masks on kicks and bans.
326 @item @code{bot:user-trusted} - For built-ins with a default
327 configuration this user has access to the same set of commands as an
328 @code{user} but may use masks on kicks and bans. Scheme commands may
329 be added which require a user to be of this level.
331 @item @code{bot:user-friend} - In the default configuration a user who
332 is a friend will be able to do everything short of stopping the
333 bot. Again, there may be user added commands that require a higher
336 @item @code{bot:user-master} - This is the highest user level and has
337 access to every feature of the bot.
341 @node Protection, Automatic Op, User Levels, Using the Bot
344 A user added via Scheme, the @file{bot.users} file, or
345 @command{!adduser} may be protected from being deoped, kicked, or
346 banned. There are currently no symbolic levels in Scheme; just use the
351 @item No ban. If a user is banned the bot will unban him..
352 @item No kick. The user may still be kicked but the bot will kickban
353 the user who kicked the protected user.
354 @item No deop. The bot will ensure that the user always maintains
358 @node Automatic Op, Built-In Commands, Protection, Using the Bot
359 @section Automatic Op
361 A user may be automatically given operator status upon entering a
362 channel. Set the @var{aop} field to ``0'' to disable auto-op or ``1''
365 @node Built-In Commands, , Automatic Op, Using the Bot
366 @section Built-In Commands
368 Bobot++ has many built-in commands that make it useful without
369 scripting support. The reference leaves off the command char; remember
370 to use whatever you defined the command char to be in
371 @file{bot.conf}. If a command needs the channel name then you must
372 specify the channel as the first argument to the command when private
373 messaging the bot a command.
375 @multitable @columnfractions 0.20 0.15 0.15 0.50
376 @item @sc{command} @tab @sc{Needs Channel} @tab @sc{Min Level to Use} @tab @sc{Description}
378 @item @command{action} @option{do} @tab Yes @tab @var{USER} @tab
379 Causes the bot to perform the action @option{do} in the current
382 @item @command{adduser} @tab @tab @tab
384 @item @command{addserver} @tab @tab @tab Adds the server specified by
385 @var{host name} or @var{ip address} to the server list.
387 @item @command{addshit} @tab @tab @tab
389 @item @command{alias} @tab @tab @tab Makes an alias, and adds the
390 function @var{new name}, that will do exactly the same command as
393 @item @command{ban} @tab @tab @tab Bans @var{mask} or @var{nick} from
394 @var{channel}. You need to be a trusted user to ban with a
397 @item @command{banlist} @tab @tab @tab
399 @item @command{channels} @tab @tab @tab Prints the channel(s) where
400 the bot is currently.
402 @item @command{cycle} @tab Yes @tab @tab Makes the bot leave and join
405 @item @command{dcclist} @tab @tab @tab Gives the list of all DCC Chat
408 @item @command{deban} @tab Yes @tab @tab Debans @var{mask} or
409 @var{nick} from @var{channel}. You need to be a trusted user to deban
412 @item @command{delserver} @tab @tab @tab Deletes server from server
413 list whose number in the server list is @var{server number}.
415 @item @command{deluser} @tab @tab @tab Removes @var{nick} or
416 @var{mask} from the userlist.
418 @item @command{delshit} @tab @tab @tab Removes @var{nick} or
419 @var{mask} from the shitlist.
421 @item @command{deop} @tab Yes @tab @tab Deops @var{mask} or @var{nick}
424 @item @command{die} @tab @tab @tab Makes the bot stop immediately.
426 @item @command{do} @tab @tab @tab
428 @item @command{execute} @tab @tab @tab @strong{Only available if
429 scripting support is enabled}
431 @item @command{help} @tab @tab @tab
433 @item @command{ident} @tab @tab @tab Identifies you on the bot. Note
434 that you should not use this command in public @dots{}
436 @item @command{invite} @tab Yes @tab @tab Invites @var{nick} on
439 @item @command{join} @tab @tab @tab Makes the bot join @var{channel}.
441 @item @command{keep} @tab Yes @tab @tab Sets the @var{modes} that the
442 bot will keep for @var{channel}.
444 @item @command{kick} @tab Yes @tab @tab Kicks @var{mask} or @var{nick}
445 out of @var{channel}, because of @var{reason}. You need to be a
446 trusted user to use a @var{mask}.
448 @item @command{kickban} @tab Yes @tab @tab Bans then kicks @var{mask}
449 or @var{nick} out of @var{channel}, because of @var{reason}. You need
450 to be a trusted user to use a @var{mask}.
452 @item @command{load} @tab @tab @tab Reloads the userlist from disk.
454 @item @command{loadscript} @tab @tab @tab @strong{Only available if
455 scripting support is enabled}
457 @item @command{lock} @tab @tab @tab Locks topic on @var{channel}.
459 @item @command{mode} @tab Yes @tab @tab Sends @var{mode string} as
460 mode for @var{channel}.
462 @item @command{msg} @tab @tab @tab
464 @item @command{names} @tab Yes @tab @tab Shows the nicknames and
465 status of users on @var{channel}.
467 @item @command{nextserver} @tab @tab @tab Makes the bot connect to the
468 next server in its server list.
470 @item @command{nick} @tab @tab @tab Makes the bot use nickname @var{nick}.
472 @item @command{nslookup} @tab @tab @tab Does a nameserver query about
473 @var{nick} host, @var{host} or @var{ip address}.
475 @item @command{op} @tab Yes @tab @tab Ops @var{nick} on @var{channel}.
477 @item @command{part} @tab Yes @tab @tab Makes the bot leave @var{channel}.
479 @item @command{password} @tab @tab @tab Changes your password on the
480 bot. Use @code{NONE} as password if you want to clear it. Do not use this
483 @item @command{reconnect} @tab @tab @tab Makes the bot reconnect to
486 @item @command{rspymessage} @tab @tab @tab Removes you from the spy
489 @item @command{save} @tab @tab @tab Saves the userlist.
491 @item @command{say} @tab Yes @tab @tab Makes the bot say @var{message}
494 @item @command{server} @tab @tab @tab Select the server to connect
495 to. @var{server number} is the number of the server in the serverlist.
497 @item @command{serverlist} @tab @tab @tab Shows the bot's serverlist.
499 @item @command{setfloodrate} @tab @tab @tab
501 @item @command{setversion} @tab @tab @tab
503 @item @command{shitlist} @tab @tab @tab Shows the bot's shitlist.
505 @item @command{spylist} @tab @tab @tab Shows the bot's spylist.
507 @item @command{spymessage} @tab @tab @tab Adds you to the spylist
509 @item @command{stats} @tab Yes @tab @tab Gives @var{channel}'s statistics.
511 @item @command{tban} @tab Yes @tab @tab Bans @var{nick} or @var{mask}
512 from @var{channel} for @var{time} seconds.
514 @item @command{tkban} @tab Yes @tab @tab Bans @var{nick} or @var{mask}
515 from @var{channel} for @var{time} seconds, then kicks him/them because
518 @item @command{topic} @tab Yes @tab @tab If no @var{topic}is given,
519 prints @var{channel}'s topic. Otherwise, the bot will change
520 @var{channel}'s topic to @var{topic}.
522 @item @command{unlock} @tab Yes @tab @tab Makes the bot unlock topic
525 @item @command{userlist} @tab @tab @tab Shows the bot's userlist
527 @item @command{who} @tab Yes @tab @tab Show your level on @var{channel}
529 @item @command{whois} @tab Yes @tab @tab Shows information about
530 @var{nick} on @var{channel}
534 @node Scripting, Concept Index, Using the Bot, Top
537 Bobot++'s most powerful feature is its scripting system. You write
538 scripts using Guile Scheme. This manual does not cover how to use
539 Guile or how to learn Scheme. @xref{Top, , Guile Reference Manual,
540 guile, The Guile Reference Manual}, for the Guile reference manual and
541 @url{http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html} for
542 a good tutorial on Scheme.
544 Note that in previous versions the scripting commands where in the
545 form @code{bot-@var{function}}. They are now in the form
546 @code{bot:@var{function}}. The old names are still available, but are
547 deprecated and will be removed in Bobot++ 3.0. New commands are only
548 available with the @code{bot:} prefix. The command @command{perl -pi
549 -e ``s/bot-/bot:/g'' @var{your-files}} should be enough to convert
550 your code to use the new functions.
553 * Adding New Commands::
555 * Scheme User Levels::
557 * Misc Scripting Stuff::
560 @node Adding New Commands, Hooks, Scripting, Scripting
561 @section Adding New Commands
563 Adding a new command is simple. To register a new command use
564 @code{bot:addcommand}.
566 @defun bot:addcommand name func needs-channel? num-of-args min-level
568 The @var{name} is a string representing the name of the command being
569 added. @var{func} is a function accepting @var{num-of-args}
570 arguments. @var{needs-channel?} is a bool that is true if the function
571 needs the channel name as its first arg, and false otherwise.
572 @var{num-of-args} is the number of args @var{func} will take and must
573 be within zero (0) and twenty (20). @var{min-level} is one of the
574 @ref{Scheme User Levels}. A user must be at least a @code{min-level}
575 user to use the new command. None of the arguments are guaranteed to
576 be passed; if they aren't they are set to the empty string @code{""}.
577 An example of a new command would be:
580 (define (hello channel name)
581 (if (string=? name "")
582 (bot:say channel "Hello world!")
583 (bot:say channel (string-append "Hello " name "!")))
585 (bot:addcommand "hello" hello #t 2 0)
588 This will display ``Hello World!'' if called as @kbd{!hello} and
589 ``Hello World @code{USER}'' if called as @kbd{!hello @var{USER}}.
592 @node Hooks, Scheme User Levels, Adding New Commands, Scripting
595 @cindex Background on Hooks
596 Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
597 and tiny fugue (a MUD bot) hooks with a little bit of extra stuff
598 added in. A hook is called when a regular expression is matched
599 against a message sent to or by the bot.
601 Bobot++ uses different hook types for each IRC message type, and also
602 includes a hook for accessing raw irc messages. Hooks are tagged with
603 a priority and a flag that specifies whether to call the next hook
604 that matches after calling the current one or to stop
607 Hooks are processed from the highest to lowest priority, with
608 fallthrough hooks of equal priority to non-fallthrough hooks being
616 @node Creating a Hook, Hook Types, Hooks, Hooks
617 @subsection Creating a Hook
619 To add a new hook you use the function @code{bot:addhook}.
621 @defun bot:addhook type regex function [pri fall name]
622 @var{type} specifies the type of hook (the types of hooks are listed
623 in @ref{Hook Types}). @var{regex} is a standard regular expression. If
624 @var{regex} is matched, @var{function} will be called. @var{function}
625 will take a different number of args depending on the hook
626 type. @var{pri} specifies the priority of the hook---higher priority
627 hooks are executed first. This argument is optional and defaults to
628 @code{0}. @var{fall} is @code{#t} if the hook is a fallthrough hook
629 and @code{#f} is the hook is not a fallthrough hook. This arg is also
630 optional and default to @code{#t}. @var{name} is the optional name of
631 the hook that defaults to ``DEFAULT''. If you set the name then you
632 can have more than one hook that matches the same regexp, as long as
633 they have the same name. E.g. in a log script you could have the
634 regexps for the log function all be @code{".*"} and set their names to
635 @code{"log"} to avoid a conflict with other hooks.
638 @node Hook Types, , Creating a Hook, Hooks
639 @subsection Hook Types
641 Here is a list of the various hooks funtions and notes on each
642 one. The general format of each hook description is as if it were a
643 function to be defined, but these describe the function to be passwd
644 to @code{bot:add-hook}. Do @emph{not} name your functions these
647 That said, here is the list of available hooks functions.
650 @defun hooks/action from to action
651 This hook is triggered when someone performs an action. @var{from} is
652 the address of the person that performed the action in the form
653 @samp{@var{nick} ! @var{user} @@ @var{host}} (without the spaces).
654 @var{to} is the target of the action, which is either a channel or the
655 Bot's nick. @var{action} is the text of the action. E.g. if someone
656 did @samp{* foobar does baz}, then @var{action} would be the string
661 @defun hooks/nickname old-nick new-nick
662 This hook gets called when someone changes thir nickname from
663 @var{old-nick} to @var{new-nick}.
666 @defun hooks/signoff nick rest
669 @defun hooks/ctcp nick to command rest
672 @defun hooks/ctcp-reply nick command rest
675 @defun hooks/disconnect server
676 This is called when the bot is disconnected from a server
677 unintentionally. @code{hooks/signoff} is called when the bot purposefully
678 disconnected. The hook function is passed the hostname of the
679 server it was disconnected from.
682 @defun hooks/flood nick
685 @defun hooks/invite nick channel
688 @defun hooks/join nick channel
691 @defun hooks/kick target from channel reason
694 @defun hooks/leave nick channel
695 @defunx hooks/part nick channel
698 @defun hooks/mode nick channel modes
701 @defun hooks/message from message
704 @defun hooks/notice nick message
707 @defun hooks/public from to message
710 @defun hooks/public-notice nick to message
713 @defun hooks/raw raw-message
716 @defun hooks/timer time
717 This hook seems to be called once a minute. @var{time} is in
721 @defun hooks/topic nick channel new-topic
724 @defun hooks/send/public mynick dest message
727 @defun hooks/send/message botnick message
730 @defun hooks/send/action mynick to message
733 @defun hooks/send/ctcp mynick to command message
736 @defun hooks/dcc/chat-begin from
737 This hook is triggered when a user begins a DCC CHAT with the bot.
738 @var{from} is the user's address in the form @samp{nick!user@@host}.
741 @defun hooks/dcc/chat-message from message
742 This hook is triggered when a user sends a message to the bot through
743 a DCC CHAT @var{from} is the user's address in the form
744 @samp{nick!user@@host}. @var{message} is the message the user sent to
748 @node Scheme User Levels, Sending Messages, Hooks, Scripting
749 @section Scheme User Levels
756 There are five levels that a user may be when interfacing with a bot:
757 @var{none}, @var{user}, @var{trusted_user}, @var{friend},
758 @var{master}. The Scheme variables for the user levels are
759 @code{bot:user-none}, @code{bot:user-user}, @code{bot:user-trusted},
760 @code{bot:user-friend}, and @code{bot:user-master}. See @ref{User
761 Levels} for more information on User Levels.
763 When adding a new command, think about who should be able to use
764 it. Is your command a general purpose command that helps the channel
765 (e.g. @code{!seen}) that everyone should be able to use? Or is it
766 something that should be restricted? See @ref{User Levels} for
767 information on what level users can do what with the built in bot
768 commands and think about what level a user your command is targetted
769 towards. You must be @emph{very} careful when giving new commands to
770 lower level users because you can do basically everything the bot can
771 do with a script. As the scripting interface becomes more powerful,
772 you must think more about what users can use new commands you add.
774 @node Sending Messages, Misc Scripting Stuff, Scheme User Levels, Scripting
775 @section Sending Messages
777 There are several types of messages you can send with Bobot++ from
778 scripts. There is the simple, but rather limited, @code{bot:say},
779 @code{bot:action} and @code{bot:msg}, and the more powerful, but lower
780 level, @code{bot:send-MESSAGE} functions. Most bots will probably only
781 need the higher level functions, but for the sake of why-not Bobot++
782 lets you use the lower level functions (in progress).
785 * High Level Message Functions::
786 * Low Level Message Functions::
789 @node High Level Message Functions, Low Level Message Functions, Sending Messages, Sending Messages
790 @subsection ``High Level'' Message Functions
792 @defun bot:say channel message
793 Send a public or private @var{message} to @var{channel}.
795 Sends a normal text message, as if a user had typed it in. The
796 @var{dest} can be a nickname or a channel.
799 @defun bot:action channel message
800 Send an ``action'' type @var{message} to @var{channel}
803 @defun bot:msg nick message
804 The same as if a user typed @code{/msg nick message} to their IRC client.
807 @defun bot:notice target message
808 Sends @var{message} as a NOTICE to @var{target}. @var{target} may be a
809 user (nick) or a channel. This returns 0 on success.
812 @node Low Level Message Functions, , High Level Message Functions, Sending Messages
813 @subsection ``Low Level'' Message Functions
815 @c Add a url for rfc2812
816 The ``Low Level'' messaging functions allow you to do things like send
817 CTCP messages. You probably want to read rfc 2812 and the CTCP spec
818 before using these. If you have no idea what these do, read rfc 2812
819 (IRC Client Protocol) and CTCP spec. These functions all return
820 @code{*unspecified*} always, so don't use the return value for
823 @defun bot:send-ctcp to command message
824 @var{to} is the target of your CTCP message, @var{command} is the
825 CTCP command, and @var{message} is the message (or arguments) of the
826 command. Make sure to @code{bot:ctcp-quote} the message!
829 @defun bot:send-ctcp-reply to command message
830 @var{to} is the target of your CTCP reply, @var{command} is the
831 CTCP command, and @var{message} is the message (or arguments) of the
832 command. Make sure to @code{bot:ctcp-quote} the message!
834 This is used to reply to a ctcp that the bot has received.
837 @node Misc Scripting Stuff, , Sending Messages, Scripting
838 @section Misc. Scripting Stuff
840 These are a few useful things that I thought people writing scripts
844 If you want to execute code when the bot exits, just do
845 @code{add-hook! bot:exit-hook @var{thunk}} where @var{thunk} is an
846 argumentless procedure (a thunk). When the bot exits your thunk will
850 [ I didn't know where to put any of these, so I just stuck them in
853 There probably needs to be several sections added, like dealing with
854 users (kicking, added, etc), dealing with the bot (channels, nickname
855 of the bot, etc), server issues (serverlist), useful tools (nslookup,
860 @defun bot:adduser nick-or-mask cbannel-mask level prot auto-op
861 Adds an user to the userlist, for a @code{nick!user@@host} matching the
862 one given, on a channel matching the @var{channelMask} given.
864 @multitable @columnfractions 0.33 0.33 0.33
865 @item The @var{level} can be: @tab The @var{prot} can be: @tab The @var{auto-op} can be:
866 @item 0 - No level @tab 0 - No protection @tab 0 - No auto-op
867 @item 1 - User @tab 1 - No ban @tab 1 - Op on join
868 @item 2 - Trusted User @tab 2 - No kick @tab
869 @item 3 - Friend @tab 3 - No deop @tab
870 @item 4 - Master @tab @tab
876 @defun bot:addserver hostname ip-address [portnumber]
877 Adds the server specified by @var{hostname} or @var{ip-address} to
882 @defun bot:addshit nick-or-mask channel-mask level [time reason]
883 Adds an user to the shitlist, for a nick!user@@host matching the
884 one given, on a channel matching the @var{channelMask} given.
887 The @var{level} can be:
890 2 - Kick and Ban on join
891 3 - Kick and Ban on join, no deban
897 @defun bot:ban channel mask-or-nick
898 Bans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
899 user to ban with a @var{mask}.
903 @defun bot:change-command-level nick-or-mask channel-mask new-level
904 Gives @var{nick} or @var{mask} level @var{new-level} on channel(s)
905 @var{channel-mask}. Note that you can not change level for someone
906 whose level is greater than yours, and that you can not give a
907 level greater than yours.
911 @defun bot:cycle channel
912 Makes the bot leave and join @var{channel}.
916 @defun bot:deban channel mask-or-nick
917 Debans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
918 user to deban with a @var{mask}.
922 @defun bot:delserver server-number
923 Deletes server from server list whose number in the server list
924 is @var{server-number}
928 @defun bot:deluser nick-or-mask channel-mask
929 Removes @var{nick} or @var{mask} from the userlist.
933 @defun bot:delshit nick-or-mask channel-mask
934 Removes @var{nick} or @var{mask} from the shitlist.
938 @defun bot:deop channel mask-or-nick
939 Deops @var{mask} or @var{nick} on @var{channel}.
943 @defun bot:die reason
944 Makes the bot stop immediately.
952 @defun bot:invite channel nick
953 Invites @var{nick} on @var{channel}.
957 @defun bot:join channel
958 Makes the bot join @var{channel}.
962 @defun bot:keep channel modes
963 Sets the @var{modes} that the bot will keep for @var{channel}.
968 @defun bot:kick channel mask-or-nick [reason]
969 Kicks @var{mask} or @var{nick} out of @var{channel}, because of @var{reason}.
970 You need to be a trusted user to use a @var{mask}.
974 @defun bot:kickban channel mask-or-nick [reason]
975 Bans then kicks @var{mask} or @var{nick} out of @var{channel},
976 because of @var{reason}.
977 You need to be a trusted user to use a @var{mask}.
981 @defun bot:lock channel
982 Locks topic on @var{channel}.
987 [ Probably returns the log port? ]
991 @defun bot:mode channel mode-string
992 Sends @var{mode-string} as mode for @var{channel}.
996 @defun bot:nextserver
997 Makes the bot connect to the next server in its server list.
1001 @defun bot:nick nick
1002 Makes the bot use nickname @var{nick}.
1006 @defun bot:op channel nick
1007 Ops @var{nick} on @var{channel}.
1011 @defun bot:part channel
1012 Makes the bot leave @var{channel}.
1016 @defun bot:reconnect
1017 Makes the bot reconnect to its current server.
1021 @defun bot:server server-number
1022 Select the server to connect to. @var{server-number} is the number of
1023 the server in the serverlist.
1027 @defun bot:setfloodrate ?
1031 @defun bot:setversion ?
1035 @defun bot:tban channel nick-or-mask time
1036 Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds.
1040 @defun bot:tkban channel nick-or-mask time [reason]
1041 Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds,
1042 then kicks him/them because of @var{reason}.
1046 @defun bot:topic channel topic
1047 If no @var{topic} is given, prints @var{channel}'s topic. Otherwise,
1048 the bot will change @var{channel}'s topic to @var{topic}.
1051 @defun bot:unlock channel
1052 Makes the bot unlock topic on @var{channel}.
1056 @defun bot:getnickname
1057 [ Gets the bot's nickname? ]
1061 @defun bot:getserver
1065 @defun bot:getserverlist
1070 [ Flushes the socket to the server? ]
1074 @defun bot:flushport
1075 [ Flushes the log port? ]
1080 [ Returns a random number? What range? Why? ]
1084 @defun bot:delcommand
1085 [ Probably deletes a command added with @code{bot:addcommand} ? ]
1089 @defun bot:addtimer ? ?
1093 @defun bot:deltimer ?
1097 @defun bot:dcc-chat-send ? ?
1101 [ And what about the stuff defined in @file{bobot-utils.scm} ? I just
1102 added it here so it could be somewhere. There should also be a
1103 section dealing with modules. How to use them. What module scripts
1104 are in. What module bobot++ provided primites are in. And so on. ]
1107 @defun bot:log . messages
1108 Write as many @var{messages} as you want to the log. If the arg is a
1109 thunk it will be executed and it's output will be written to the log.
1112 @defun bot:load file
1115 @defun bot:load-module module-spec
1118 @defun bot:use-module module-spec
1121 @defun bot:match-not-channel regex
1122 match-not-channel adds a prefix regex to your @var{regex} so it
1123 doesn't match the sender or channel in a PUBLIC message
1126 @defun bot:match-to-me regex
1127 match-to-me matches text that was addressed to the bot with a
1128 ':', ',', or nothing after the bot name.
1131 @defun bot:sent-to-me? message
1134 @defun bot:ctcp-quote message
1135 Returns the CTCP quoted message
1136 Input @emph{MUST NOT} contain the trailing @code{\r\n}
1137 (it is added by the message sending code).
1141 @defvar %bot:loadpath
1144 @defun %bot:load-extensions
1149 @node Concept Index, Function Index, Scripting, Top
1150 @unnumbered Concept Index
1153 @node Function Index, Variable Index, Concept Index, Top
1154 @unnumbered Function Index
1157 @node Variable Index, , Function Index, Top
1158 @unnumbered Variable Index