bobot++.info

   1 This is bobot++.info, produced by makeinfo version 4.6 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 content.
  48
  49 \1f
  50 File: bobot++.info,  Node: Configuration,  Next: Using the Bot,  Prev: Introduction,  Up: Top
  51
  52 Configuration
  53 *************
  54
  55 Bobot++ is easy to configure. The configuration file format may be
  56 changing in the 2.1 series, so it is not documented for now. See the
  57 `examples' directory for an example configuration.
  58
  59 * Menu:
  60
  61 * Configuration File Syntax::
  62 * Configure File Placement::
  63
  64 \1f
  65 File: bobot++.info,  Node: Configuration File Syntax,  Next: Configure File Placement,  Prev: Configuration,  Up: Configuration
  66
  67 Configuration File Syntax
  68 =========================
  69
  70 * Menu:
  71
  72 * bot.conf::
  73
  74 \1f
  75 File: bobot++.info,  Node: bot.conf,  Prev: Configuration File Syntax,  Up: Configuration File Syntax
  76
  77 bot.conf
  78 --------
  79
  80 bot.conf is the main configuration file for a Bobot++. The available
  81 configuration variables are listed below in the format "VARIABLE
  82 <default-value>: description"
  83
  84    * NICKNAME <Bobot>: The nickname of the bot (NICK is an alias for
  85      NICKNAME)
  86
  87    * USERNAME <bobot>: The IRC username of the bot
  88
  89    * CMDCHAR <!>: The character that prefixes commands given to the bot
  90      (COMMAND is an alias for CMDCHAR)
  91
  92    * IRCNAME <I'm a bobot++!>: The IRC name (or 'real name') of the bot
  93      (REALNAME is an alias for IRCNAME)
  94
  95    * USERLIST <bot.users>: Name of the file where the userlist is stored
  96
  97    * SHITLIST <bot.shit>: Name of the file where the shitlist is stored
  98
  99    * LOGFILE <$LOGDIR/bot.log>:
 100
 101
 102 \1f
 103 File: bobot++.info,  Node: Configure File Placement,  Prev: Configuration File Syntax,  Up: Configuration
 104
 105 Configuration File Placement
 106 ============================
 107
 108 Bobot++ will look in `/etc/bobotpp/default/' for its default config if
 109 none is specified on the command line. Put the configuration files you
 110 want to be loaded by default in this directory. If you are not root or
 111 you want to have your own personal configration, put it in
 112 `~/.bobotpp/config/default/'.
 113
 114 \1f
 115 File: bobot++.info,  Node: Using the Bot,  Next: Scripting,  Prev: Configuration,  Up: Top
 116
 117 Using Bobot++
 118 *************
 119
 120 FIXME: stuff here...
 121
 122 * Menu:
 123
 124 * User Levels::
 125
 126 \1f
 127 File: bobot++.info,  Node: User Levels,  Prev: Using the Bot,  Up: Using the Bot
 128
 129 User Levels
 130 ===========
 131
 132 There are five levels that a user may be when interfacing with a bot:
 133 NONE, USER, TRUSTED_USER, FRIEND, MASTER. All users default to NONE
 134 unless they are changed by a script, the `!adduser' command or the
 135 `bot.users' file. NONE is for everyone--very few commands (e.g. help)
 136 are available to the users and almost everyone should be this level. A
 137 USER can execute many of the bot commands, but can't use masks on kicks
 138 and bans. A TRUSTED user can everything a USER can do, but can also use
 139 masks on kicks and bans. A FRIEND can do everything except for stopping
 140 the bot (be careful who you give this to!). The MASTER level is for the
 141 bot's owner (probably you) and can do _everything_ to the bot. Be
 142 _very_ careful if you give MASTER level access to anyone else. You
 143 cannot use this symbolic levels with the `!adduser' command. See
 144 (FIXME: ref) for the numbers you must use with `!adduser'.
 145
 146 \1f
 147 File: bobot++.info,  Node: Scripting,  Next: Concept Index,  Prev: Using the Bot,  Up: Top
 148
 149 Scripting
 150 *********
 151
 152 Bobot++'s most powerful feature is its scripting system. You write
 153 scripts using Guile Scheme. This manual does not cover how to use Guile
 154 or how to learn Scheme. *Note Guile Reference Manual: (guile)Top, for
 155 the Guile reference manual and
 156 <http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html> for a
 157 good tutorial on Scheme.
 158
 159    Note that in previous versions the scripting commands where in the
 160 form `bot-FUNCTION'. They are now in the form `bot:FUNCTION'. The old
 161 names are still available, but are deprecated and will be removed in
 162 Bobot++ 2.4. The command `perl -pi -e ``s/bot-/bot:/g'' YOUR-FILES'
 163 should be enough to convert your code to use the new functions.
 164
 165 * Menu:
 166
 167 * Adding New Commands::
 168 * Hooks::
 169 * Scheme User Levels::
 170 * Sending Messages::
 171 * Misc Scripting Stuff::
 172
 173 \1f
 174 File: bobot++.info,  Node: Adding New Commands,  Next: Hooks,  Prev: Scripting,  Up: Scripting
 175
 176 Adding New Commands
 177 ===================
 178
 179 Adding a new command is simple. To register a new command use
 180 `bot:addcommand'. The prototype for `bot:addcommand' is
 181 `(bot:addcommand name func needs-channel? num-of-args min-level)'. The
 182 `name' is a string representing the name of the command being added.
 183 `func' is a function accepting `num-of-args' arguments.
 184 `needs-channel?' is a bool that is true if the function needs the
 185 channel name as its first arg, and false otherwise. `num-of-args' is
 186 the number of args `func' will take and must be within zero (0) and
 187 twenty (20). `min-level' is one of the *Note Scheme User Levels::. A
 188 user must be at least a `min-level' user to use the new command. None
 189 of the arguments are guaranteed to be passed; if they aren't they are
 190 set to the empty string `""'. An example of a new command would be:
 191
 192      (define (hello channel name)
 193        (if (string=? name "")
 194          (bot:say channel "Hello world!")
 195          (bot:say channel (string-append "Hello " name "!")))
 196
 197      (bot:addcommand "hello" hello #t 2 0)
 198
 199    This will display "Hello World!" if called as `!hello' and "Hello
 200 World `USER'" if called as `!hello USER'.
 201
 202 \1f
 203 File: bobot++.info,  Node: Hooks,  Next: Scheme User Levels,  Prev: Adding New Commands,  Up: Scripting
 204
 205 Hooks
 206 =====
 207
 208 Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
 209 and tiny fugue (a MUD bot) hooks with a little bit of extra stuff added
 210 in. The basic idea of a hook if that you match a text against regular
 211 expression and call a function if text in a message matches that regex.
 212 The different types of hooks provided by Bobot++ correspond to the
 213 different classes of messages that Bobot++ can recieve. A Hook also has
 214 several properties, including its priority and whether or not it is a
 215 fallthrough hook. Higher priority hooks are executed before lower
 216 priority hooks and fallthrough hooks are executed before
 217 non-fallthrough hooks of the same priority. A fallthrough hook can
 218 match and processing of hooks will continue; as soon as the first
 219 non-fallthrough hooks matches processing of hooks stops.
 220
 221 * Menu:
 222
 223 * Creating a Hook::
 224 * Hook Types::
 225
 226 \1f
 227 File: bobot++.info,  Node: Creating a Hook,  Next: Hook Types,  Prev: Hooks,  Up: Hooks
 228
 229 Creating a Hook
 230 ---------------
 231
 232 To add a new hook you use the function `bot:addhook'. `bot:addhook' is
 233 prototyped as `(bot:addhook type regex function pri fall name)'. `type'
 234 specifies the type of hook (the types of hooks are listed in *Note Hook
 235 Types::). `regex' is a standard regular expression. If `regex' is
 236 matched, `function' will be called. `function' will take a different
 237 number of args depending on the hook type. `pri' specifies the priority
 238 of the hook--higher priority hooks are executed first. This argument is
 239 optional and defaults to `0'. `fall' is `#t' if the hook is a
 240 fallthrough hook and `#f' is the hook is not a fallthrough hook. This
 241 arg is also optional and default to `#t'. `name' is the optional name
 242 of the hook that defaults to "DEFAULT". If you set the name then you
 243 can have more than one hook that matches the same regexp, as long as
 244 they have the same name. E.g. in a log script you could have the
 245 regexps for the log function all be `".*"' and set their names to
 246 `"log"' to avoid a conflict with other hooks.
 247
 248 \1f
 249 File: bobot++.info,  Node: Hook Types,  Prev: Creating a Hook,  Up: Hooks
 250
 251 Hook Types
 252 ----------
 253
 254 Here is a list of the various hooks are notes on each one. The general
 255 format of a hook is:
 256
 257    * `hooks/name' (this is the Scheme variable name of the hook)
 258         - Description of the hook
 259
 260         - ARG1 ARG2 ... ARGN
 261              - ARG1: desc
 262
 263              - ARG2: desc
 264
 265              - ...
 266
 267              - ARGN: desc
 268
 269    That said, here is the list of available hooks: FIXME: write docs
 270
 271    * `hooks/action'
 272         - This hook is triggered when someone performs an action.
 273
 274         - FROM, TO, ACTION
 275              - FROM: this is the address of the person that performed
 276                the action in the form `NICK ! USER @ HOST' (without the
 277                spaces).
 278
 279              - TO: This is the target of the action, which is either a
 280                channel or the Bot's nick.
 281
 282              - ACTION: This is the text of the action. E.g. if someone
 283                did `* foobar does baz', then ACTION would be the string
 284                `"does baz"'.
 285
 286    * `hooks/nickname'
 287         - Description of the hook
 288
 289         - # of args
 290              - `arg1': desc
 291
 292    * `hooks/signoff'
 293         - Description of the hook
 294
 295         - # of args
 296              - `arg1': desc
 297
 298    * `hooks/ctcp'
 299         - Description of the hook
 300
 301         - # of args
 302              - `arg1': desc
 303
 304    * `hooks/ctcp-reply'
 305         - Description of the hook
 306
 307         - # of args
 308              - `arg1': desc
 309
 310    * `hooks/disconnect'
 311         - Description of the hook
 312
 313         - # of args
 314              - `arg1': desc
 315
 316    * `hooks/flood'
 317         - Description of the hook
 318
 319         - # of args
 320              - `arg1': desc
 321
 322    * `hooks/invite'
 323         - Description of the hook
 324
 325         - # of args
 326              - `arg1': desc
 327
 328    * `hooks/join'
 329         - Description of the hook
 330
 331         - # of args
 332              - `arg1': desc
 333
 334    * `hooks/kick'
 335         - Description of the hook
 336
 337         - # of args
 338              - `arg1': desc
 339
 340    * `hooks/part'
 341         - Description of the hook
 342
 343         - # of args
 344              - `arg1': desc
 345
 346    * `hooks/mode'
 347         - Description of the hook
 348
 349         - # of args
 350              - `arg1': desc
 351
 352    * `hooks/message'
 353         - Description of the hook
 354
 355         - # of args
 356              - `arg1': desc
 357
 358    * `hooks/notice'
 359         - Description of the hook
 360
 361         - # of args
 362              - `arg1': desc
 363
 364    * `hooks/public'
 365         - Description of the hook
 366
 367         - # of args
 368              - `arg1': desc
 369
 370    * `hooks/public-notice'
 371         - Description of the hook
 372
 373         - # of args
 374              - `arg1': desc
 375
 376    * `hooks/raw'
 377         - Description of the hook
 378
 379         - # of args
 380              - `arg1': desc
 381
 382    * `hooks/timer'
 383         - Description of the hook
 384
 385         - # of args
 386              - `arg1': desc
 387
 388    * `hooks/topic'
 389         - Description of the hook
 390
 391         - # of args
 392              - `arg1': desc
 393
 394    * `hooks/dcc/begin'
 395         - This hook is triggered when a user begins a DCC CHAT with the
 396           bot.
 397
 398         - FROM
 399              - FROM: This is the user's address in the form
 400                `nick!user@host'.
 401
 402    * `hooks/dcc/message'
 403         - This hook is triggered when a user sends a message to the bot
 404           through a DCC CHAT
 405
 406         - FROM MESSAGE
 407              - FROM: This is the user's address in the form
 408                `nick!user@host'.
 409
 410              - MESSAGE: This is the message the user sent to the bot.
 411
 412 \1f
 413 File: bobot++.info,  Node: Scheme User Levels,  Next: Sending Messages,  Prev: Hooks,  Up: Scripting
 414
 415 Scheme User Levels
 416 ==================
 417
 418 There are five levels that a user may be when interfacing with a bot:
 419 NONE, USER, TRUSTED_USER, FRIEND, MASTER. The Scheme variables for the
 420 user levels are `bot:user-none', `bot:user-user', `bot:user-trusted',
 421 `bot:user-friend', and `bot:user-master'. See *Note User Levels:: for
 422 more information on User Levels.
 423
 424    When adding a new command, think about who should be able to use it.
 425 Is your command a general purpose command that helps the channel (e.g.
 426 `!seen') that everyone should be able to use? Or is it something that
 427 should be restricted? See *Note User Levels:: for information on what
 428 level users can do what with the built in bot commands and think about
 429 what level a user your command is targetted towards. You must be _very_
 430 careful when giving new commands to lower level users because you can
 431 do basically everything the bot can do with a script. As the scripting
 432 interface becomes more powerful, you must think more about what users
 433 can use new commands you add.
 434
 435 \1f
 436 File: bobot++.info,  Node: Sending Messages,  Next: Misc Scripting Stuff,  Prev: Scheme User Levels,  Up: Scripting
 437
 438 Sending Messages
 439 ================
 440
 441 There are several types of messages you can send with Bobot++ from
 442 scripts. There is the simple, but rather limited, `bot:say',
 443 `bot:action' and `bot:msg', and the more powerful, but lower level,
 444 `bot:send-MESSAGE' functions. Most bots will probably only need the
 445 higher level functions, but for the sake of why-not Bobot++ lets you
 446 use the lower level functions (in progress).
 447
 448 * Menu:
 449
 450 * High Level Message Functions::
 451 * Low Level Message Functions::
 452
 453 \1f
 454 File: bobot++.info,  Node: High Level Message Functions,  Next: Low Level Message Functions,  Prev: Sending Messages,  Up: Sending Messages
 455
 456 "High Level" Message Functions
 457 ------------------------------
 458
 459 ...
 460
 461 \1f
 462 File: bobot++.info,  Node: Low Level Message Functions,  Prev: High Level Message Functions,  Up: Sending Messages
 463
 464 "Low Level" Message Functions
 465 -----------------------------
 466
 467 The "Low Level" messaging functions allow you to do things like send
 468 CTCP messages. You probably want to read rfc 2812 and the CTCP spec
 469 before using these. If you have no idea what these do, read rfc 2812
 470 (IRC Client Protocol) and CTCP spec. These functions all return
 471 `*unspecified*' always, so don't use the return value for anything.
 472
 473    * `bot:send-CTCP to command message' `to' is the target of your CTCP
 474      message, `command' is the CTCP command, and `message' is the
 475      message (or arguments) of the command. Make sure to
 476      `bot:ctcp-quote' the message!
 477
 478
 479 \1f
 480 File: bobot++.info,  Node: Misc Scripting Stuff,  Prev: Sending Messages,  Up: Scripting
 481
 482 Misc. Scripting Stuff
 483 =====================
 484
 485 These are a few useful things that I thought people writing scripts
 486 might want to know.
 487
 488    If you want to execute code when the bot exits, just do `add-hook!
 489 bot:exit-hook THUNK' where THUNK is an argumentless procedure (a
 490 thunk). When the bot exits your thunk will be called.
 491
 492 \1f
 493 File: bobot++.info,  Node: Concept Index,  Next: Function Index,  Prev: Scripting,  Up: Top
 494
 495 Concept Index
 496 *************
 497
 498 * Menu:
 499
 500 * Background on Hooks:                   Hooks.
 501
 502 \1f
 503 File: bobot++.info,  Node: Function Index,  Next: Variable Index,  Prev: Concept Index,  Up: Top
 504
 505 Function Index
 506 **************
 507
 508 * Menu:
 509
 510 * addcommand:                            Adding New Commands.
 511 * addhook:                               Creating a Hook.
 512
 513 \1f
 514 File: bobot++.info,  Node: Variable Index,  Prev: Function Index,  Up: Top
 515
 516 Variable Index
 517 **************
 518
 519 * Menu:
 520
 521 * exit-hook:                             Misc Scripting Stuff.
 522 * hooks/action:                          Hook Types.
 523 * hooks/ctcp:                            Hook Types.
 524 * hooks/ctcp-reply:                      Hook Types.
 525 * hooks/dcc/begin:                       Hook Types.
 526 * hooks/dcc/message:                     Hook Types.
 527 * hooks/disconnect:                      Hook Types.
 528 * hooks/flood:                           Hook Types.
 529 * hooks/invite:                          Hook Types.
 530 * hooks/join:                            Hook Types.
 531 * hooks/kick:                            Hook Types.
 532 * hooks/message:                         Hook Types.
 533 * hooks/mode:                            Hook Types.
 534 * hooks/nickname:                        Hook Types.
 535 * hooks/notice:                          Hook Types.
 536 * hooks/part:                            Hook Types.
 537 * hooks/public:                          Hook Types.
 538 * hooks/public-notice:                   Hook Types.
 539 * hooks/raw:                             Hook Types.
 540 * hooks/signoff:                         Hook Types.
 541 * hooks/timer:                           Hook Types.
 542 * hooks/topic:                           Hook Types.
 543 * user-friend:                           Scheme User Levels.
 544 * user-master:                           Scheme User Levels.
 545 * user-none:                             Scheme User Levels.
 546 * user-trusted:                          Scheme User Levels.
 547 * user-user:                             Scheme User Levels.
 548
 549
 550 \1f
 551 Tag Table:
 552 Node: Top\7f517
 553 Node: Introduction\7f1246
 554 Node: Configuration\7f1434
 555 Node: Configuration File Syntax\7f1817
 556 Node: bot.conf\7f2024
 557 Node: Configure File Placement\7f2856
 558 Node: Using the Bot\7f3327
 559 Node: User Levels\7f3498
 560 Node: Scripting\7f4499
 561 Node: Adding New Commands\7f5404
 562 Node: Hooks\7f6668
 563 Node: Creating a Hook\7f7639
 564 Node: Hook Types\7f8775
 565 Node: Scheme User Levels\7f12246
 566 Node: Sending Messages\7f13372
 567 Node: High Level Message Functions\7f13980
 568 Node: Low Level Message Functions\7f14191
 569 Node: Misc Scripting Stuff\7f14941
 570 Node: Concept Index\7f15357
 571 Node: Function Index\7f15539
 572 Node: Variable Index\7f15800
 573 \1f
 574 End Tag Table