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
568 @code{bot:addcommand}.
570 @defun bot:addcommand name func needs-channel? num-of-args min-level
572 The @var{name} is a string representing the name of the command being
573 added. @var{func} is a function accepting @var{num-of-args}
574 arguments. @var{needs-channel?} is a bool that is true if the function
575 needs the channel name as its first arg, and false otherwise.
576 @var{num-of-args} is the number of args @var{func} will take and must
577 be within zero (0) and twenty (20). @var{min-level} is one of the
578 @ref{Scheme User Levels}. A user must be at least a @code{min-level}
579 user to use the new command. None of the arguments are guaranteed to
580 be passed; if they aren't they are set to the empty string @code{""}.
581 An example of a new command would be:
584 (define (hello channel name)
585 (if (string=? name "")
586 (bot:say channel "Hello world!")
587 (bot:say channel (string-append "Hello " name "!")))
589 (bot:addcommand "hello" hello #t 2 0)
592 This will display ``Hello World!'' if called as @kbd{!hello} and
593 ``Hello World @code{USER}'' if called as @kbd{!hello @var{USER}}.
596 @node Hooks, Scheme User Levels, Adding New Commands, Scripting
599 @cindex Background on Hooks
600 Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
601 and tiny fugue (a MUD bot) hooks with a little bit of extra stuff
602 added in. A hook is called when a regular expression is matched
603 against a message sent to or by the bot.
605 Bobot++ uses different hook types for each IRC message type, and also
606 includes a hook for accessing raw irc messages. Hooks are tagged with
607 a priority and a flag that specifies whether to call the next hook
608 that matches after calling the current one or to stop
611 Hooks are processed from the highest to lowest priority, with
612 fallthrough hooks of equal priority to non-fallthrough hooks being
620 @node Creating a Hook, Hook Types, Hooks, Hooks
621 @subsection Creating a Hook
623 To add a new hook you use the function @code{bot:addhook}.
625 @defun bot:addhook type regex function [pri fall name]
626 @var{type} specifies the type of hook (the types of hooks are listed
627 in @ref{Hook Types}). @var{regex} is a standard regular expression. If
628 @var{regex} is matched, @var{function} will be called. @var{function}
629 will take a different number of args depending on the hook
630 type. @var{pri} specifies the priority of the hook---higher priority
631 hooks are executed first. This argument is optional and defaults to
632 @code{0}. @var{fall} is @code{#t} if the hook is a fallthrough hook
633 and @code{#f} is the hook is not a fallthrough hook. This arg is also
634 optional and default to @code{#t}. @var{name} is the optional name of
635 the hook that defaults to ``DEFAULT''. If you set the name then you
636 can have more than one hook that matches the same regexp, as long as
637 they have the same name. E.g. in a log script you could have the
638 regexps for the log function all be @code{".*"} and set their names to
639 @code{"log"} to avoid a conflict with other hooks.
642 @node Hook Types, , Creating a Hook, Hooks
643 @subsection Hook Types
645 Here is a list of the various hooks funtions and notes on each
646 one. The general format of each hook description is as if it was was
647 function to be defined, but these describe the function to be passwd
648 to @code{bot:add-hook}. Do @emph{not} name your functions these
652 [ Boy, that's clumsy. I want to say that the hook/xx functions that
653 are documented below are not funtions that you call. They are the
654 functions that needs to be passed to bot:addhook for that kind of
657 Still clumsy. Oh well. ]
661 That said, here is the list of available hooks functions.
664 @defun hooks/action from to action
665 This hook is triggered when someone performs an action. @var{from} is
666 the address of the person that performed the action in the form
667 @samp{@var{nick} ! @var{user} @@ @var{host}} (without the spaces).
668 @var{to} is the target of the action, which is either a channel or the
669 Bot's nick. @var{action} is the text of the action. E.g. if someone
670 did @samp{* foobar does baz}, then @var{action} would be the string
675 @defun hooks/nickname old-nick new-nick
676 This hook gets called when someone changes thir nickname from
677 @var{old-nick} to @var{new-nick}.
680 @defun hooks/signoff nick rest
683 @defun hooks/ctcp nick to command rest
686 @defun hooks/ctcp-reply nick command rest
689 @defun hooks/disconnect server
690 This is called when the bot is disconnected from a server
691 unintentionally. @code{hooks/signoff} is called when the bot purposefully
692 disconnected. The hook function is passed the hostname of the
693 server it was disconnected from.
696 @defun hooks/flood nick
699 @defun hooks/invite nick channel
702 @defun hooks/join nick channel
705 @defun hooks/kick target from channel reason
708 @defun hooks/leave nick channel
709 @defunx hooks/part nick channel
712 @defun hooks/mode nick channel modes
715 @defun hooks/message from message
718 @defun hooks/notice nick message
721 @defun hooks/public from to message
724 @defun hooks/public-notice nick to message
727 @defun hooks/raw raw-message
730 @defun hooks/timer time
731 This hook seems to be called once a minute. @var{time} is in
735 @defun hooks/topic nick channel new-topic
738 @defun hooks/send/public mynick dest message
741 @defun hooks/send/message botnick message
744 @defun hooks/send/action mynick to message
747 @defun hooks/send/ctcp mynick to command message
750 @defun hooks/dcc/chat-begin from
751 This hook is triggered when a user begins a DCC CHAT with the bot.
752 @var{from} is the user's address in the form @samp{nick!user@@host}.
755 @defun hooks/dcc/chat-message from message
756 This hook is triggered when a user sends a message to the bot through
757 a DCC CHAT @var{from} is the user's address in the form
758 @samp{nick!user@@host}. @var{message} is the message the user sent to
762 @node Scheme User Levels, Sending Messages, Hooks, Scripting
763 @section Scheme User Levels
770 There are five levels that a user may be when interfacing with a bot:
771 @var{none}, @var{user}, @var{trusted_user}, @var{friend},
772 @var{master}. The Scheme variables for the user levels are
773 @code{bot:user-none}, @code{bot:user-user}, @code{bot:user-trusted},
774 @code{bot:user-friend}, and @code{bot:user-master}. See @ref{User
775 Levels} for more information on User Levels.
777 When adding a new command, think about who should be able to use
778 it. Is your command a general purpose command that helps the channel
779 (e.g. @code{!seen}) that everyone should be able to use? Or is it
780 something that should be restricted? See @ref{User Levels} for
781 information on what level users can do what with the built in bot
782 commands and think about what level a user your command is targetted
783 towards. You must be @emph{very} careful when giving new commands to
784 lower level users because you can do basically everything the bot can
785 do with a script. As the scripting interface becomes more powerful,
786 you must think more about what users can use new commands you add.
788 @node Sending Messages, Misc Scripting Stuff, Scheme User Levels, Scripting
789 @section Sending Messages
791 There are several types of messages you can send with Bobot++ from
792 scripts. There is the simple, but rather limited, @code{bot:say},
793 @code{bot:action} and @code{bot:msg}, and the more powerful, but lower
794 level, @code{bot:send-MESSAGE} functions. Most bots will probably only
795 need the higher level functions, but for the sake of why-not Bobot++
796 lets you use the lower level functions (in progress).
799 * High Level Message Functions::
800 * Low Level Message Functions::
803 @node High Level Message Functions, Low Level Message Functions, Sending Messages, Sending Messages
804 @subsection ``High Level'' Message Functions
806 @defun bot:say channel message
807 Send a public or private @var{message} to @var{channel}.
809 Sends a normal text message, as if a user had typed it in. The
810 @var{dest} can be a nickname or a channel.
813 @defun bot:action channel message
814 Send an ``action'' type @var{message} to @var{channel}
817 @defun bot:msg nick message
818 The same as if a user typed @code{/msg nick message} to their IRC client.
821 @defun bot:notice target message
822 Sends @var{message} as a NOTICE to @var{target}. @var{target} may be a
823 user (nick) or a channel. This returns 0 on success.
826 @node Low Level Message Functions, , High Level Message Functions, Sending Messages
827 @subsection ``Low Level'' Message Functions
829 @c Add a url for rfc2812
830 The ``Low Level'' messaging functions allow you to do things like send
831 CTCP messages. You probably want to read rfc 2812 and the CTCP spec
832 before using these. If you have no idea what these do, read rfc 2812
833 (IRC Client Protocol) and CTCP spec. These functions all return
834 @code{*unspecified*} always, so don't use the return value for
837 @defun bot:send-CTCP to command message
838 @code{to} is the target of your CTCP message, @code{command} is the
839 CTCP command, and @code{message} is the message (or arguments) of the
840 command. Make sure to @code{bot:ctcp-quote} the message!
843 @node Misc Scripting Stuff, , Sending Messages, Scripting
844 @section Misc. Scripting Stuff
846 These are a few useful things that I thought people writing scripts
850 If you want to execute code when the bot exits, just do
851 @code{add-hook! bot:exit-hook @var{thunk}} where @var{thunk} is an
852 argumentless procedure (a thunk). When the bot exits your thunk will
856 [ I didn't know where to put any of these, so I jsut stuck them in
859 There probably needs to be several sections added, like dealing with
860 users (kicking, added, etc), dealing with the bot (channels, nickname
861 of the bot, etc), server issues (serverlist), useful tools (nslookup,
866 @defun bot:adduser nick-or-mask cbannel-mask level prot auto-op
867 Adds an user to the userlist, for a @code{nick!user@@host} matching the
868 one given, on a channel matching the @var{channelMask} given.
870 @multitable @columnfractions 0.33 0.33 0.33
871 @item The @var{level} can be: @tab The @var{prot} can be: @tab The @var{auto-op} can be:
872 @item 0 - No level @tab 0 - No protection @tab 0 - No auto-op
873 @item 1 - User @tab 1 - No ban @tab 1 - Op on join
874 @item 2 - Trusted User @tab 2 - No kick @tab
875 @item 3 - Friend @tab 3 - No deop @tab
876 @item 4 - Master @tab @tab
882 @defun bot:addserver hostname ip-address [portnumber]
883 Adds the server specified by @var{hostname} or @var{ip-address} to
888 @defun bot:addshit nick-or-mask channel-mask level [time reason]
889 Adds an user to the shitlist, for a nick!user@@host matching the
890 one given, on a channel matching the @var{channelMask} given.
893 The @var{level} can be:
896 2 - Kick and Ban on join
897 3 - Kick and Ban on join, no deban
903 @defun bot:ban channel mask-or-nick
904 Bans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
905 user to ban with a @var{mask}.
909 @defun bot:change-command-level nick-or-mask channel-mask new-level
910 Gives @var{nick} or @var{mask} level @var{new-level} on channel(s)
911 @var{channel-mask}. Note that you can not change level for someone
912 whose level is greater than yours, and that you can not give a
913 level greater than yours.
917 @defun bot:cycle channel
918 Makes the bot leave and join @var{channel}.
922 @defun bot:deban channel mask-or-nick
923 Debans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
924 user to deban with a @var{mask}.
928 @defun bot:delserver server-number
929 Deletes server from server list whose number in the server list
930 is @var{server-number}
934 @defun bot:deluser nick-or-mask channel-mask
935 Removes @var{nick} or @var{mask} from the userlist.
939 @defun bot:delshit nick-or-mask channel-mask
940 Removes @var{nick} or @var{mask} from the shitlist.
944 @defun bot:deop channel mask-or-nick
945 Deops @var{mask} or @var{nick} on @var{channel}.
949 @defun bot:die reason
950 Makes the bot stop immediately.
958 @defun bot:invite channel nick
959 Invites @var{nick} on @var{channel}.
963 @defun bot:join channel
964 Makes the bot join @var{channel}.
968 @defun bot:keep channel modes
969 Sets the @var{modes} that the bot will keep for @var{channel}.
974 @defun bot:kick channel mask-or-nick [reason]
975 Kicks @var{mask} or @var{nick} out of @var{channel}, because of @var{reason}.
976 You need to be a trusted user to use a @var{mask}.
980 @defun bot:kickban channel mask-or-nick [reason]
981 Bans then kicks @var{mask} or @var{nick} out of @var{channel},
982 because of @var{reason}.
983 You need to be a trusted user to use a @var{mask}.
987 @defun bot:lock channel
988 Locks topic on @var{channel}.
993 [ Probably returns the log port? ]
997 @defun bot:mode channel mode-string
998 Sends @var{mode-string} as mode for @var{channel}.
1002 @defun bot:nextserver
1003 Makes the bot connect to the next server in its server list.
1007 @defun bot:nick nick
1008 Makes the bot use nickname @var{nick}.
1012 @defun bot:op channel nick
1013 Ops @var{nick} on @var{channel}.
1017 @defun bot:part channel
1018 Makes the bot leave @var{channel}.
1022 @defun bot:reconnect
1023 Makes the bot reconnect to its current server.
1027 @defun bot:server server-number
1028 Select the server to connect to. @var{server-number} is the number of
1029 the server in the serverlist.
1033 @defun bot:setfloodrate ?
1037 @defun bot:setversion ?
1041 @defun bot:tban channel nick-or-mask time
1042 Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds.
1046 @defun bot:tkban channel nick-or-mask time [reason]
1047 Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds,
1048 then kicks him/them because of @var{reason}.
1052 @defun bot:topic channel topic
1053 If no @var{topic} is given, prints @var{channel}'s topic. Otherwise,
1054 the bot will change @var{channel}'s topic to @var{topic}.
1057 @defun bot:unlock channel
1058 Makes the bot unlock topic on @var{channel}.
1062 @defun bot:getnickname
1063 [ Gets the bot's nickname? ]
1067 @defun bot:getserver
1071 @defun bot:getserverlist
1076 [ Flushes the socket to the server? ]
1080 @defun bot:flushport
1081 [ Flushes the log port? ]
1086 [ Returns a random number? What range? Why? ]
1090 @defun bot:delcommand
1091 [ Probably deletes a command added with @code{bot:addcommand} ? ]
1095 @defun bot:addtimer ? ?
1099 @defun bot:deltimer ?
1103 @defun bot:dcc-chat-send ? ?
1107 [ And what about the stuff defined in @file{bobot-utils.scm} ? I just
1108 added it here so it could be somewhere. There should also be a
1109 section dealing with modules. How to use them. What module scripts
1110 are in. What module bobot++ provided primites are in. And so on. ]
1113 @defun bot:log . messages
1114 Write as many @var{messages} as you want to the log. If the arg is a
1115 thunk it will be executed and it's output will be written to the log.
1118 @defun bot:load file
1121 @defun bot:load-module module-spec
1124 @defun bot:use-module module-spec
1127 @defun bot:match-not-channel regex
1128 match-not-channel adds a prefix regex to your @var{regex} so it
1129 doesn't match the sender or channel in a PUBLIC message
1132 @defun bot:match-to-me regex
1133 match-to-me matches text that was addressed to the bot with a
1134 ':', ',', or nothing after the bot name.
1137 @defun bot:sent-to-me? message
1140 @defun bot:ctcp-quote message
1141 Returns the CTCP quoted message
1142 Input @emph{MUST NOT} contain the trailing @code{\r\n}
1143 (it is added by the message sending code).
1147 @defvar %bot:loadpath
1150 @defun %bot:load-extensions
1155 @node Concept Index, Function Index, Scripting, Top
1156 @unnumbered Concept Index
1159 @node Function Index, Variable Index, Concept Index, Top
1160 @unnumbered Function Index
1163 @node Variable Index, , Function Index, Top
1164 @unnumbered Variable Index