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 Opt 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 Files::
72 * Configuration File Placement::
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 Files::
127 * Configuration File Placement::
130 @node Configuration Files, Configuration File Placement, Configuration, Configuration
131 @section Configuration Files
138 @node bot.conf, bot.users, Configuration Files, Configuration Files
146 @file{bot.conf} contains key value pairs separated by @code{=}.
148 @code{<key> = <value>}
150 Comments are started with a @code{#} and cause the entire line to be
151 ignored. @emph{Note that this only works when the @code{#} is the first
152 character of the line}.
154 bot.conf is the main configuration file for a Bobot++. The available
155 configuration variables are listed below in the format ``@var{variable}
156 <default-value>: description''
160 @item @var{nickname} <Bobot>: The nickname of the bot (@var{nick} is an
161 alias for @var{nickname})
162 @item @var{username} <bobot>: The IRC username of the bot
163 @item @var{cmdchar} <!>: The character that prefixes commands given to
164 the bot (@var{command} is an alias for @var{cmdchar})
165 @item @var{ircname} <I'm a bobot++!>: The IRC name (or 'real name') of
166 the bot (@var{realname} is an alias for @var{ircname})
167 @item @var{userlist} <bot.users>: Name of the file where the userlist is
169 @item @var{shitlist} <bot.shit>: Name of the file where the shitlist is
171 @item @var{logfile} <$LOGDIR/bot.log>: Location of the bot logfile
172 (set this to @file{/dev/null} to disable logging).
173 @item @var{server} <None>: This specifies the server to connect
174 to. Note that this has a special syntax.
175 @item @var{channel} <None>: This specifies a channel the bot will join
176 when it starts up. This also has a special syntax.
180 @node server syntax, channel syntax, bot.conf, bot.conf
181 @subsubsection server syntax
183 @var{server} = @var{server_name} [@var{port} [@var{password}]]
185 This will make Bobot++ attempt to connect to @var{server_name} on port
186 @var{port} with the password @var{password}. @var{server_name} should
187 be the address of the server. @var{port} and @var{password} are
188 optional. You may use more than one server line; Bobot++ will attempt
189 to connect to the first one and, if it fails, will connect to the next
190 one in the list. There is also a command to cause the bot to cycle
191 servers. At the present time Bobot++ cannot connect to more than one
192 server at a time. This is a planned feature of 3.0 (which is a very
193 long way away; the current structure of the program would make it very
194 difficult to add support for connecting to multiple servers at a time
197 @node channel syntax, , server syntax, bot.conf
198 @subsubsection channel syntax
201 @var{name}:@var{initial_modes}:@var{modes_to_keep}:@var{channel_key}
203 You may have any number of channel lines. When Bobot++ starts it will
204 attempt to join and gain ops in every channel listed. It will join
205 @var{name} and set the channel modes to @var{initial_modes}
206 (e.g. ``nt'') if it is able to gain operator status. It will then
207 maintain @var{modes_to_keep}. If the channel requires a key to enter
208 simply set @var{channel_key}. Every argument except for @var{name} is
213 @code{@var{channel} = #foo:nt:nt:bar}
215 The bot will join @code{#foo} with the channel key @code{bar} and will
216 then maintain the modes @code{nt}.
218 @code{@var{channel} = #bar:::}
220 The bot will join @code{#bar} and will not set any modes nor will it
221 attempt to maintain any modes.
223 @node bot.users, , bot.conf, Configuration Files
224 @subsection bot.users
226 @file{bot.users} is the default file name of the userlist. It may be
227 changed in @file{bot.conf}. The file contains lines with the format:
229 @samp{@var{mask}:@var{channel}:@var{level}:@var{protection}:@var{auto-op}}
233 @item @var{mask} is the host mask
234 (e.g. @samp{*!*username@*.domain.com}) of the user
236 @item @var{channel} is a channel mask of the channels that the user
237 has priviliges to use the bot in (e.g. @samp{*} for all channels,
238 @samp{#*} for all non-local channel, @samp{#foo*} for all channels
239 starting with ``foo,'' @samp{#bar} for channel ``#bar'' only, etc.)
241 @item @var{level} is the user level of the user (@ref{User Levels}).
243 @item @var{protection} is the protection level of the user
246 @item @var{auto-op} is set to control whether a user is automatically
247 given operator priviliges on channel entry (@ref{Automatic Op}).
251 @node Configuration File Placement, , Configuration Files, Configuration
252 @section Configuration File Placement
255 [ I kinda think this should go before the detailed description of the
256 config file. I was didn't see it at first and was very frustrated
257 trying to find out @emph{where} to edit all this wonderful stuff. ]
260 Bobot++ will look in @file{/etc/bobotpp/default/} for its default
261 config if none is specified on the command line. Put the configuration
262 files you want to be loaded by default in this directory. If you are
263 not root or you want to have your own personal configuration, put it
264 in @file{~/.bobotpp/config/default/}.
266 @node Using the Bot, Scripting, Configuration, Top
267 @chapter Using Bobot++
276 * Built-In Commands::
279 @node Starting the Bot, User Levels, Using the Bot, Using the Bot
280 @section Starting the Bot
282 The bot is usually installed with the binary name @file{bobotpp}. It
283 accepts the following command line arguments:
286 @item @code{[--help][-h]} - Shows detailed help and exits
287 @item @code{[--version][-v]} - Shows version information and exits
288 @item @code{[--no-background][-b]} - Run bobot++ in the foreground
289 @item @code{[--config-file file][-f]} - Use file instead of @file{bot.conf}
290 @item @code{[--config-dir dir][-d]} - Use dir as dir to load config file from
291 @item @code{[--config dir][-c]} - Search your config path (defaults to
292 @file{@var{$HOME}/.bobotpp/config/} and then @file{/etc/bobotpp/}) for
293 dir and then loads your config data using dir
294 @item @code{[--sys-config dir][-s]} - Looks for config in
295 @file{/etc/bobotpp/dir}. Note that the user dir is still searched
297 @item @code{[--user-config dir][-u]} - Looks for config in
298 @file{@var{$HOME}/.bobotpp/config/dir/}. Note that the system dir is
299 still searched after this if dir is not found.
300 @item @code{[--debug][-D]} Makes Bobot++ print debugging info and run
304 The default configuration is read from
305 @file{@var{$HOME}/.bobotpp/config/default/} and then
306 @file{/etc/bobotpp/default/} if the user config is not found.
308 The bot defaults to running in the background as a daemon.
310 @node User Levels, Protection, Starting the Bot, Using the Bot
313 There are several user levels available in Bobot++ to provide gradated
314 access to commands. @command{!adduser} and @file{bot.users} use the
315 numeric code; Scheme uses the textual name for the level. By default
316 (if no catch-all setting is found in @xref{bot.users}.) a user is not
317 even a @code{bot:user-none} and cannot execute @strong{any} commands,
318 even commands available to @code{bot:user-none}.
322 @item @code{bot:user-none} - No @strong{built-in} commands may be
323 executed @emph{by default} (commands may be added from Scheme that can
324 be executed by users of level none and the level required to execute a
325 command may be changed from Scheme).
327 @item @code{bot:user-user} - Will be able to execute most commands but
328 not all and cannot use masks on kicks and bans.
330 @item @code{bot:user-trusted} - For built-ins with a default
331 configuration this user has access to the same set of commands as an
332 @code{user} but may use masks on kicks and bans. Scheme commands may
333 be added which require a user to be of this level.
335 @item @code{bot:user-friend} - In the default configuration a user who
336 is a friend will be able to do everything short of stopping the
337 bot. Again, there may be user added commands that require a higher
340 @item @code{bot:user-master} - This is the highest user level and has
341 access to every feature of the bot.
345 @node Protection, Automatic Op, User Levels, Using the Bot
348 A user added via Scheme, the @file{bot.users} file, or
349 @command{!adduser} may be protected from being deoped, kicked, or
350 banned. There are currently no symbolic levels in Scheme; just use the
355 @item No ban. If a user is banned the bot will unban him..
356 @item No kick. The user may still be kicked but the bot will kickban
357 the user who kicked the protected user.
358 @item No deop. The bot will ensure that the user always maintains
362 @node Automatic Op, Built-In Commands, Protection, Using the Bot
363 @section Automatic Op
365 A user may be automatically given operator status upon entering a
366 channel. Set the @var{aop} field to ``0'' to disable auto-op or ``1''
369 @node Built-In Commands, , Automatic Op, Using the Bot
370 @section Built-In Commands
372 Bobot++ has many built-in commands that make it useful without
373 scripting support. The reference leaves off the command char; remember
374 to use whatever you defined the command char to be in
375 @file{bot.conf}. If a command needs the channel name then you must
376 specify the channel as the first argument to the command when private
377 messaging the bot a command.
379 @multitable @columnfractions 0.20 0.15 0.15 0.50
380 @item @sc{command} @tab @sc{Needs Channel} @tab @sc{Min Level to Use} @tab @sc{Description}
382 @item @command{action} @option{do} @tab Yes @tab @var{USER} @tab
383 Causes the bot to perform the action @option{do} in the current
386 @item @command{adduser} @tab @tab @tab
388 @item @command{addserver} @tab @tab @tab Adds the server specified by
389 @var{host name} or @var{ip address} to the server list.
391 @item @command{addshit} @tab @tab @tab
393 @item @command{alias} @tab @tab @tab Makes an alias, and adds the
394 function @var{new name}, that will do exactly the same command as
397 @item @command{ban} @tab @tab @tab Bans @var{mask} or @var{nick} from
398 @var{channel}. You need to be a trusted user to ban with a
401 @item @command{banlist} @tab @tab @tab
403 @item @command{channels} @tab @tab @tab Prints the channel(s) where
404 the bot is currently.
406 @item @command{cycle} @tab Yes @tab @tab Makes the bot leave and join
409 @item @command{dcclist} @tab @tab @tab Gives the list of all DCC Chat
412 @item @command{deban} @tab Yes @tab @tab Debans @var{mask} or
413 @var{nick} from @var{channel}. You need to be a trusted user to deban
416 @item @command{delserver} @tab @tab @tab Deletes server from server
417 list whose number in the server list is @var{server number}.
419 @item @command{deluser} @tab @tab @tab Removes @var{nick} or
420 @var{mask} from the userlist.
422 @item @command{delshit} @tab @tab @tab Removes @var{nick} or
423 @var{mask} from the shitlist.
425 @item @command{deop} @tab Yes @tab @tab Deops @var{mask} or @var{nick}
428 @item @command{die} @tab @tab @tab Makes the bot stop immediately.
430 @item @command{do} @tab @tab @tab
432 @item @command{execute} @tab @tab @tab @strong{Only available if
433 scripting support is enabled}
435 @item @command{help} @tab @tab @tab
437 @item @command{ident} @tab @tab @tab Identifies you on the bot. Note
438 that you should not use this command in public @dots{}
440 @item @command{invite} @tab Yes @tab @tab Invites @var{nick} on
443 @item @command{join} @tab @tab @tab Makes the bot join @var{channel}.
445 @item @command{keep} @tab Yes @tab @tab Sets the @var{modes} that the
446 bot will keep for @var{channel}.
448 @item @command{kick} @tab Yes @tab @tab Kicks @var{mask} or @var{nick}
449 out of @var{channel}, because of @var{reason}. You need to be a
450 trusted user to use a @var{mask}.
452 @item @command{kickban} @tab Yes @tab @tab Bans then kicks @var{mask}
453 or @var{nick} out of @var{channel}, because of @var{reason}. You need
454 to be a trusted user to use a @var{mask}.
456 @item @command{load} @tab @tab @tab Reloads the userlist from disk.
458 @item @command{loadscript} @tab @tab @tab @strong{Only available if
459 scripting support is enabled}
461 @item @command{lock} @tab @tab @tab Locks topic on @var{channel}.
463 @item @command{mode} @tab Yes @tab @tab Sends @var{mode string} as
464 mode for @var{channel}.
466 @item @command{msg} @tab @tab @tab
468 @item @command{names} @tab Yes @tab @tab Shows the nicknames and
469 status of users on @var{channel}.
471 @item @command{nextserver} @tab @tab @tab Makes the bot connect to the
472 next server in its server list.
474 @item @command{nick} @tab @tab @tab Makes the bot use nickname @var{nick}.
476 @item @command{nslookup} @tab @tab @tab Does a nameserver query about
477 @var{nick} host, @var{host} or @var{ip address}.
479 @item @command{op} @tab Yes @tab @tab Ops @var{nick} on @var{channel}.
481 @item @command{part} @tab Yes @tab @tab Makes the bot leave @var{channel}.
483 @item @command{password} @tab @tab @tab Changes your password on the
484 bot. Use @code{NONE} as password if you want to clear it. Do not use this
487 @item @command{reconnect} @tab @tab @tab Makes the bot reconnect to
490 @item @command{rspymessage} @tab @tab @tab Removes you from the spy
493 @item @command{save} @tab @tab @tab Saves the userlist.
495 @item @command{say} @tab Yes @tab @tab Makes the bot say @var{message}
498 @item @command{server} @tab @tab @tab Select the server to connect
499 to. @var{server number} is the number of the server in the serverlist.
501 @item @command{serverlist} @tab @tab @tab Shows the bot's serverlist.
503 @item @command{setfloodrate} @tab @tab @tab
505 @item @command{setversion} @tab @tab @tab
507 @item @command{shitlist} @tab @tab @tab Shows the bot's shitlist.
509 @item @command{spylist} @tab @tab @tab Shows the bot's spylist.
511 @item @command{spymessage} @tab @tab @tab Adds you to the spylist
513 @item @command{stats} @tab Yes @tab @tab Gives @var{channel}'s statistics.
515 @item @command{tban} @tab Yes @tab @tab Bans @var{nick} or @var{mask}
516 from @var{channel} for @var{time} seconds.
518 @item @command{tkban} @tab Yes @tab @tab Bans @var{nick} or @var{mask}
519 from @var{channel} for @var{time} seconds, then kicks him/them because
522 @item @command{topic} @tab Yes @tab @tab If no @var{topic}is given,
523 prints @var{channel}'s topic. Otherwise, the bot will change
524 @var{channel}'s topic to @var{topic}.
526 @item @command{unlock} @tab Yes @tab @tab Makes the bot unlock topic
529 @item @command{userlist} @tab @tab @tab Shows the bot's userlist
531 @item @command{who} @tab Yes @tab @tab Show your level on @var{channel}
533 @item @command{whois} @tab Yes @tab @tab Shows information about
534 @var{nick} on @var{channel}
538 @node Scripting, Concept Index, Using the Bot, Top
541 Bobot++'s most powerful feature is its scripting system. You write
542 scripts using Guile Scheme. This manual does not cover how to use
543 Guile or how to learn Scheme. @xref{Top, , Guile Reference Manual,
544 guile, The Guile Reference Manual}, for the Guile reference manual and
545 @url{http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html} for
546 a good tutorial on Scheme.
548 Note that in previous versions the scripting commands where in the
549 form @code{bot-@var{function}}. They are now in the form
550 @code{bot:@var{function}}. The old names are still available, but are
551 deprecated and will be removed in Bobot++ 3.0. New commands are only
552 available with the @code{bot:} prefix. The command @command{perl -pi
553 -e ``s/bot-/bot:/g'' @var{your-files}} should be enough to convert
554 your code to use the new functions.
557 * Adding New Commands::
559 * Scheme User Levels::
561 * Misc Scripting Stuff::
564 @node Adding New Commands, Hooks, Scripting, Scripting
565 @section Adding New Commands
567 Adding a new command is simple. To register a new command use @code{bot:addcommand}.
569 @defun bot:addcommand name func needs-channel? num-of-args min-level
571 The @var{name} is a string representing the name of the command being
572 added. @var{func} is a function accepting @var{num-of-args}
573 arguments. @var{needs-channel?} is a bool that is true if the function
574 needs the channel name as its first arg, and false otherwise.
575 @var{num-of-args} is the number of args @var{func} will take and must
576 be within zero (0) and twenty (20). @var{min-level} is one of the
577 @ref{Scheme User Levels}. A user must be at least a @code{min-level}
578 user to use the new command. None of the arguments are guaranteed to
579 be passed; if they aren't they are set to the empty string @code{""}.
580 An example of a new command would be:
583 (define (hello channel name)
584 (if (string=? name "")
585 (bot:say channel "Hello world!")
586 (bot:say channel (string-append "Hello " name "!")))
588 (bot:addcommand "hello" hello #t 2 0)
591 This will display ``Hello World!'' if called as @kbd{!hello} and
592 ``Hello World @code{USER}'' if called as @kbd{!hello @var{USER}}.
595 @node Hooks, Scheme User Levels, Adding New Commands, Scripting
598 @cindex Background on Hooks
599 Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
600 and tiny fugue (a MUD bot) hooks with a little bit of extra stuff
601 added in. The basic idea of a hook if that you match a text against
602 regular expression and call a function if text in a message matches
603 that regex. The different types of hooks provided by Bobot++
604 correspond to the different classes of messages that Bobot++ can
605 recieve. A Hook also has several properties, including its priority
606 and whether or not it is a fallthrough hook. Higher priority hooks are
607 executed before lower priority hooks and fallthrough hooks are
608 executed before non-fallthrough hooks of the same priority. A
609 fallthrough hook can match and processing of hooks will continue; as
610 soon as the first non-fallthrough hooks matches processing of hooks
618 @node Creating a Hook, Hook Types, Hooks, Hooks
619 @subsection Creating a Hook
621 To add a new hook you use the function @code{bot:addhook}.
623 @defun bot:addhook type regex function [pri fall name]
624 @var{type} specifies the type of hook (the types of hooks are listed
625 in @ref{Hook Types}). @var{regex} is a standard regular expression. If
626 @var{regex} is matched, @var{function} will be called. @var{function}
627 will take a different number of args depending on the hook
628 type. @var{pri} specifies the priority of the hook---higher priority
629 hooks are executed first. This argument is optional and defaults to
630 @code{0}. @var{fall} is @code{#t} if the hook is a fallthrough hook
631 and @code{#f} is the hook is not a fallthrough hook. This arg is also
632 optional and default to @code{#t}. @var{name} is the optional name of
633 the hook that defaults to ``DEFAULT''. If you set the name then you
634 can have more than one hook that matches the same regexp, as long as
635 they have the same name. E.g. in a log script you could have the
636 regexps for the log function all be @code{".*"} and set their names to
637 @code{"log"} to avoid a conflict with other hooks.
640 @node Hook Types, , Creating a Hook, Hooks
641 @subsection Hook Types
643 Here is a list of the various hooks funtions and notes on each
644 one. The general format of each hook description is as if it was was
645 function to be defined, but these describe the function to be passwd
646 to @code{bot:add-hook}. Do @emph{not} name your functions these
650 [ Boy, that's clumsy. I want to say that the hook/xx functions that
651 are documented below are not funtions that you call. They are the
652 functions that needs to be passed to bot:addhook for that kind of
655 Still clumsy. Oh well. ]
659 That said, here is the list of available hooks functions.
662 @defun hooks/action from to action
663 This hook is triggered when someone performs an action. @var{from} is
664 the address of the person that performed the action in the form
665 @samp{@var{nick} ! @var{user} @@ @var{host}} (without the spaces).
666 @var{to} is the target of the action, which is either a channel or the
667 Bot's nick. @var{action} is the text of the action. E.g. if someone
668 did @samp{* foobar does baz}, then @var{action} would be the string
673 @defun hooks/nickname old-nick new-nick
674 This hook gets called when someone changes thir nickname from
675 @var{old-nick} to @var{new-nick}.
678 @defun hooks/signoff nick rest
681 @defun hooks/ctcp nick to command rest
684 @defun hooks/ctcp-reply nick command rest
687 @defun hooks/disconnect ?
688 [ Is this ever called? I can't find it in the source ]
691 @defun hooks/flood nick
694 @defun hooks/invite nick channel
697 @defun hooks/join nick channel
700 @defun hooks/kick target from channel reason
703 @defun hooks/leave nick channel
704 @defunx hooks/part nick channel
707 @defun hooks/mode nick channel modes
710 @defun hooks/message from message
713 @defun hooks/notice nick message
716 @defun hooks/public from to message
719 @defun hooks/public-notice nick to message
722 @defun hooks/raw raw-message
725 @defun hooks/timer time
726 This hook seems to be called once a minute. @var{time} is in
730 @defun hooks/topic nick channel new-topic
733 @defun hooks/send/public mynick dest message
736 @defun hooks/send/message botnick message
739 @defun hooks/send/action mynick to message
742 @defun hooks/send/ctcp mynick to command message
745 @defun hooks/dcc/chat-begin from
746 This hook is triggered when a user begins a DCC CHAT with the bot.
747 @var{from} is the user's address in the form @samp{nick!user@@host}.
750 @defun hooks/dcc/chat-message from message
751 This hook is triggered when a user sends a message to the bot through
752 a DCC CHAT @var{from} is the user's address in the form
753 @samp{nick!user@@host}. @var{message} is the message the user sent to
757 @node Scheme User Levels, Sending Messages, Hooks, Scripting
758 @section Scheme User Levels
765 There are five levels that a user may be when interfacing with a bot:
766 @var{none}, @var{user}, @var{trusted_user}, @var{friend},
767 @var{master}. The Scheme variables for the user levels are
768 @code{bot:user-none}, @code{bot:user-user}, @code{bot:user-trusted},
769 @code{bot:user-friend}, and @code{bot:user-master}. See @ref{User
770 Levels} for more information on User Levels.
772 When adding a new command, think about who should be able to use
773 it. Is your command a general purpose command that helps the channel
774 (e.g. @code{!seen}) that everyone should be able to use? Or is it
775 something that should be restricted? See @ref{User Levels} for
776 information on what level users can do what with the built in bot
777 commands and think about what level a user your command is targetted
778 towards. You must be @emph{very} careful when giving new commands to
779 lower level users because you can do basically everything the bot can
780 do with a script. As the scripting interface becomes more powerful,
781 you must think more about what users can use new commands you add.
783 @node Sending Messages, Misc Scripting Stuff, Scheme User Levels, Scripting
784 @section Sending Messages
786 There are several types of messages you can send with Bobot++ from
787 scripts. There is the simple, but rather limited, @code{bot:say},
788 @code{bot:action} and @code{bot:msg}, and the more powerful, but lower
789 level, @code{bot:send-MESSAGE} functions. Most bots will probably only
790 need the higher level functions, but for the sake of why-not Bobot++
791 lets you use the lower level functions (in progress).
794 * High Level Message Functions::
795 * Low Level Message Functions::
798 @node High Level Message Functions, Low Level Message Functions, Sending Messages, Sending Messages
799 @subsection ``High Level'' Message Functions
801 @defun bot:say channel message
802 Send a public or private @var{message} to @var{channel}.
804 Sends a normal text message, as if a user had typed it in. The
805 @var{dest} can be a nickname or a channel.
808 @defun bot:action channel message
809 Send an ``action'' type @var{message} to @var{channel}
812 @defun bot:msg nick message
813 The same as if a user typed @code{/msg nick message} to their IRC client.
816 @node Low Level Message Functions, , High Level Message Functions, Sending Messages
817 @subsection ``Low Level'' Message Functions
819 @c Add a url for rfc2812
820 The ``Low Level'' messaging functions allow you to do things like send
821 CTCP messages. You probably want to read rfc 2812 and the CTCP spec
822 before using these. If you have no idea what these do, read rfc 2812
823 (IRC Client Protocol) and CTCP spec. These functions all return
824 @code{*unspecified*} always, so don't use the return value for
827 @defun bot:send-CTCP to command message
828 @code{to} is the target of your CTCP message, @code{command} is the
829 CTCP command, and @code{message} is the message (or arguments) of the
830 command. Make sure to @code{bot:ctcp-quote} the message!
833 @node Misc Scripting Stuff, , Sending Messages, Scripting
834 @section Misc. Scripting Stuff
836 These are a few useful things that I thought people writing scripts
840 If you want to execute code when the bot exits, just do
841 @code{add-hook! bot:exit-hook @var{thunk}} where @var{thunk} is an
842 argumentless procedure (a thunk). When the bot exits your thunk will
846 [ I didn't know where to put any of these, so I jsut stuck them in
849 There probably needs to be several sections added, like dealing with
850 users (kicking, added, etc), dealing with the bot (channels, nickname
851 of the bot, etc), server issues (serverlist), useful tools (nslookup,
856 @defun bot:adduser nick-or-mask cbannel-mask level prot auto-op
857 Adds an user to the userlist, for a @code{nick!user@@host} matching the
858 one given, on a channel matching the @var{channelMask} given.
860 @multitable @columnfractions 0.33 0.33 0.33
861 @item The @var{level} can be: @tab The @var{prot} can be: @tab The @var{auto-op} can be:
862 @item 0 - No level @tab 0 - No protection @tab 0 - No auto-op
863 @item 1 - User @tab 1 - No ban @tab 1 - Op on join
864 @item 2 - Trusted User @tab 2 - No kick @tab
865 @item 3 - Friend @tab 3 - No deop @tab
866 @item 4 - Master @tab @tab
872 @defun bot:addserver hostname ip-address [portnumber]
873 Adds the server specified by @var{hostname} or @var{ip-address} to
878 @defun bot:addshit nick-or-mask channel-mask level [time reason]
879 Adds an user to the shitlist, for a nick!user@@host matching the
880 one given, on a channel matching the @var{channelMask} given.
883 The @var{level} can be:
886 2 - Kick and Ban on join
887 3 - Kick and Ban on join, no deban
893 @defun bot:ban channel mask-or-nick
894 Bans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
895 user to ban with a @var{mask}.
899 @defun bot:change-command-level nick-or-mask channel-mask new-level
900 Gives @var{nick} or @var{mask} level @var{new-level} on channel(s)
901 @var{channel-mask}. Note that you can not change level for someone
902 whose level is greater than yours, and that you can not give a
903 level greater than yours.
907 @defun bot:cycle channel
908 Makes the bot leave and join @var{channel}.
912 @defun bot:deban channel mask-or-nick
913 Debans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
914 user to deban with a @var{mask}.
918 @defun bot:delserver server-number
919 Deletes server from server list whose number in the server list
920 is @var{server-number}
924 @defun bot:deluser nick-or-mask channel-mask
925 Removes @var{nick} or @var{mask} from the userlist.
929 @defun bot:delshit nick-or-mask channel-mask
930 Removes @var{nick} or @var{mask} from the shitlist.
934 @defun bot:deop channel mask-or-nick
935 Deops @var{mask} or @var{nick} on @var{channel}.
939 @defun bot:die reason
940 Makes the bot stop immediately.
948 @defun bot:invite channel nick
949 Invites @var{nick} on @var{channel}.
953 @defun bot:join channel
954 Makes the bot join @var{channel}.
958 @defun bot:keep channel modes
959 Sets the @var{modes} that the bot will keep for @var{channel}.
964 @defun bot:kick channel mask-or-nick [reason]
965 Kicks @var{mask} or @var{nick} out of @var{channel}, because of @var{reason}.
966 You need to be a trusted user to use a @var{mask}.
970 @defun bot:kickban channel mask-or-nick [reason]
971 Bans then kicks @var{mask} or @var{nick} out of @var{channel},
972 because of @var{reason}.
973 You need to be a trusted user to use a @var{mask}.
977 @defun bot:lock channel
978 Locks topic on @var{channel}.
983 [ Probably returns the log port? ]
987 @defun bot:mode channel mode-string
988 Sends @var{mode-string} as mode for @var{channel}.
992 @defun bot:nextserver
993 Makes the bot connect to the next server in its server list.
998 Makes the bot use nickname @var{nick}.
1002 @defun bot:op channel nick
1003 Ops @var{nick} on @var{channel}.
1007 @defun bot:part channel
1008 Makes the bot leave @var{channel}.
1012 @defun bot:reconnect
1013 Makes the bot reconnect to its current server.
1017 @defun bot:server server-number
1018 Select the server to connect to. @var{server-number} is the number of
1019 the server in the serverlist.
1023 @defun bot:setfloodrate ?
1027 @defun bot:setversion ?
1031 @defun bot:tban channel nick-or-mask time
1032 Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds.
1036 @defun bot:tkban channel nick-or-mask time [reason]
1037 Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds,
1038 then kicks him/them because of @var{reason}.
1042 @defun bot:topic channel topic
1043 If no @var{topic} is given, prints @var{channel}'s topic. Otherwise,
1044 the bot will change @var{channel}'s topic to @var{topic}.
1047 @defun bot:unlock channel
1048 Makes the bot unlock topic on @var{channel}.
1052 @defun bot:getnickname
1053 [ Gets the bot's nickname? ]
1057 @defun bot:getserver
1061 @defun bot:getserverlist
1066 [ Flushes the socket to the server? ]
1070 @defun bot:flushport
1071 [ Flushes the log port? ]
1076 [ Returns a random number? What range? Why? ]
1080 @defun bot:delcommand
1081 [ Probably deletes a command added with @code{bot:addcommand} ? ]
1085 @defun bot:addtimer ? ?
1089 @defun bot:deltimer ?
1093 @defun bot:dcc-chat-send ? ?
1097 [ And what about the stuff defined in @file{bobot-utils.scm} ? I just
1098 added it here so it could be somewhere. There should also be a
1099 section dealing with modules. How to use them. What module scripts
1100 are in. What module bobot++ provided primites are in. And so on. ]
1103 @defun bot:log . messages
1104 Write as many @var{messages} as you want to the log. If the arg is a
1105 thunk it will be executed and it's output will be written to the log.
1108 @defun bot:load file
1111 @defun bot:load-module module-spec
1114 @defun bot:use-module module-spec
1117 @defun bot:match-not-channel regex
1118 match-not-channel adds a prefix regex to your @var{regex} so it
1119 doesn't match the sender or channel in a PUBLIC message
1122 @defun bot:match-to-me regex
1123 match-to-me matches text that was addressed to the bot with a
1124 ':', ',', or nothing after the bot name.
1127 @defun bot:sent-to-me? message
1130 @defun bot:ctcp-quote message
1131 Returns the CTCP quoted message
1132 Input @emph{MUST NOT} contain the trailing @code{\r\n}
1133 (it is added by the message sending code).
1137 @defvar %bot:loadpath
1140 @defun %bot:load-extensions
1145 @node Concept Index, Function Index, Scripting, Top
1146 @unnumbered Concept Index
1149 @node Function Index, Variable Index, Concept Index, Top
1150 @unnumbered Function Index
1153 @node Variable Index, , Function Index, Top
1154 @unnumbered Variable Index