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 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 @c @vskip O plus 1filll
28 Copyright @copyright{} 2002 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.0 of the program named
48 Copyright 2002 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 @node Introduction, Configuration, Top, Top
70 This manual feels abused and neglected because it has almost no
73 @node Configuration, Using the Bot, Introduction, Top
74 @chapter Configuration
76 Bobot++ is easy to configure. The configuration file format may be
77 changing in the 2.1 series, so it is not documented for now. See the
78 @file{examples} directory for an example configuration.
81 * Configuration File Syntax::
82 * Configure File Placement::
85 @node Configuration File Syntax, Configure File Placement, Configuration, Configuration
86 @section Configuration File Syntax
90 @node Configure File Placement, , Configuration File Syntax, Configuration
91 @section Configuration File Placement
93 Bobot++ will look in @file{/etc/bobotpp/default/} for its default
94 config if none is specified on the command line. Put the configuration
95 files you want to be loaded by default in this directory. If you are
96 not root or you want to have your own personal configration, put it in
97 @file{~/.bobotpp/config/default/}.
99 @node Using the Bot, Scripting, Configuration, Top
100 @chapter Using Bobot++
108 @node User Levels, , Using the Bot, Using the Bot
111 There are five levels that a user may be when interfacing with a bot:
112 @var{none}, @var{user}, @var{trusted_user}, @var{friend},
113 @var{master}. All users default to @var{none} unless they are changed
114 by a script, the @code{!adduser} command or the @file{bot.users}
115 file. @var{none} is for everyone---very few commands (e.g. help) are
116 available to the users and almost everyone should be this
117 level. A @var{user} can execute many of the bot commands, but can't
118 use masks on kicks and bans. A @var{trusted} user can everything a
119 @var{user} can do, but can also use masks on kicks and bans. A
120 @var{friend} can do everything except for stopping the bot (be
121 careful who you give this to!). The @var{master} level is for the
122 bot's owner (probably you) and can do @emph{everything} to the bot. Be
123 @emph{very} careful if you give @var{master} level access to anyone
124 else. You cannot use this symbolic levels with the @code{!adduser}
125 command. See (FIXME: ref) for the numbers you must use with
128 @node Scripting, Concept Index, Using the Bot, Top
131 Bobot++'s most powerful feature is its scripting system. You write
132 scripts using Guile Scheme. This manual does not cover how to use
133 Guile or how to learn Scheme. @xref{Top, , Guile Reference Manual,
134 guile, The Guile Reference Manual}, for the Guile reference manual and
135 @url{http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html} for
136 a good tutorial on Scheme.
138 Note that in previous versions the scripting commands where in the
139 form @code{bot-@var{function}}. They are now in the form
140 @code{bot:@var{function}}. The old names are still available, but are
141 deprecated and will be removed in Bobot++ 2.4. The command
142 @command{perl -pi -e ``s/bot-/bot:/g'' @var{your-files}} should be enough to
143 convert your code to use the new functions.
146 * Adding New Commands::
148 * Scheme User Levels::
150 * Misc Scripting Stuff::
153 @node Adding New Commands, Hooks, Scripting, Scripting
154 @section Adding New Commands
157 Adding a new command is simple. To register a new command use
158 @code{bot:addcommand}. The prototype for @code{bot:addcommand} is
159 @code{(bot:addcommand name func needs-channel? num-of-args
160 min-level)}. The @code{name} is a string representing the name of the
161 command being added. @code{func} is a function accepting
162 @code{num-of-args} arguments. @code{needs-channel?} is a bool that is
163 true if the function needs the channel name as its first arg, and
164 false otherwise. @code{num-of-args} is the number of args @code{func}
165 will take and must be within zero (0) and twenty
166 (20). @code{min-level} is one of the @ref{Scheme User Levels}. A user must be
167 at least a @code{min-level} user to use the new command. None of the
168 arguments are guaranteed to be passed; if they aren't they are set to
169 the empty string @code{""}. An example of a new command would be:
171 (define (hello channel name)
172 (if (string=? name "")}@*
173 (bot:say channel "Hello world!")
174 (bot:say channel (string-append "Hello " name "!")))
176 (bot:addcommand "hello" hello #t 2 0)
178 This will display ``Hello World!'' if called as @kbd{!hello} and
179 ``Hello World @code{USER}'' if called as @kbd{!hello @var{USER}}.
181 @node Hooks, Scheme User Levels, Adding New Commands, Scripting
184 @cindex Background on Hooks
185 Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
186 hooks and tiny fugue (a MUD bot) hooks. The basic idea of a hook if
187 that you match a text against regular expression and call a function
188 if text in a message matches that regex. The different types of hooks
189 provided by Bobot++ correspond to the different classes of messages
190 that Bobot++ can recieve. A Hook also has several properties,
191 including its priority and whether or not it is a fallthrough
192 hook. Higher priority hooks are executed before lower priority hooks
193 and fallthrough hooks are executed before non-fallthrough hooks of the
194 same priority. A fallthrough hook can match and processing of hooks
195 will continue; as soon as the first non-fallthrough hooks matches
196 processing of hooks stops.
203 @node Creating a Hook, Hook Types, Hooks, Hooks
204 @subsection Creating a Hook
207 To add a new hook you use the function
208 @code{bot:addhook}. @code{bot:addhook} is prototyped as
209 @code{(bot:addhook type regex function pri fall name)}. @code{type}
210 specifies the type of hook (the types of hooks are listed in @ref{Hook
211 Types}). @code{regex} is a standard regular expression. If
212 @code{regex} is matched, @code{function} will be
213 called. @code{function} will take a different number of args depending
214 on the hook type. @code{pri} specifies the priority of the
215 hook---higher priority hooks are executed first. This argument is
216 optional and defaults to @code{0}. @code{fall} is @code{#t} if the
217 hook is a fallthrough hook and @code{#f} is the hook is not a
218 fallthrough hook. This arg is also optional and default to
219 @code{#t}. @code{name} is the optional name of the hook that defaults
220 to ``DEFAULT''. If you set the name then you can have more than one
221 hook that matches the same regexp, as long as they have the same
222 name. E.g. in a log script you could have the regexps for the log
223 function all be @code{".*"} and set their names to @code{"log"} to
224 avoid a conflict with other hooks.
226 @node Hook Types, , Creating a Hook, Hooks
227 @subsection Hook Types
229 Here is a list of the various hooks are notes on each one. The general
234 @code{hooks/name} (this is the Scheme variable name of the hook)
237 Description of the hook
253 That said, here is the list of available hooks:
263 Description of the hook
273 @vindex hooks/nickname
274 @code{hooks/nickname}
277 Description of the hook
287 @vindex hooks/signoff
291 Description of the hook
305 Description of the hook
315 @vindex hooks/ctcp-reply
316 @code{hooks/ctcp-reply}
319 Description of the hook
329 @vindex hooks/disconnect
330 @code{hooks/disconnect}
333 Description of the hook
347 Description of the hook
361 Description of the hook
375 Description of the hook
389 Description of the hook
403 Description of the hook
417 Description of the hook
427 @vindex hooks/message
431 Description of the hook
445 Description of the hook
459 Description of the hook
469 @vindex hooks/public-notice
470 @code{hooks/public-notice}
473 Description of the hook
487 Description of the hook
501 Description of the hook
515 Description of the hook
527 @node Scheme User Levels, Sending Messages, Hooks, Scripting
528 @section Scheme User Levels
535 There are five levels that a user may be when interfacing with a bot:
536 @var{none}, @var{user}, @var{trusted_user}, @var{friend},
537 @var{master}. The Scheme variables for the user levels are
538 @code{bot:user-none}, @code{bot:user-user}, @code{bot:user-trusted},
539 @code{bot:user-friend}, and @code{bot:user-master}. See @ref{User
540 Levels} for more information on User Levels.
542 When adding a new command, think about who should be able to use
543 it. Is your command a general purpose command that helps the channel
544 (e.g. @code{!seen}) that everyone should be able to use? Or is it
545 something that should be restricted? See @ref{User Levels} for
546 information on what level users can do what with the built in bot
547 commands and think about what level a user your command is targetted
548 towards. You must be @emph{very} careful when giving new commands to
549 lower level users because you can do basically everything the bot can
550 do with a script. As the scripting interface becomes more powerful,
551 you must think more about what users can use new commands you add.
553 @node Sending Messages, Misc Scripting Stuff, Scheme User Levels, Scripting
554 @section Sending Messages
556 There are several types of messages you can send with Bobot++ from
557 scripts. There is the simple, but rather limited, @code{bot:say},
558 @code{bot:action} and @code{bot:msg}, and
559 the more powerful, but lower level, @code{bot:send-MESSAGE}
560 functions. Most bots will probably only need the higher level
561 functions, but for the sake of why-not Bobot++ lets you use the lower
565 * High Level Message Functions::
566 * Low Level Message Functions::
569 @node High Level Message Functions, Low Level Message Functions, Sending Messages, Sending Messages
570 @subsection ``High Level'' Message Functions
574 @node Low Level Message Functions, , High Level Message Functions, Sending Messages
575 @subsection ``Low Level'' Message Functions
577 The ``Low Level'' messaging functions allow you to do things like send
578 CTCP messages. You probably want to read rfc 2812 and the CTCP spec
579 before using these. If you have no idea what these do, read rfc 2812
580 (IRC Client Protocol) and CTCP spec. These functions all return
581 @code{*unspecified*} always, so don't use the return value for anything.
585 @item @code{bot:send-CTCP to command message}
586 @code{to} is the target of your CTCP message, @code{command} is the
587 CTCP command, and @code{message} is the message (or arguments) of the
588 command. Make sure to @code{bot:ctcp-quote} the message!
592 @node Misc Scripting Stuff, , Sending Messages, Scripting
593 @section Misc. Scripting Stuff
595 These are a few useful things that I thought people writing scripts
598 If you want to execute code when the bot exits, just do
599 @code{add-hook! bot:exit-hook @var{thunk}} where @var{thunk} is an
600 argumentless procedure (a thunk). When the bot exits your thunk will
603 Since a bot calls hooks on things it says, you have to be careful
604 about hooks that output text that might match itself. E.g. if you have
605 a hook that matches @code{"foo"} and the hook displays @code{"foo to
606 the whatsit?"}, then the hook will call itself over and over until the
607 stack overflows! To protect against this I wrote the macro
608 @code{not-from-me}. You call it like this: @code{(not-from-me from
609 (stmts if not from bot) (stmts if from bot))}. E.g.
612 (bot:addhook hooks/public "foo"
614 (not-from-me f ((bot:say t "foo to the what!")))))
617 This say ``foo to the what!'' to the channel that ``foo'' was said in
618 and do nothing otherwise. You can optionally specify an action to be
619 executed if the message is from the bot:
622 (bot:addhook hooks/public "foo"
624 (not-from-me f ((bot:say t "foo to the what!"))
625 ((bot:say t "moof")))))
628 That will do the same thing as the first example, but the bot will
629 say ``moof'' if it said ``foo'' before. That probably isn't a very
630 nice thing to do, but it works as an example. You can have as many
631 staments as you want in the clauses.
633 @node Concept Index, Function Index, Scripting, Top
634 @unnumbered Concept Index
637 @node Function Index, Variable Index, Concept Index, Top
638 @unnumbered Function Index
641 @node Variable Index, , Function Index, Top
642 @unnumbered Variable Index