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 @vskip Opt 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::
152 @node Adding New Commands, Hooks, Scripting, Scripting
153 @section Adding New Commands
156 Adding a new command is simple. To register a new command use
157 @code{bot:addcommand}. The prototype for @code{bot:addcommand} is
158 @code{(bot:addcommand name func needs-channel? num-of-args
159 min-level)}. The @code{name} is a string representing the name of the
160 command being added. @code{func} is a function accepting
161 @code{num-of-args} arguments. @code{needs-channel?} is a bool that is
162 true if the function needs the channel name as its first arg, and
163 false otherwise. @code{num-of-args} is the number of args @code{func}
164 will take and must be within zero (0) and twenty
165 (20). @code{min-level} is one of the @ref{Scheme User Levels}. A user must be
166 at least a @code{min-level} user to use the new command. None of the
167 arguments are guaranteed to be passed; if they aren't they are set to
168 the empty string @code{""}. An example of a new command would be:
170 (define (hello channel name)
171 (if (string=? name "")}@*
172 (bot:say channel "Hello world!")
173 (bot:say channel (string-append "Hello " name "!")))
175 (bot:addcommand "hello" hello #t 2 0)
177 This will display ``Hello World!'' if called as @kbd{!hello} and
178 ``Hello World @code{USER}'' if called as @kbd{!hello @var{USER}}.
180 @node Hooks, Scheme User Levels, Adding New Commands, Scripting
183 @cindex Background on Hooks
184 Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
185 hooks and tiny fugue (a MUD bot) hooks. The basic idea of a hook if
186 that you match a text against regular expression and call a function
187 if text in a message matches that regex. The different types of hooks
188 provided by Bobot++ correspond to the different classes of messages
189 that Bobot++ can recieve. A Hook also has several properties,
190 including its priority and whether or not it is a fallthrough
191 hook. Higher priority hooks are executed before lower priority hooks
192 and fallthrough hooks are executed before non-fallthrough hooks. A
193 fallthrough hook can match and processing of hooks will continue; as
194 soon as the first non-fallthrough hooks matches processing of hooks
202 @node Creating a Hook, Hook Types, Hooks, Hooks
203 @subsection Creating a Hook
206 To add a new hook you use the function
207 @code{bot:addhook}. @code{bot:addhook} is prototyped as
208 @code{(bot:addhook type regex function pri fall)}. @code{type}
209 specifies the type of hook (the types of hooks are listed in @ref{Hook
210 Types}). @code{regex} is a standard regular expression. If
211 @code{regex} is matched, @code{function} will be
212 called. @code{function} will take a different number of args depending
213 on the hook type. @code{pri} specifies the priority of the
214 hook---higher priority hooks are executed first. This argument is
215 optional and defaults to @code{0}. @code{fall} is @code{#t} if the
216 hook is a fallthrough hook and @code{#f} is the hook is not a
217 fallthrough hook. This arg is also optional and default to @code{#t}.
219 @node Hook Types, , Creating a Hook, Hooks
220 @subsection Hook Types
222 Here is a list of the various hooks are notes on each one. The general
227 @code{hooks/name} (this is the Scheme variable name of the hook)
230 Description of the hook
246 That said, here is the list of available hooks:
256 Description of the hook
266 @vindex hooks/nickname
267 @code{hooks/nickname}
270 Description of the hook
280 @vindex hooks/signoff
284 Description of the hook
298 Description of the hook
308 @vindex hooks/ctcp-reply
309 @code{hooks/ctcp-reply}
312 Description of the hook
322 @vindex hooks/disconnect
323 @code{hooks/disconnect}
326 Description of the hook
340 Description of the hook
354 Description of the hook
368 Description of the hook
382 Description of the hook
396 Description of the hook
410 Description of the hook
420 @vindex hooks/message
424 Description of the hook
438 Description of the hook
452 Description of the hook
462 @vindex hooks/public-notice
463 @code{hooks/public-notice}
466 Description of the hook
480 Description of the hook
494 Description of the hook
508 Description of the hook
520 @node Scheme User Levels, Sending Messages, Hooks, Scripting
521 @section Scheme User Levels
528 There are five levels that a user may be when interfacing with a bot:
529 @var{none}, @var{user}, @var{trusted_user}, @var{friend},
530 @var{master}. The Scheme variables for the user levels are
531 @code{bot:user-none}, @code{bot:user-user}, @code{bot:user-trusted},
532 @code{bot:user-friend}, and @code{bot:user-master}. See @ref{User
533 Levels} for more information on User Levels.
535 When adding a new command, think about who should be able to use
536 it. Is your command a general purpose command that helps the channel
537 (e.g. @code{!seen}) that everyone should be able to use? Or is it
538 something that should be restricted? See @ref{User Levels} for
539 information on what level users can do what with the built in bot
540 commands and think about what level a user your command is targetted
541 towards. You must be @emph{very} careful when giving new commands to
542 lower level users because you can do basically everything the bot can
543 do with a script. As the scripting interface becomes more powerful,
544 you must think more about what users can use new commands you add.
546 @node Sending Messages, , Scheme User Levels, Scripting
547 @section Sending Messages
549 There are several types of messages you can send with Bobot++ from
550 scripts. There is the simple, but rather limited, @code{bot:say},
551 @code{bot:action} and @code{bot:msg}, and
552 the more powerful, but lower level, @code{bot:send-MESSAGE}
553 functions. Most bots will probably only need the higher level
554 functions, but for the sake of why-not Bobot++ lets you use the lower
558 * High Level Message Functions::
559 * Low Level Message Functions::
562 @node High Level Message Functions, Low Level Message Functions, Sending Messages, Sending Messages
563 @subsection ``High Level'' Message Functions
567 @node Low Level Message Functions, , High Level Message Functions, Sending Messages
568 @subsection ``Low Level'' Message Functions
570 The ``Low Level'' messaging functions allow you to do things like send
571 CTCP messages. You probably want to read rfc 2812 and the CTCP spec
572 before using these. If you have no idea what these do, read rfc 2812
573 (IRC Client Protocol) and CTCP spec. These functions all return
574 @code{*unspecified*} always, so don't use the return value for anything.
578 @item @code{bot:send-CTCP to command message}
579 @code{to} is the target of your CTCP message, @code{command} is the
580 CTCP command, and @code{message} is the message (or arguments) of the
581 command. Make sure to @code{bot:ctcp-quote} the message!
585 @node Concept Index, Function Index, Scripting, Top
586 @unnumbered Concept Index
589 @node Function Index, Variable Index, Concept Index, Top
590 @unnumbered Function Index
593 @node Variable Index, , Function Index, Top
594 @unnumbered Variable Index