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