bobot++.info

   1 This is bobot++.info, produced by makeinfo version 4.1 from
   2 bobot++.texinfo.
   3
   4    This file documents Bobot++ by Clinton Ebadi and Etienne Bernard
   5 (original author, no longer works on program).
   6
   7    Copyright 2002 Clinton Ebadi
   8
   9    Permission is granted to copy, distribute and/or modify this document
  10 under the terms of the GNU Free Documentation License, Version 1.1 or
  11 any later version published by the Free Software Foundation; with no
  12 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
  13 Texts.
  14
  15 \1f
  16 File: bobot++.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
  17
  18    This document describes Bobot++ by Clinton Ebadi and Etienne Bernard
  19 (original author, no longer works on program).
  20
  21    This document applies to version 2.1.0 of the program named Bobot++
  22
  23    Copyright 2002 Clinton Ebadi
  24
  25    Permission is granted to copy, distribute and/or modify this document
  26 under the terms of the GNU Free Documentation License, Version 1.1 or
  27 any later version published by the Free Software Foundation; with no
  28 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
  29 Texts.
  30
  31 * Menu:
  32
  33 * Introduction::
  34 * Configuration::
  35 * Using the Bot::
  36 * Scripting::
  37 * Concept Index::
  38 * Function Index::
  39 * Variable Index::
  40
  41 \1f
  42 File: bobot++.info,  Node: Introduction,  Next: Configuration,  Prev: Top,  Up: Top
  43
  44 Introduction
  45 ************
  46
  47    This manual feels abused and neglected because it has almost no
  48 content.
  49
  50 \1f
  51 File: bobot++.info,  Node: Configuration,  Next: Using the Bot,  Prev: Introduction,  Up: Top
  52
  53 Configuration
  54 *************
  55
  56    Bobot++ is easy to configure. The configuration file format may be
  57 changing in the 2.1 series, so it is not documented for now. See the
  58 `examples' directory for an example configuration.
  59
  60 * Menu:
  61
  62 * Configuration File Syntax::
  63 * Configure File Placement::
  64
  65 \1f
  66 File: bobot++.info,  Node: Configuration File Syntax,  Next: Configure File Placement,  Prev: Configuration,  Up: Configuration
  67
  68 Configuration File Syntax
  69 =========================
  70
  71    Not here yet.
  72
  73 \1f
  74 File: bobot++.info,  Node: Configure File Placement,  Prev: Configuration File Syntax,  Up: Configuration
  75
  76 Configuration File Placement
  77 ============================
  78
  79    Bobot++ will look in `/etc/bobotpp/default/' for its default config
  80 if none is specified on the command line. Put the configuration files
  81 you want to be loaded by default in this directory. If you are not root
  82 or you want to have your own personal configration, put it in
  83 `~/.bobotpp/config/default/'.
  84
  85 \1f
  86 File: bobot++.info,  Node: Using the Bot,  Next: Scripting,  Prev: Configuration,  Up: Top
  87
  88 Using Bobot++
  89 *************
  90
  91    FIXME: stuff here...
  92
  93 * Menu:
  94
  95 * User Levels::
  96
  97 \1f
  98 File: bobot++.info,  Node: User Levels,  Prev: Using the Bot,  Up: Using the Bot
  99
 100 User Levels
 101 ===========
 102
 103    There are five levels that a user may be when interfacing with a bot:
 104 NONE, USER, TRUSTED_USER, FRIEND, MASTER. All users default to NONE
 105 unless they are changed by a script, the `!adduser' command or the
 106 `bot.users' file. NONE is for everyone--very few commands (e.g. help)
 107 are available to the users and almost everyone should be this level. A
 108 USER can execute many of the bot commands, but can't use masks on kicks
 109 and bans. A TRUSTED user can everything a USER can do, but can also use
 110 masks on kicks and bans. A FRIEND can do everything except for stopping
 111 the bot (be careful who you give this to!). The MASTER level is for the
 112 bot's owner (probably you) and can do _everything_ to the bot. Be
 113 _very_ careful if you give MASTER level access to anyone else. You
 114 cannot use this symbolic levels with the `!adduser' command. See
 115 (FIXME: ref) for the numbers you must use with `!adduser'.
 116
 117 \1f
 118 File: bobot++.info,  Node: Scripting,  Next: Concept Index,  Prev: Using the Bot,  Up: Top
 119
 120 Scripting
 121 *********
 122
 123    Bobot++'s most powerful feature is its scripting system. You write
 124 scripts using Guile Scheme. This manual does not cover how to use Guile
 125 or how to learn Scheme. *Note Guile Reference Manual: (guile)Top, for
 126 the Guile reference manual and
 127 <http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html> for a
 128 good tutorial on Scheme.
 129
 130    Note that in previous versions the scripting commands where in the
 131 form `bot-FUNCTION'. They are now in the form `bot:FUNCTION'. The old
 132 names are still available, but are deprecated and will be removed in
 133 Bobot++ 2.4. The command `perl -pi -e ``s/bot-/bot:/g'' YOUR-FILES'
 134 should be enough to convert your code to use the new functions.
 135
 136 * Menu:
 137
 138 * Adding New Commands::
 139 * Hooks::
 140 * Scheme User Levels::
 141 * Sending Messages::
 142
 143 \1f
 144 File: bobot++.info,  Node: Adding New Commands,  Next: Hooks,  Prev: Scripting,  Up: Scripting
 145
 146 Adding New Commands
 147 ===================
 148
 149    Adding a new command is simple. To register a new command use
 150 `bot:addcommand'. The prototype for `bot:addcommand' is
 151 `(bot:addcommand name func needs-channel? num-of-args min-level)'. The
 152 `name' is a string representing the name of the command being added.
 153 `func' is a function accepting `num-of-args' arguments.
 154 `needs-channel?' is a bool that is true if the function needs the
 155 channel name as its first arg, and false otherwise. `num-of-args' is
 156 the number of args `func' will take and must be within zero (0) and
 157 twenty (20). `min-level' is one of the *Note Scheme User Levels::. A
 158 user must be at least a `min-level' user to use the new command. None
 159 of the arguments are guaranteed to be passed; if they aren't they are
 160 set to the empty string `""'. An example of a new command would be:
 161 (define (hello channel name)   (if (string=? name "")}@*     (bot:say
 162 channel "Hello world!")      (bot:say channel (string-append "Hello "
 163 name "!")))
 164
 165    (bot:addcommand "hello" hello #t 2 0)
 166
 167    This will display ``Hello World!'' if called as !hello and ``Hello
 168 World `USER''' if called as !hello USER.
 169
 170 \1f
 171 File: bobot++.info,  Node: Hooks,  Next: Scheme User Levels,  Prev: Adding New Commands,  Up: Scripting
 172
 173 Hooks
 174 =====
 175
 176    Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
 177 hooks and tiny fugue (a MUD bot) hooks. The basic idea of a hook if
 178 that you match a text against regular expression and call a function if
 179 text in a message matches that regex. The different types of hooks
 180 provided by Bobot++ correspond to the different classes of messages
 181 that Bobot++ can recieve. A Hook also has several properties, including
 182 its priority and whether or not it is a fallthrough hook. Higher
 183 priority hooks are executed before lower priority hooks and fallthrough
 184 hooks are executed before non-fallthrough hooks of the same priority. A
 185 fallthrough hook can match and processing of hooks will continue; as
 186 soon as the first non-fallthrough hooks matches processing of hooks
 187 stops.
 188
 189 * Menu:
 190
 191 * Creating a Hook::
 192 * Hook Types::
 193
 194 \1f
 195 File: bobot++.info,  Node: Creating a Hook,  Next: Hook Types,  Prev: Hooks,  Up: Hooks
 196
 197 Creating a Hook
 198 ---------------
 199
 200    To add a new hook you use the function `bot:addhook'. `bot:addhook'
 201 is prototyped as `(bot:addhook type regex function pri fall)'. `type'
 202 specifies the type of hook (the types of hooks are listed in *Note Hook
 203 Types::). `regex' is a standard regular expression. If `regex' is
 204 matched, `function' will be called. `function' will take a different
 205 number of args depending on the hook type. `pri' specifies the priority
 206 of the hook---higher priority hooks are executed first. This argument is
 207 optional and defaults to `0'. `fall' is `#t' if the hook is a
 208 fallthrough hook and `#f' is the hook is not a fallthrough hook. This
 209 arg is also optional and default to `#t'.
 210
 211 \1f
 212 File: bobot++.info,  Node: Hook Types,  Prev: Creating a Hook,  Up: Hooks
 213
 214 Hook Types
 215 ----------
 216
 217    Here is a list of the various hooks are notes on each one. The
 218 general format of a hook is:
 219
 220    * `hooks/name' (this is the Scheme variable name of the hook)
 221         - Description of the hook
 222
 223         - # of args
 224              - `arg1': desc
 225
 226              - `arg2': desc
 227
 228              - ...
 229
 230              - `argN': desc
 231
 232    That said, here is the list of available hooks: FIXME: write docs
 233
 234    * `hooks/action'
 235         - Description of the hook
 236
 237         - # of args
 238              - `arg1': desc
 239
 240    * `hooks/nickname'
 241         - Description of the hook
 242
 243         - # of args
 244              - `arg1': desc
 245
 246    * `hooks/signoff'
 247         - Description of the hook
 248
 249         - # of args
 250              - `arg1': desc
 251
 252    * `hooks/ctcp'
 253         - Description of the hook
 254
 255         - # of args
 256              - `arg1': desc
 257
 258    * `hooks/ctcp-reply'
 259         - Description of the hook
 260
 261         - # of args
 262              - `arg1': desc
 263
 264    * `hooks/disconnect'
 265         - Description of the hook
 266
 267         - # of args
 268              - `arg1': desc
 269
 270    * `hooks/flood'
 271         - Description of the hook
 272
 273         - # of args
 274              - `arg1': desc
 275
 276    * `hooks/invite'
 277         - Description of the hook
 278
 279         - # of args
 280              - `arg1': desc
 281
 282    * `hooks/join'
 283         - Description of the hook
 284
 285         - # of args
 286              - `arg1': desc
 287
 288    * `hooks/kick'
 289         - Description of the hook
 290
 291         - # of args
 292              - `arg1': desc
 293
 294    * `hooks/part'
 295         - Description of the hook
 296
 297         - # of args
 298              - `arg1': desc
 299
 300    * `hooks/mode'
 301         - Description of the hook
 302
 303         - # of args
 304              - `arg1': desc
 305
 306    * `hooks/message'
 307         - Description of the hook
 308
 309         - # of args
 310              - `arg1': desc
 311
 312    * `hooks/notice'
 313         - Description of the hook
 314
 315         - # of args
 316              - `arg1': desc
 317
 318    * `hooks/public'
 319         - Description of the hook
 320
 321         - # of args
 322              - `arg1': desc
 323
 324    * `hooks/public-notice'
 325         - Description of the hook
 326
 327         - # of args
 328              - `arg1': desc
 329
 330    * `hooks/raw'
 331         - Description of the hook
 332
 333         - # of args
 334              - `arg1': desc
 335
 336    * `hooks/timer'
 337         - Description of the hook
 338
 339         - # of args
 340              - `arg1': desc
 341
 342    * `hooks/topic'
 343         - Description of the hook
 344
 345         - # of args
 346              - `arg1': desc
 347
 348
 349 \1f
 350 File: bobot++.info,  Node: Scheme User Levels,  Next: Sending Messages,  Prev: Hooks,  Up: Scripting
 351
 352 Scheme User Levels
 353 ==================
 354
 355    There are five levels that a user may be when interfacing with a bot:
 356 NONE, USER, TRUSTED_USER, FRIEND, MASTER. The Scheme variables for the
 357 user levels are `bot:user-none', `bot:user-user', `bot:user-trusted',
 358 `bot:user-friend', and `bot:user-master'. See *Note User Levels:: for
 359 more information on User Levels.
 360
 361    When adding a new command, think about who should be able to use it.
 362 Is your command a general purpose command that helps the channel (e.g.
 363 `!seen') that everyone should be able to use? Or is it something that
 364 should be restricted? See *Note User Levels:: for information on what
 365 level users can do what with the built in bot commands and think about
 366 what level a user your command is targetted towards. You must be _very_
 367 careful when giving new commands to lower level users because you can
 368 do basically everything the bot can do with a script. As the scripting
 369 interface becomes more powerful, you must think more about what users
 370 can use new commands you add.
 371
 372 \1f
 373 File: bobot++.info,  Node: Sending Messages,  Prev: Scheme User Levels,  Up: Scripting
 374
 375 Sending Messages
 376 ================
 377
 378    There are several types of messages you can send with Bobot++ from
 379 scripts. There is the simple, but rather limited, `bot:say',
 380 `bot:action' and `bot:msg', and the more powerful, but lower level,
 381 `bot:send-MESSAGE' functions. Most bots will probably only need the
 382 higher level functions, but for the sake of why-not Bobot++ lets you
 383 use the lower level functions.
 384
 385 * Menu:
 386
 387 * High Level Message Functions::
 388 * Low Level Message Functions::
 389
 390 \1f
 391 File: bobot++.info,  Node: High Level Message Functions,  Next: Low Level Message Functions,  Prev: Sending Messages,  Up: Sending Messages
 392
 393 ``High Level'' Message Functions
 394 --------------------------------
 395
 396    ...
 397
 398 \1f
 399 File: bobot++.info,  Node: Low Level Message Functions,  Prev: High Level Message Functions,  Up: Sending Messages
 400
 401 ``Low Level'' Message Functions
 402 -------------------------------
 403
 404    The ``Low Level'' messaging functions allow you to do things like
 405 send CTCP messages. You probably want to read rfc 2812 and the CTCP spec
 406 before using these. If you have no idea what these do, read rfc 2812
 407 (IRC Client Protocol) and CTCP spec. These functions all return
 408 `*unspecified*' always, so don't use the return value for anything.
 409
 410    * `bot:send-CTCP to command message' `to' is the target of your CTCP
 411      message, `command' is the CTCP command, and `message' is the
 412      message (or arguments) of the command. Make sure to
 413      `bot:ctcp-quote' the message!
 414
 415
 416 \1f
 417 File: bobot++.info,  Node: Concept Index,  Next: Function Index,  Prev: Scripting,  Up: Top
 418
 419 Concept Index
 420 *************
 421
 422 * Menu:
 423
 424 * Background on Hooks:                   Hooks.
 425
 426 \1f
 427 File: bobot++.info,  Node: Function Index,  Next: Variable Index,  Prev: Concept Index,  Up: Top
 428
 429 Function Index
 430 **************
 431
 432 * Menu:
 433
 434 * addcommand:                            Adding New Commands.
 435 * addhook:                               Creating a Hook.
 436
 437 \1f
 438 File: bobot++.info,  Node: Variable Index,  Prev: Function Index,  Up: Top
 439
 440 Variable Index
 441 **************
 442
 443 * Menu:
 444
 445 * hooks/action:                          Hook Types.
 446 * hooks/ctcp:                            Hook Types.
 447 * hooks/ctcp-reply:                      Hook Types.
 448 * hooks/disconnect:                      Hook Types.
 449 * hooks/flood:                           Hook Types.
 450 * hooks/invite:                          Hook Types.
 451 * hooks/join:                            Hook Types.
 452 * hooks/kick:                            Hook Types.
 453 * hooks/message:                         Hook Types.
 454 * hooks/mode:                            Hook Types.
 455 * hooks/nickname:                        Hook Types.
 456 * hooks/notice:                          Hook Types.
 457 * hooks/part:                            Hook Types.
 458 * hooks/public:                          Hook Types.
 459 * hooks/public-notice:                   Hook Types.
 460 * hooks/raw:                             Hook Types.
 461 * hooks/signoff:                         Hook Types.
 462 * hooks/timer:                           Hook Types.
 463 * hooks/topic:                           Hook Types.
 464 * user-friend:                           Scheme User Levels.
 465 * user-master:                           Scheme User Levels.
 466 * user-none:                             Scheme User Levels.
 467 * user-trusted:                          Scheme User Levels.
 468 * user-user:                             Scheme User Levels.
 469
 470
 471 \1f
 472 Tag Table:
 473 Node: Top\7f517
 474 Node: Introduction\7f1246
 475 Node: Configuration\7f1437
 476 Node: Configuration File Syntax\7f1823
 477 Node: Configure File Placement\7f2025
 478 Node: Using the Bot\7f2499
 479 Node: User Levels\7f2673
 480 Node: Scripting\7f3677
 481 Node: Adding New Commands\7f4560
 482 Node: Hooks\7f5803
 483 Node: Creating a Hook\7f6741
 484 Node: Hook Types\7f7533
 485 Node: Scheme User Levels\7f10006
 486 Node: Sending Messages\7f11135
 487 Node: High Level Message Functions\7f11703
 488 Node: Low Level Message Functions\7f11921
 489 Node: Concept Index\7f12680
 490 Node: Function Index\7f12862
 491 Node: Variable Index\7f13123
 492 \1f
 493 End Tag Table