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 * Misc Scripting Stuff::
 143
 144 \1f
 145 File: bobot++.info,  Node: Adding New Commands,  Next: Hooks,  Prev: Scripting,  Up: Scripting
 146
 147 Adding New Commands
 148 ===================
 149
 150    Adding a new command is simple. To register a new command use
 151 `bot:addcommand'. The prototype for `bot:addcommand' is
 152 `(bot:addcommand name func needs-channel? num-of-args min-level)'. The
 153 `name' is a string representing the name of the command being added.
 154 `func' is a function accepting `num-of-args' arguments.
 155 `needs-channel?' is a bool that is true if the function needs the
 156 channel name as its first arg, and false otherwise. `num-of-args' is
 157 the number of args `func' will take and must be within zero (0) and
 158 twenty (20). `min-level' is one of the *Note Scheme User Levels::. A
 159 user must be at least a `min-level' user to use the new command. None
 160 of the arguments are guaranteed to be passed; if they aren't they are
 161 set to the empty string `""'. An example of a new command would be:
 162
 163      (define (hello channel name)
 164        (if (string=? name "")
 165          (bot:say channel "Hello world!")
 166          (bot:say channel (string-append "Hello " name "!")))
 167
 168      (bot:addcommand "hello" hello #t 2 0)
 169
 170    This will display "Hello World!" if called as `!hello' and "Hello
 171 World `USER'" if called as `!hello USER'.
 172
 173 \1f
 174 File: bobot++.info,  Node: Hooks,  Next: Scheme User Levels,  Prev: Adding New Commands,  Up: Scripting
 175
 176 Hooks
 177 =====
 178
 179    Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
 180 and tiny fugue (a MUD bot) hooks with a little bit of extra stuff added
 181 in. The basic idea of a hook if that you match a text against regular
 182 expression and call a function if text in a message matches that regex.
 183 The different types of hooks provided by Bobot++ correspond to the
 184 different classes of messages that Bobot++ can recieve. A Hook also has
 185 several properties, including its priority and whether or not it is a
 186 fallthrough hook. Higher priority hooks are executed before lower
 187 priority hooks and fallthrough hooks are executed before
 188 non-fallthrough hooks of the same priority. A fallthrough hook can
 189 match and processing of hooks will continue; as soon as the first
 190 non-fallthrough hooks matches processing of hooks stops.
 191
 192 * Menu:
 193
 194 * Creating a Hook::
 195 * Hook Types::
 196
 197 \1f
 198 File: bobot++.info,  Node: Creating a Hook,  Next: Hook Types,  Prev: Hooks,  Up: Hooks
 199
 200 Creating a Hook
 201 ---------------
 202
 203    To add a new hook you use the function `bot:addhook'. `bot:addhook'
 204 is prototyped as `(bot:addhook type regex function pri fall name)'.
 205 `type' specifies the type of hook (the types of hooks are listed in
 206 *Note Hook Types::). `regex' is a standard regular expression. If
 207 `regex' is matched, `function' will be called. `function' will take a
 208 different number of args depending on the hook type. `pri' specifies
 209 the priority of the hook--higher priority hooks are executed first.
 210 This argument is optional and defaults to `0'. `fall' is `#t' if the
 211 hook is a fallthrough hook and `#f' is the hook is not a fallthrough
 212 hook. This arg is also optional and default to `#t'. `name' is the
 213 optional name of the hook that defaults to "DEFAULT". If you set the
 214 name then you can have more than one hook that matches the same regexp,
 215 as long as they have the same name. E.g. in a log script you could have
 216 the regexps for the log function all be `".*"' and set their names to
 217 `"log"' to avoid a conflict with other hooks.
 218
 219 \1f
 220 File: bobot++.info,  Node: Hook Types,  Prev: Creating a Hook,  Up: Hooks
 221
 222 Hook Types
 223 ----------
 224
 225    Here is a list of the various hooks are notes on each one. The
 226 general format of a hook is:
 227
 228    * `hooks/name' (this is the Scheme variable name of the hook)
 229         - Description of the hook
 230
 231         - ARG1 ARG2 ... ARGN
 232              - ARG1: desc
 233
 234              - ARG2: desc
 235
 236              - ...
 237
 238              - ARGN: desc
 239
 240    That said, here is the list of available hooks: FIXME: write docs
 241
 242    * `hooks/action'
 243         - This hook is triggered when someone performs an action.
 244
 245         - FROM, TO, ACTION
 246              - FROM: this is the address of the person that performed
 247                the action in the form `NICK ! USER @ HOST' (without the
 248                spaces).
 249
 250              - TO: This is the target of the action, which is either a
 251                channel or the Bot's nick.
 252
 253              - ACTION: This is the text of the action. E.g. if someone
 254                did `* foobar does baz', then ACTION would be the string
 255                `"does baz"'.
 256
 257    * `hooks/nickname'
 258         - Description of the hook
 259
 260         - # of args
 261              - `arg1': desc
 262
 263    * `hooks/signoff'
 264         - Description of the hook
 265
 266         - # of args
 267              - `arg1': desc
 268
 269    * `hooks/ctcp'
 270         - Description of the hook
 271
 272         - # of args
 273              - `arg1': desc
 274
 275    * `hooks/ctcp-reply'
 276         - Description of the hook
 277
 278         - # of args
 279              - `arg1': desc
 280
 281    * `hooks/disconnect'
 282         - Description of the hook
 283
 284         - # of args
 285              - `arg1': desc
 286
 287    * `hooks/flood'
 288         - Description of the hook
 289
 290         - # of args
 291              - `arg1': desc
 292
 293    * `hooks/invite'
 294         - Description of the hook
 295
 296         - # of args
 297              - `arg1': desc
 298
 299    * `hooks/join'
 300         - Description of the hook
 301
 302         - # of args
 303              - `arg1': desc
 304
 305    * `hooks/kick'
 306         - Description of the hook
 307
 308         - # of args
 309              - `arg1': desc
 310
 311    * `hooks/part'
 312         - Description of the hook
 313
 314         - # of args
 315              - `arg1': desc
 316
 317    * `hooks/mode'
 318         - Description of the hook
 319
 320         - # of args
 321              - `arg1': desc
 322
 323    * `hooks/message'
 324         - Description of the hook
 325
 326         - # of args
 327              - `arg1': desc
 328
 329    * `hooks/notice'
 330         - Description of the hook
 331
 332         - # of args
 333              - `arg1': desc
 334
 335    * `hooks/public'
 336         - Description of the hook
 337
 338         - # of args
 339              - `arg1': desc
 340
 341    * `hooks/public-notice'
 342         - Description of the hook
 343
 344         - # of args
 345              - `arg1': desc
 346
 347    * `hooks/raw'
 348         - Description of the hook
 349
 350         - # of args
 351              - `arg1': desc
 352
 353    * `hooks/timer'
 354         - Description of the hook
 355
 356         - # of args
 357              - `arg1': desc
 358
 359    * `hooks/topic'
 360         - Description of the hook
 361
 362         - # of args
 363              - `arg1': desc
 364
 365    * `hooks/dcc/begin'
 366         - This hook is triggered when a user begins a DCC CHAT with the
 367           bot.
 368
 369         - FROM
 370              - FROM: This is the user's address in the form
 371                `nick!user@host'.
 372
 373    * `hooks/dcc/message'
 374         - This hook is triggered when a user sends a message to the bot
 375           through a DCC CHAT
 376
 377         - FROM MESSAGE
 378              - FROM: This is the user's address in the form
 379                `nick!user@host'.
 380
 381              - MESSAGE: This is the message the user sent to the bot.
 382
 383 \1f
 384 File: bobot++.info,  Node: Scheme User Levels,  Next: Sending Messages,  Prev: Hooks,  Up: Scripting
 385
 386 Scheme User Levels
 387 ==================
 388
 389    There are five levels that a user may be when interfacing with a bot:
 390 NONE, USER, TRUSTED_USER, FRIEND, MASTER. The Scheme variables for the
 391 user levels are `bot:user-none', `bot:user-user', `bot:user-trusted',
 392 `bot:user-friend', and `bot:user-master'. See *Note User Levels:: for
 393 more information on User Levels.
 394
 395    When adding a new command, think about who should be able to use it.
 396 Is your command a general purpose command that helps the channel (e.g.
 397 `!seen') that everyone should be able to use? Or is it something that
 398 should be restricted? See *Note User Levels:: for information on what
 399 level users can do what with the built in bot commands and think about
 400 what level a user your command is targetted towards. You must be _very_
 401 careful when giving new commands to lower level users because you can
 402 do basically everything the bot can do with a script. As the scripting
 403 interface becomes more powerful, you must think more about what users
 404 can use new commands you add.
 405
 406 \1f
 407 File: bobot++.info,  Node: Sending Messages,  Next: Misc Scripting Stuff,  Prev: Scheme User Levels,  Up: Scripting
 408
 409 Sending Messages
 410 ================
 411
 412    There are several types of messages you can send with Bobot++ from
 413 scripts. There is the simple, but rather limited, `bot:say',
 414 `bot:action' and `bot:msg', and the more powerful, but lower level,
 415 `bot:send-MESSAGE' functions. Most bots will probably only need the
 416 higher level functions, but for the sake of why-not Bobot++ lets you
 417 use the lower level functions (in progress).
 418
 419 * Menu:
 420
 421 * High Level Message Functions::
 422 * Low Level Message Functions::
 423
 424 \1f
 425 File: bobot++.info,  Node: High Level Message Functions,  Next: Low Level Message Functions,  Prev: Sending Messages,  Up: Sending Messages
 426
 427 "High Level" Message Functions
 428 ------------------------------
 429
 430    ...
 431
 432 \1f
 433 File: bobot++.info,  Node: Low Level Message Functions,  Prev: High Level Message Functions,  Up: Sending Messages
 434
 435 "Low Level" Message Functions
 436 -----------------------------
 437
 438    The "Low Level" messaging functions allow you to do things like send
 439 CTCP messages. You probably want to read rfc 2812 and the CTCP spec
 440 before using these. If you have no idea what these do, read rfc 2812
 441 (IRC Client Protocol) and CTCP spec. These functions all return
 442 `*unspecified*' always, so don't use the return value for anything.
 443
 444    * `bot:send-CTCP to command message' `to' is the target of your CTCP
 445      message, `command' is the CTCP command, and `message' is the
 446      message (or arguments) of the command. Make sure to
 447      `bot:ctcp-quote' the message!
 448
 449
 450 \1f
 451 File: bobot++.info,  Node: Misc Scripting Stuff,  Prev: Sending Messages,  Up: Scripting
 452
 453 Misc. Scripting Stuff
 454 =====================
 455
 456    These are a few useful things that I thought people writing scripts
 457 might want to know.
 458
 459    If you want to execute code when the bot exits, just do `add-hook!
 460 bot:exit-hook THUNK' where THUNK is an argumentless procedure (a
 461 thunk). When the bot exits your thunk will be called.
 462
 463 \1f
 464 File: bobot++.info,  Node: Concept Index,  Next: Function Index,  Prev: Scripting,  Up: Top
 465
 466 Concept Index
 467 *************
 468
 469 * Menu:
 470
 471 * Background on Hooks:                   Hooks.
 472
 473 \1f
 474 File: bobot++.info,  Node: Function Index,  Next: Variable Index,  Prev: Concept Index,  Up: Top
 475
 476 Function Index
 477 **************
 478
 479 * Menu:
 480
 481 * addcommand:                            Adding New Commands.
 482 * addhook:                               Creating a Hook.
 483
 484 \1f
 485 File: bobot++.info,  Node: Variable Index,  Prev: Function Index,  Up: Top
 486
 487 Variable Index
 488 **************
 489
 490 * Menu:
 491
 492 * exit-hook:                             Misc Scripting Stuff.
 493 * hooks/action:                          Hook Types.
 494 * hooks/ctcp:                            Hook Types.
 495 * hooks/ctcp-reply:                      Hook Types.
 496 * hooks/dcc/begin:                       Hook Types.
 497 * hooks/dcc/message:                     Hook Types.
 498 * hooks/disconnect:                      Hook Types.
 499 * hooks/flood:                           Hook Types.
 500 * hooks/invite:                          Hook Types.
 501 * hooks/join:                            Hook Types.
 502 * hooks/kick:                            Hook Types.
 503 * hooks/message:                         Hook Types.
 504 * hooks/mode:                            Hook Types.
 505 * hooks/nickname:                        Hook Types.
 506 * hooks/notice:                          Hook Types.
 507 * hooks/part:                            Hook Types.
 508 * hooks/public:                          Hook Types.
 509 * hooks/public-notice:                   Hook Types.
 510 * hooks/raw:                             Hook Types.
 511 * hooks/signoff:                         Hook Types.
 512 * hooks/timer:                           Hook Types.
 513 * hooks/topic:                           Hook Types.
 514 * user-friend:                           Scheme User Levels.
 515 * user-master:                           Scheme User Levels.
 516 * user-none:                             Scheme User Levels.
 517 * user-trusted:                          Scheme User Levels.
 518 * user-user:                             Scheme User Levels.
 519
 520
 521 \1f
 522 Tag Table:
 523 Node: Top\7f517
 524 Node: Introduction\7f1246
 525 Node: Configuration\7f1437
 526 Node: Configuration File Syntax\7f1823
 527 Node: Configure File Placement\7f2025
 528 Node: Using the Bot\7f2499
 529 Node: User Levels\7f2673
 530 Node: Scripting\7f3677
 531 Node: Adding New Commands\7f4585
 532 Node: Hooks\7f5852
 533 Node: Creating a Hook\7f6826
 534 Node: Hook Types\7f7965
 535 Node: Scheme User Levels\7f11439
 536 Node: Sending Messages\7f12568
 537 Node: High Level Message Functions\7f13179
 538 Node: Low Level Message Functions\7f13393
 539 Node: Misc Scripting Stuff\7f14146
 540 Node: Concept Index\7f14565
 541 Node: Function Index\7f14747
 542 Node: Variable Index\7f15008
 543 \1f
 544 End Tag Table