bobot++.info

   1 This is bobot++.info, produced by makeinfo version 4.7 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,2004,2005 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.2 of the program named Bobot++
  22
  23    Copyright 2002,2004,2005 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  --- The Detailed Node Listing ---
  42
  43 Configuration
  44
  45 * Configuration File Placement::
  46 * Configuration Files::
  47
  48 Configuration Files
  49
  50 * bot.conf::
  51 * bot.users::
  52
  53 bot.conf
  54
  55 * server syntax::
  56 * channel syntax::
  57
  58 Using Bobot++
  59
  60 * Starting the Bot::
  61 * User Levels::
  62 * Protection::
  63 * Automatic Op::
  64 * Built-In Commands::
  65
  66 Scripting
  67
  68 * Adding New Commands::
  69 * Hooks::
  70 * Scheme User Levels::
  71 * Sending Messages::
  72 * Misc Scripting Stuff::
  73
  74 Hooks
  75
  76 * Creating a Hook::
  77 * Hook Types::
  78
  79 Hook Types
  80
  81 * Received Message Hooks::
  82 * Sent Message Hooks::
  83 * DCC CHAT Hooks::
  84 * Miscellaneous Hooks::
  85
  86 Sending Messages
  87
  88 * High Level Message Functions::
  89 * Low Level Message Functions::
  90
  91 \1f
  92 File: bobot++.info,  Node: Introduction,  Next: Configuration,  Prev: Top,  Up: Top
  93
  94 1 Introduction
  95 **************
  96
  97 This manual feels abused and neglected because it has almost no content.
  98
  99 \1f
 100 File: bobot++.info,  Node: Configuration,  Next: Using the Bot,  Prev: Introduction,  Up: Top
 101
 102 2 Configuration
 103 ***************
 104
 105 Bobot++ is easy to configure. See the `examples' directory for an
 106 example configuration.
 107
 108 * Menu:
 109
 110 * Configuration File Placement::
 111 * Configuration Files::
 112
 113 \1f
 114 File: bobot++.info,  Node: Configuration File Placement,  Next: Configuration Files,  Prev: Configuration,  Up: Configuration
 115
 116 2.1 Configuration File Placement
 117 ================================
 118
 119 Bobot++ will look in `/etc/bobotpp/default/' for its default config if
 120 none is specified on the command line. Put the configuration files you
 121 want to be loaded by default in this directory. If you are not root or
 122 you want to have your own personal configuration, put it in
 123 `~/.bobotpp/config/default/'.
 124
 125 \1f
 126 File: bobot++.info,  Node: Configuration Files,  Prev: Configuration File Placement,  Up: Configuration
 127
 128 2.2 Configuration Files
 129 =======================
 130
 131 * Menu:
 132
 133 * bot.conf::
 134 * bot.users::
 135
 136 \1f
 137 File: bobot++.info,  Node: bot.conf,  Next: bot.users,  Prev: Configuration Files,  Up: Configuration Files
 138
 139 2.2.1 bot.conf
 140 --------------
 141
 142 * Menu:
 143
 144 * server syntax::
 145 * channel syntax::
 146
 147    `bot.conf' contains key value pairs separated by `='.
 148
 149    `<key> = <value>'
 150
 151    Comments are started with a `#' and cause the entire line to be
 152 ignored. _Note that this only works when the `#' is the first character
 153 of the line_.
 154
 155    bot.conf is the main configuration file for a Bobot++. The available
 156 configuration variables are listed below in the format "VARIABLE
 157 <default-value>: description"
 158
 159    * NICKNAME <Bobot>: The nickname of the bot (NICK is an alias for
 160      NICKNAME)
 161
 162    * USERNAME <bobot>: The IRC username of the bot
 163
 164    * CMDCHAR <!>: The character that prefixes commands given to the bot
 165      (COMMAND is an alias for CMDCHAR)
 166
 167    * IRCNAME <I'm a bobot++!>: The IRC name (or 'real name') of the bot
 168      (REALNAME is an alias for IRCNAME)
 169
 170    * USERLIST <bot.users>: Name of the file where the userlist is stored
 171
 172    * SHITLIST <bot.shit>: Name of the file where the shitlist is stored
 173
 174    * LOGFILE <$LOGDIR/bot.log>: Location of the bot logfile (set this
 175      to `/dev/null' to disable logging).
 176
 177    * SERVER <None>: This specifies the server to connect to. Note that
 178      this has a special syntax.
 179
 180    * CHANNEL <None>: This specifies a channel the bot will join when it
 181      starts up. This also has a special syntax.
 182
 183
 184 \1f
 185 File: bobot++.info,  Node: server syntax,  Next: channel syntax,  Prev: bot.conf,  Up: bot.conf
 186
 187 2.2.1.1 server syntax
 188 .....................
 189
 190 SERVER = SERVER_NAME [PORT [PASSWORD]]
 191
 192    This will make Bobot++ attempt to connect to SERVER_NAME on port
 193 PORT with the password PASSWORD. SERVER_NAME should be the address of
 194 the server. PORT and PASSWORD are optional. You may use more than one
 195 server line; Bobot++ will attempt to connect to the first one and, if
 196 it fails, will connect to the next one in the list. There is also a
 197 command to cause the bot to cycle servers. At the present time Bobot++
 198 cannot connect to more than one server at a time. This is a planned
 199 feature of 3.0 (which is a very long way away; the current structure of
 200 the program would make it very difficult to add support for connecting
 201 to multiple servers at a time in a usable manner).
 202
 203 \1f
 204 File: bobot++.info,  Node: channel syntax,  Prev: server syntax,  Up: bot.conf
 205
 206 2.2.1.2 channel syntax
 207 ......................
 208
 209 CHANNEL = NAME:INITIAL_MODES:MODES_TO_KEEP:CHANNEL_KEY
 210
 211    You may have any number of channel lines. When Bobot++ starts it will
 212 attempt to join and gain ops in every channel listed. It will join NAME
 213 and set the channel modes to INITIAL_MODES (e.g. "nt") if it is able to
 214 gain operator status. It will then maintain MODES_TO_KEEP. If the
 215 channel requires a key to enter simply set CHANNEL_KEY. Every argument
 216 except for NAME is optional.
 217
 218    A few example lines:
 219
 220    `CHANNEL = #foo:nt:nt:bar'
 221
 222    The bot will join `#foo' with the channel key `bar' and will then
 223 maintain the modes `nt'.
 224
 225    `CHANNEL = #bar:::'
 226
 227    The bot will join `#bar' and will not set any modes nor will it
 228 attempt to maintain any modes.
 229
 230 \1f
 231 File: bobot++.info,  Node: bot.users,  Prev: bot.conf,  Up: Configuration Files
 232
 233 2.2.2 bot.users
 234 ---------------
 235
 236 `bot.users' is the default file name of the userlist. It may be changed
 237 in `bot.conf'. The file contains lines with the format:
 238
 239    `MASK:CHANNEL:LEVEL:PROTECTION:AUTO-OP'
 240
 241    * MASK is the host mask (e.g. `*!*username
 242      .domain.com') of the user
 243
 244    * CHANNEL is a channel mask of the channels that the user has
 245      priviliges to use the bot in (e.g. `*' for all channels, `#*' for
 246      all non-local channel, `#foo*' for all channels starting with
 247      "foo," `#bar' for channel "#bar" only, etc.)
 248
 249    * LEVEL is the user level of the user (*Note User Levels::).
 250
 251    * PROTECTION is the protection level of the user (*Note
 252      Protection::).
 253
 254    * AUTO-OP is set to control whether a user is automatically given
 255      operator priviliges on channel entry (*Note Automatic Op::).
 256
 257
 258 \1f
 259 File: bobot++.info,  Node: Using the Bot,  Next: Scripting,  Prev: Configuration,  Up: Top
 260
 261 3 Using Bobot++
 262 ***************
 263
 264 FIXME: stuff here...
 265
 266 * Menu:
 267
 268 * Starting the Bot::
 269 * User Levels::
 270 * Protection::
 271 * Automatic Op::
 272 * Built-In Commands::
 273
 274 \1f
 275 File: bobot++.info,  Node: Starting the Bot,  Next: User Levels,  Prev: Using the Bot,  Up: Using the Bot
 276
 277 3.1 Starting the Bot
 278 ====================
 279
 280 The bot is usually installed with the binary name `bobotpp'. It accepts
 281 the following command line arguments:
 282
 283    * `[--help][-h]' - Shows detailed help and exits
 284
 285    * `[--version][-v]' - Shows version information and exits
 286
 287    * `[--no-background][-b]' - Run bobot++ in the foreground
 288
 289    * `[--config-file file][-f]' - Use file instead of `bot.conf'
 290
 291    * `[--config-dir dir][-d]' - Use dir as dir to load config file from
 292
 293    * `[--config dir][-c]' - Search your config path (defaults to
 294      `$HOME/.bobotpp/config/' and then `/etc/bobotpp/') for dir and
 295      then loads your config data using dir
 296
 297    * `[--sys-config dir][-s]' - Looks for config in `/etc/bobotpp/dir'.
 298      Note that the user dir is still searched first
 299
 300    * `[--user-config dir][-u]' - Looks for config in
 301      `$HOME/.bobotpp/config/dir/'. Note that the system dir is still
 302      searched after this if dir is not found.
 303
 304    * `[--debug][-D]' Makes Bobot++ print debugging info and run in the
 305      foreground
 306
 307    * `[--debug-scripts][-S]' Enabled the Guile debugging evaluator for
 308      verbose script errors and backtraces while still running the bot
 309      in the background.
 310
 311    The default configuration is read from
 312 `$HOME/.bobotpp/config/default/' and then `/etc/bobotpp/default/' if
 313 the user config is not found.
 314
 315    The bot defaults to running in the background as a daemon.
 316
 317 \1f
 318 File: bobot++.info,  Node: User Levels,  Next: Protection,  Prev: Starting the Bot,  Up: Using the Bot
 319
 320 3.2 User Levels
 321 ===============
 322
 323 There are several user levels available in Bobot++ to provide gradated
 324 access to commands. `!adduser' and `bot.users' use the numeric code;
 325 Scheme uses the textual name for the level. By default (if no catch-all
 326 setting is found in *Note bot.users::.) a user has access to commands
 327 with the level `bot:user-none'.
 328
 329   0. `bot:user-none' - No *built-in* commands may be executed _by
 330      default_ (commands may be added from Scheme that can be executed
 331      by users of level none and the level required to execute a command
 332      may be changed from Scheme).
 333
 334   1. `bot:user-user' - Will be able to execute most commands but not
 335      all and cannot use masks on kicks and bans.
 336
 337   2. `bot:user-trusted' - For built-ins with a default configuration
 338      this user has access to the same set of commands as an `user' but
 339      may use masks on kicks and bans. Scheme commands may be added
 340      which require a user to be of this level.
 341
 342   3. `bot:user-friend' - In the default configuration a user who is a
 343      friend will be able to do everything short of stopping the bot.
 344      Again, there may be user added commands that require a higher user
 345      level.
 346
 347   4. `bot:user-master' - This is the highest user level and has access
 348      to every feature of the bot.
 349
 350
 351 \1f
 352 File: bobot++.info,  Node: Protection,  Next: Automatic Op,  Prev: User Levels,  Up: Using the Bot
 353
 354 3.3 Protection
 355 ==============
 356
 357 A user added via Scheme, the `bot.users' file, or `!adduser' may be
 358 protected from being deoped, kicked, or banned. There are currently no
 359 symbolic levels in Scheme; just use the numeric code.
 360
 361   0. No protection
 362
 363   1. No ban. If a user is banned the bot will unban him..
 364
 365   2. No kick. The user may still be kicked but the bot will kickban the
 366      user who kicked the protected user.
 367
 368   3. No deop. The bot will ensure that the user always maintains
 369      operator status.
 370
 371 \1f
 372 File: bobot++.info,  Node: Automatic Op,  Next: Built-In Commands,  Prev: Protection,  Up: Using the Bot
 373
 374 3.4 Automatic Op
 375 ================
 376
 377 A user may be automatically given operator status upon entering a
 378 channel. Set the AOP field to "0" to disable auto-op or "1" to enable
 379 auto-op.
 380
 381 \1f
 382 File: bobot++.info,  Node: Built-In Commands,  Prev: Automatic Op,  Up: Using the Bot
 383
 384 3.5 Built-In Commands
 385 =====================
 386
 387 Bobot++ has many built-in commands that make it useful without
 388 scripting support. The reference leaves off the command char; remember
 389 to use whatever you defined the command char to be in `bot.conf'. If a
 390 command needs the channel name then you must specify the channel as the
 391 first argument to the command when private messaging the bot a command.
 392
 393 COMMAND        NEEDS       MIN LEVEL   DESCRIPTION
 394                CHANNEL     TO USE
 395 `action' `do'  Yes         USER         Causes the bot to perform the
 396                                        action `do' in the current channel.
 397 `adduser'
 398 `addserver'                            Adds the server specified by HOST
 399                                        NAME or IP ADDRESS to the server
 400                                        list.
 401 `addshit'
 402 `alias'                                Makes an alias, and adds the
 403                                        function NEW NAME, that will do
 404                                        exactly the same command as OLD
 405                                        NAME.
 406 `ban'                                  Bans MASK or NICK from CHANNEL. You
 407                                        need to be a trusted user to ban
 408                                        with a MASK.
 409 `banlist'
 410 `channels'                             Prints the channel(s) where the bot
 411                                        is currently.
 412 `cycle'        Yes                     Makes the bot leave and join
 413                                        CHANNEL.
 414 `dcclist'                              Gives the list of all DCC Chat
 415                                        connections.
 416 `deban'        Yes                     Debans MASK or NICK from CHANNEL.
 417                                        You need to be a trusted user to
 418                                        deban with a MASK.
 419 `delserver'                            Deletes server from server list
 420                                        whose number in the server list is
 421                                        SERVER NUMBER.
 422 `deluser'                              Removes NICK or MASK from the
 423                                        userlist.
 424 `delshit'                              Removes NICK or MASK from the
 425                                        shitlist.
 426 `deop'         Yes                     Deops MASK or NICK on CHANNEL.
 427 `die'                                  Makes the bot stop immediately.
 428 `do'
 429 `execute'                              *Only available if scripting
 430                                        support is enabled*
 431 `help'
 432 `ident'                                Identifies you on the bot. Note
 433                                        that you should not use this
 434                                        command in public ...
 435 `invite'       Yes                     Invites NICK on CHANNEL.
 436 `join'                                 Makes the bot join CHANNEL.
 437 `keep'         Yes                     Sets the MODES that the bot will
 438                                        keep for CHANNEL.
 439 `kick'         Yes                     Kicks MASK or NICK out of CHANNEL,
 440                                        because of REASON. You need to be a
 441                                        trusted user to use a MASK.
 442 `kickban'      Yes                     Bans then kicks MASK or NICK out of
 443                                        CHANNEL, because of REASON. You need
 444                                        to be a trusted user to use a MASK.
 445 `load'                                 Reloads the userlist from disk.
 446 `loadscript'                           *Only available if scripting
 447                                        support is enabled*
 448 `lock'                                 Locks topic on CHANNEL.
 449 `mode'         Yes                     Sends MODE STRING as mode for
 450                                        CHANNEL.
 451 `msg'
 452 `names'        Yes                     Shows the nicknames and status of
 453                                        users on CHANNEL.
 454 `nextserver'                           Makes the bot connect to the next
 455                                        server in its server list.
 456 `nick'                                 Makes the bot use nickname NICK.
 457 `nslookup'                             Does a nameserver query about NICK
 458                                        host, HOST or IP ADDRESS.
 459 `op'           Yes                     Ops NICK on CHANNEL.
 460 `part'         Yes                     Makes the bot leave CHANNEL.
 461 `password'                             Changes your password on the bot.
 462                                        Use `NONE' as password if you want
 463                                        to clear it. Do not use this
 464                                        command in public!
 465 `reconnect'                            Makes the bot reconnect to its
 466                                        current server.
 467 `rspymessage'                          Removes you from the spy list.
 468 `save'                                 Saves the userlist.
 469 `say'          Yes                     Makes the bot say MESSAGE on
 470                                        CHANNEL.
 471 `server'                               Select the server to connect to.
 472                                        SERVER NUMBER is the number of the
 473                                        server in the serverlist.
 474 `serverlist'                           Shows the bot's serverlist.
 475 `setfloodrate'
 476 `setversion'
 477 `shitlist'                             Shows the bot's shitlist.
 478 `spylist'                              Shows the bot's spylist.
 479 `spymessage'                           Adds you to the spylist
 480 `stats'        Yes                     Gives CHANNEL's statistics.
 481 `tban'         Yes                     Bans NICK or MASK from CHANNEL for
 482                                        TIME seconds.
 483 `tkban'        Yes                     Bans NICK or MASK from CHANNEL for
 484                                        TIME seconds, then kicks him/them
 485                                        because of REASON.
 486 `topic'        Yes                     If no TOPICis given, prints
 487                                        CHANNEL's topic. Otherwise, the bot
 488                                        will change CHANNEL's topic to
 489                                        TOPIC.
 490 `unlock'       Yes                     Makes the bot unlock topic on
 491                                        CHANNEL
 492 `userlist'                             Shows the bot's userlist
 493 `who'          Yes                     Show your level on CHANNEL
 494 `whois'        Yes                     Shows information about NICK on
 495                                        CHANNEL
 496
 497 \1f
 498 File: bobot++.info,  Node: Scripting,  Next: Concept Index,  Prev: Using the Bot,  Up: Top
 499
 500 4 Scripting
 501 ***********
 502
 503 Bobot++'s most powerful feature is its scripting system. You write
 504 scripts using Guile Scheme. This manual does not cover how to use Guile
 505 or how to learn Scheme. *Note Guile Reference Manual: (guile)Top, for
 506 the Guile reference manual and
 507 `http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html' for a
 508 good tutorial on Scheme.
 509
 510    Note that in previous versions the scripting commands where in the
 511 form `bot-FUNCTION'. They are now in the form `bot:FUNCTION'. The old
 512 names are still available, but are deprecated and will be removed in
 513 Bobot++ 3.0. New commands are only available with the `bot:' prefix.
 514 The command `perl -pi -e ``s/bot-/bot:/g'' YOUR-FILES' should be enough
 515 to convert your code to use the new functions.
 516
 517    *NOTE*: All arguments to functions and hooks called by the bot are
 518 strings unless otherwise specified.
 519
 520 * Menu:
 521
 522 * Adding New Commands::
 523 * Hooks::
 524 * Scheme User Levels::
 525 * Sending Messages::
 526 * Misc Scripting Stuff::
 527
 528 \1f
 529 File: bobot++.info,  Node: Adding New Commands,  Next: Hooks,  Prev: Scripting,  Up: Scripting
 530
 531 4.1 Adding New Commands
 532 =======================
 533
 534 Adding a new command is simple. To register a new command use
 535 `bot:addcommand'.
 536
 537  -- Function: bot:addcommand name func needs-channel? num-of-args
 538           min-level
 539      The NAME is a string representing the name of the command being
 540      added.  FUNC is a function accepting NUM-OF-ARGS arguments.
 541      NEEDS-CHANNEL? is a bool that is true if the function needs the
 542      channel name as its first arg, and false otherwise.  NUM-OF-ARGS
 543      is the number of args FUNC will take and must be within zero (0)
 544      and twenty (20).  MIN-LEVEL is one of the *Note Scheme User
 545      Levels::.  A user must be at least a `min-level' user to use the
 546      new command.  None of the arguments are guaranteed to be passed;
 547      if they aren't they are set to the empty string `""'.  An example
 548      of a new command would be:
 549
 550           (define (hello channel name)
 551             (if (string=? name "")
 552               (bot:say channel "Hello world!")
 553               (bot:say channel (string-append "Hello " name "!")))
 554
 555           (bot:addcommand "hello" hello #t 2 0)
 556
 557      This will display "Hello World!" if called as `!hello' and "Hello
 558      World USER" if called as `!hello USER'.
 559
 560 \1f
 561 File: bobot++.info,  Node: Hooks,  Next: Scheme User Levels,  Prev: Adding New Commands,  Up: Scripting
 562
 563 4.2 Hooks
 564 =========
 565
 566 Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
 567 and tiny fugue (a MUD bot) hooks with a little bit of extra stuff added
 568 in. A hook is called when a regular expression is matched against a
 569 message sent to or by the bot.
 570
 571    Bobot++ uses different hook types for each IRC message type, and also
 572 includes a hook for accessing raw irc messages. Hooks are tagged with a
 573 priority and a flag that specifies whether to call the next hook that
 574 matches after calling the current one or to stop processing.
 575
 576    Hooks are processed from the highest to lowest priority, with
 577 fallthrough hooks of equal priority to non-fallthrough hooks being
 578 executed first.
 579
 580 * Menu:
 581
 582 * Creating a Hook::
 583 * Hook Types::
 584
 585 \1f
 586 File: bobot++.info,  Node: Creating a Hook,  Next: Hook Types,  Prev: Hooks,  Up: Hooks
 587
 588 4.2.1 Creating a Hook
 589 ---------------------
 590
 591 To add a new hook you use the function `bot:addhook'.
 592
 593  -- Function: bot:addhook type regex function [pri fall name]
 594      TYPE specifies the type of hook (the types of hooks are listed in
 595      *Note Hook Types::).
 596
 597      REGEX is a standard regular expression. If REGEX is matched,
 598      FUNCTION will be called.
 599
 600      FUNCTION will take a different number of args depending on the
 601      hook type.
 602
 603      PRI specifies the priority of the hook--higher priority hooks are
 604      executed first. This argument is optional and defaults to `0'.
 605
 606      FALL is `#t' if the hook is a fallthrough hook and `#f' is the
 607      hook is not a fallthrough hook. This arg is also optional and
 608      defaults to `#t'.
 609
 610      NAME is the optional name of the hook that defaults to
 611      `"DEFAULT"'. If you set the name then you can have more than one
 612      hook that matches the same regexp, as long as they have the same
 613      name. E.g. in a log script you could have the regexps for the log
 614      function all be `".*"' and set their names to `"log"' to avoid a
 615      conflict with other hooks.
 616
 617 \1f
 618 File: bobot++.info,  Node: Hook Types,  Prev: Creating a Hook,  Up: Hooks
 619
 620 4.2.2 Hook Types
 621 ----------------
 622
 623 The following sections document the different hooks Bobot++ exposes.
 624
 625    The general format of each hook description is as if it were a
 626 function to be defined, but these describe the function to be passwd to
 627 `bot:add-hook'.  Do _not_ name your functions these names.
 628
 629    That said, here is the list of available hooks functions.  FIXME:
 630 write docs
 631
 632 * Menu:
 633
 634 * Received Message Hooks::
 635 * Sent Message Hooks::
 636 * DCC CHAT Hooks::
 637 * Miscellaneous Hooks::
 638
 639 \1f
 640 File: bobot++.info,  Node: Received Message Hooks,  Next: Sent Message Hooks,  Prev: Hook Types,  Up: Hook Types
 641
 642 4.2.2.1 Receieved Message Hooks
 643 ...............................
 644
 645 The following hooks are triggered when a mesage is received by the bot.
 646
 647  -- Function: hooks/action from to action
 648      This hook is triggered when someone performs an action.
 649
 650      FROM is the nickname the person that performed the action.
 651
 652      TO is the target of the action, which is either a channel or the
 653      Bot's nick if the user private messages the bot.
 654
 655      ACTION is the text of the action. E.g. if someone did `* foobar
 656      does baz', then ACTION would be the string `"does baz"'.
 657
 658  -- Function: hooks/nickname old-nick new-nick
 659      This hook is called when someone changes his nickname from
 660      OLD-NICK to NEW-NICK.
 661
 662  -- Function: hooks/signoff nick message
 663      This hook is called when someone signs off of IRC.
 664
 665      NICK is the nickname of the person signing off.
 666
 667      MESSAGE is his quit message
 668
 669  -- Function: hooks/ctcp nick to command rest
 670      This hook is called when a CTCP request is received by the bot.
 671
 672      NICK is the nickname of the sender.
 673
 674      TO is the target of the CTCP request. This will either be a
 675      channel the bot is in, or the nickname of the bot.
 676
 677      COMMAND is the CTCP command issued.
 678
 679      REST contains the arguments to the CTCP command.
 680
 681  -- Function: hooks/ctcp-reply nick command rest
 682      This hook is called when a CTCP REPLY is received. This occurs when
 683      the bot has sent a CTCP request to another client. The CTCP REPLY
 684      is always addressed to the bot directly.
 685
 686      NICK is the nickname of the person who replied.
 687
 688      COMMAND is the command to which NICK is replying.
 689
 690      REST contains the body of the reply.
 691
 692  -- Function: hooks/disconnect server intentional
 693      This is called when the bot is disconnected from a server.
 694
 695      SERVER is the hostname of the server from which the bot was
 696      disconnected.
 697
 698      INTENTIONAL is a flag set to `#t' when the bot disonnected from
 699      the server as the result of a command (issued by a user from IRC,
 700      SIGHUP, or from a script), or `#f' when the bot disconnected from
 701      the server unintentionally..
 702
 703  -- Function: hooks/invite nick channel
 704      This hook is called when a user invited the bot to join a channel.
 705
 706      NICK is the nickname of the user who sent the invite.
 707
 708      CHANNEL is the channel to which the bot was invited.
 709
 710  -- Function: hooks/join nick channel
 711      This is called when a user or the bot joins a channel.
 712
 713      NICK is the nickname of the user who joined CHANNEL. This may be
 714      the bot's nickname (the IRC server sends the JOIN command back to
 715      the the bot after it joins a channel).
 716
 717      CHANNEL is the channel that was joined
 718
 719  -- Function: hooks/kick target from channel reason
 720      This hook is called when a user, including the bot, is kicked out
 721      of a channel.
 722
 723      TARGET is the nick of the user who was kicked. This may be the
 724      bot's nick.
 725
 726      FROM is the nick of the user who issued the kick. This may also be
 727      the bot's nick.
 728
 729      CHANNEL is the channel the kick was issued in.
 730
 731      REASON is the reason the user was kicked.
 732
 733  -- Function: hooks/part nick channel
 734      This hook is called when a user parts a channel.
 735
 736      NICK is the user who parted the channel. This may be the bot.
 737
 738      CHANNEL is the channel from which the user parted.
 739
 740  -- Function: hooks/mode nick target modes
 741      This hook is called when someone sets the modes of TARGET.
 742
 743      NICK is the user who set the modes. This may be the bot.
 744
 745      TARGET is the target of the MODE command. This may be a channel or
 746      a user. If it is a user, it may be the bot.
 747
 748      MODES is the MODE string.
 749
 750  -- Function: hooks/message nick message
 751      This hook is called when someone sends a private message to the
 752      bot.
 753
 754      NICK is the nickname of the user who sent the message.
 755
 756      MESSAGE is the message the user sent.
 757
 758  -- Function: hooks/notice nick message
 759      This hook is called when a user send a private notice to the bot.
 760
 761      NICK is the user who sent the notice.
 762
 763      MESSAGE is the message the user sent.
 764
 765  -- Function: hooks/public nick channel message
 766      This hook is called when a user sends a normal message to a
 767      channel.
 768
 769      NICK is the user who sent the message.
 770
 771      CHANNEL is the channel to which the message was sent.
 772
 773      MESSAGE is the message that was sent.
 774
 775  -- Function: hooks/public-notice nick channel message
 776      This hook is called when a user send a notice to a channel.
 777
 778      NICK is the user who sent the notice.
 779
 780      CHANNEL is the channel to which the notice was sent.
 781
 782      MESSAGE is the message that was sent.
 783
 784  -- Function: hooks/raw raw-message
 785      This hook is called every time a message is received. This matches
 786      on the raw message text and passes the hook function the raw IRC
 787      message.
 788
 789      RAW-MESSAGE is the raw IRC message.
 790
 791  -- Function: hooks/topic nick channel new-topic
 792      This hook is called when a user changes the topic in a channel.
 793
 794      NICK is the user who set the topic. This may be the bot.
 795
 796      CHANNEL is the channel that's topic was changed.
 797
 798      NEW-TOPIC is the new topic.
 799
 800 \1f
 801 File: bobot++.info,  Node: Sent Message Hooks,  Next: DCC CHAT Hooks,  Prev: Received Message Hooks,  Up: Hook Types
 802
 803 4.2.2.2 Sent Message Hooks
 804 ..........................
 805
 806 These hooks are called when the bot sends a message. MYNICK is always
 807 the bot's nick and will not be documented in each hook description.
 808
 809  -- Function: hooks/send/public mynick channel message
 810      This hook is called when the bot sends a normal message to a
 811      channel.
 812
 813      CHANNEL is the channel to which the bot sent the message.
 814
 815      MESSAGE is the message the bot sent.
 816
 817  -- Function: hooks/send/message mynick to message
 818      This hook is called when the bot sends a private message to a user.
 819
 820      TO is the nick of the user to whom the message was sent.
 821
 822      MESSAGE is the message that was sent.
 823
 824  -- Function: hooks/send/action mynick to message
 825      This hook is called when the bot sents an action to a channel or a
 826      user.
 827
 828      TO is the channel or nick of the user to which the action was sent.
 829
 830      MESSAGE is the text of the action.
 831
 832  -- Function: hooks/send/ctcp mynick to command message
 833      This hook is called when the bot sends a CTCP message _other than_
 834      an ACTION to a channel or user.
 835
 836      TO is the channel or nick of the user to which the CTCP was sent.
 837
 838      COMMAND is the CTCP command that was sent.
 839
 840      MESSAGE is a string containing the arguments to the CTCP command.
 841
 842 \1f
 843 File: bobot++.info,  Node: DCC CHAT Hooks,  Next: Miscellaneous Hooks,  Prev: Sent Message Hooks,  Up: Hook Types
 844
 845 4.2.2.3 DCC CHAT Hooks
 846 ......................
 847
 848 These hooks are called when a user initializes a DCC CHAT and when the
 849 bot receives messages from the user in a DCC CHAT.
 850
 851  -- Function: hooks/dcc/chat-begin from
 852      This hook is called when a user begins a DCC CHAT with the bot.
 853      FROM is the user's address in the form `nick!user@host'.
 854
 855  -- Function: hooks/dcc/chat-message from message
 856      This hook is called when a user sends a message to the bot through
 857      a DCC CHAT.
 858
 859      FROM is the user's address in the form `nick!user@host'.
 860
 861      MESSAGE is the message the user sent to the bot.
 862
 863 \1f
 864 File: bobot++.info,  Node: Miscellaneous Hooks,  Prev: DCC CHAT Hooks,  Up: Hook Types
 865
 866 4.2.2.4 Miscellaneous Hooks
 867 ...........................
 868
 869  -- Function: hooks/flood nick
 870      This hook is called when a user is detected flooding the bot.
 871
 872      NICK is the nickname of the user flooding the bot.
 873
 874  -- Function: hooks/timer time
 875      This hook is called once a minute. The regex is *not* used.
 876
 877      TIME is the in zero-padded `hh:mm' format.
 878
 879 \1f
 880 File: bobot++.info,  Node: Scheme User Levels,  Next: Sending Messages,  Prev: Hooks,  Up: Scripting
 881
 882 4.3 Scheme User Levels
 883 ======================
 884
 885 There are five levels that a user may be when interfacing with a bot:
 886 NONE, USER, TRUSTED_USER, FRIEND, MASTER. The Scheme variables for the
 887 user levels are `bot:user-none', `bot:user-user', `bot:user-trusted',
 888 `bot:user-friend', and `bot:user-master'. See *Note User Levels:: for
 889 more information on User Levels.
 890
 891    When adding a new command, think about who should be able to use it.
 892 Is your command a general purpose command that helps the channel (e.g.
 893 `!seen') that everyone should be able to use? Or is it something that
 894 should be restricted? See *Note User Levels:: for information on what
 895 level users can do what with the built in bot commands and think about
 896 what level a user your command is targetted towards. You must be _very_
 897 careful when giving new commands to lower level users because you can
 898 do basically everything the bot can do with a script. As the scripting
 899 interface becomes more powerful, you must think more about what users
 900 can use new commands you add.
 901
 902 \1f
 903 File: bobot++.info,  Node: Sending Messages,  Next: Misc Scripting Stuff,  Prev: Scheme User Levels,  Up: Scripting
 904
 905 4.4 Sending Messages
 906 ====================
 907
 908 There are several types of messages you can send with Bobot++ from
 909 scripts. There is the simple, but rather limited, `bot:say',
 910 `bot:action' and `bot:msg', and the more powerful, but lower level,
 911 `bot:send-MESSAGE' functions. Most bots will probably only need the
 912 higher level functions, but for the sake of why-not Bobot++ lets you
 913 use the lower level functions (in progress).
 914
 915 * Menu:
 916
 917 * High Level Message Functions::
 918 * Low Level Message Functions::
 919
 920 \1f
 921 File: bobot++.info,  Node: High Level Message Functions,  Next: Low Level Message Functions,  Prev: Sending Messages,  Up: Sending Messages
 922
 923 4.4.1 "High Level" Message Functions
 924 ------------------------------------
 925
 926  -- Function: bot:say channel message
 927      Send a public or private MESSAGE to CHANNEL.
 928
 929      Sends a normal text message, as if a user had typed it in.  The
 930      DEST can be a nickname or a channel.
 931
 932  -- Function: bot:action channel message
 933      Send an "action" type  MESSAGE to CHANNEL
 934
 935  -- Function: bot:msg nick message
 936      The same as if a user typed `/msg nick message' to their IRC
 937      client.
 938
 939  -- Function: bot:notice target message
 940      Sends MESSAGE as a NOTICE to TARGET. TARGET may be a user (nick)
 941      or a channel. This returns 0 on success.
 942
 943 \1f
 944 File: bobot++.info,  Node: Low Level Message Functions,  Prev: High Level Message Functions,  Up: Sending Messages
 945
 946 4.4.2 "Low Level" Message Functions
 947 -----------------------------------
 948
 949 The "Low Level" messaging functions allow you to do things like send
 950 CTCP messages. You probably want to read rfc 2812 and the CTCP spec
 951 before using these. If you have no idea what these do, read rfc 2812
 952 (IRC Client Protocol) and CTCP spec. These functions all return
 953 `*unspecified*' always, so don't use the return value for anything.
 954
 955  -- Function: bot:send-ctcp to command message
 956      TO is the target of your CTCP message, COMMAND is the CTCP
 957      command, and MESSAGE is the message (or arguments) of the command.
 958      Make sure to `bot:ctcp-quote' the message!
 959
 960  -- Function: bot:send-ctcp-reply to command message
 961      TO is the target of your CTCP reply, COMMAND is the CTCP command,
 962      and MESSAGE is the message (or arguments) of the command. Make
 963      sure to `bot:ctcp-quote' the message!
 964
 965      This is used to reply to a ctcp that the bot has received.
 966
 967 \1f
 968 File: bobot++.info,  Node: Misc Scripting Stuff,  Prev: Sending Messages,  Up: Scripting
 969
 970 4.5 Misc. Scripting Stuff
 971 =========================
 972
 973 These are a few useful things that I thought people writing scripts
 974 might want to know.
 975
 976    If you want to execute code when the bot exits, just do `add-hook!
 977 bot:exit-hook THUNK' where THUNK is an argumentless procedure (a
 978 thunk). When the bot exits your thunk will be called.
 979
 980      [ I didn't know where to put any of these, so I just stuck them in
 981      here.
 982
 983      There probably needs to be several sections added, like dealing
 984      with users (kicking, added, etc), dealing with the bot (channels,
 985      nickname of the bot, etc), server issues (serverlist), useful
 986      tools (nslookup, whois), and do on. ]
 987
 988  -- Function: bot:adduser nick-or-mask cbannel-mask level prot auto-op
 989      Adds an user to the userlist, for a `nick!user@host' matching the
 990      one given, on a channel matching the CHANNELMASK given.
 991
 992      The LEVEL can be:      The PROT can be:       The AUTO-OP can be:
 993      0 - No level           0 - No protection      0 - No auto-op
 994      1 - User               1 - No ban             1 - Op on join
 995      2 - Trusted User       2 - No kick
 996      3 - Friend             3 - No deop
 997      4 - Master
 998
 999
1000  -- Function: bot:addserver hostname ip-address [portnumber]
1001      Adds the server specified by HOSTNAME or IP-ADDRESS to the server
1002      list.
1003
1004  -- Function: bot:addshit nick-or-mask channel-mask level [time reason]
1005      Adds an user to the shitlist, for a nick!user@host matching the
1006      one given, on a channel matching the CHANNELMASK given.
1007
1008           The LEVEL can be:
1009             0 - No shit
1010             1 - No op
1011             2 - Kick and Ban on join
1012             3 - Kick and Ban on join, no deban
1013
1014
1015  -- Function: bot:ban channel mask-or-nick
1016      Bans MASK or NICK from CHANNEL. You need to be a trusted user to
1017      ban with a MASK.
1018
1019  -- Function: bot:change-command-level nick-or-mask channel-mask
1020           new-level
1021      Gives NICK or MASK level NEW-LEVEL on channel(s) CHANNEL-MASK.
1022      Note that you can not change level for someone whose level is
1023      greater than yours, and that you can not give a level greater than
1024      yours.
1025
1026  -- Function: bot:cycle channel
1027      Makes the bot leave and join CHANNEL.
1028
1029  -- Function: bot:deban channel mask-or-nick
1030      Debans MASK or NICK from CHANNEL. You need to be a trusted user to
1031      deban with a MASK.
1032
1033  -- Function: bot:delserver server-number
1034      Deletes server from server list whose number in the server list is
1035      SERVER-NUMBER
1036
1037  -- Function: bot:deluser nick-or-mask channel-mask
1038      Removes NICK or MASK from the userlist.
1039
1040  -- Function: bot:delshit nick-or-mask channel-mask
1041      Removes NICK or MASK from the shitlist.
1042
1043  -- Function: bot:deop channel mask-or-nick
1044      Deops MASK or NICK on CHANNEL.
1045
1046  -- Function: bot:die reason
1047      Makes the bot stop immediately.
1048
1049  -- Function: bot:do ?
1050
1051  -- Function: bot:invite channel nick
1052      Invites NICK on CHANNEL.
1053
1054  -- Function: bot:join channel
1055      Makes the bot join CHANNEL.
1056
1057  -- Function: bot:keep channel modes
1058      Sets the MODES that the bot will keep for CHANNEL.  See also STATS.
1059
1060  -- Function: bot:kick channel mask-or-nick [reason]
1061      Kicks MASK or NICK out of CHANNEL, because of REASON.  You need to
1062      be a trusted user to use a MASK.
1063
1064  -- Function: bot:kickban channel mask-or-nick [reason]
1065      Bans then kicks MASK or NICK out of CHANNEL, because of REASON.
1066      You need to be a trusted user to use a MASK.
1067
1068  -- Function: bot:lock channel
1069      Locks topic on CHANNEL.
1070
1071  -- Function: bot:logport
1072      [ Probably returns the log port? ]
1073
1074  -- Function: bot:mode channel mode-string
1075      Sends MODE-STRING as mode for CHANNEL.
1076
1077  -- Function: bot:nextserver
1078      Makes the bot connect to the next server in its server list.
1079
1080  -- Function: bot:nick nick
1081      Makes the bot use nickname NICK.
1082
1083  -- Function: bot:op channel nick
1084      Ops NICK on CHANNEL.
1085
1086  -- Function: bot:part channel
1087      Makes the bot leave CHANNEL.
1088
1089  -- Function: bot:reconnect
1090      Makes the bot reconnect to its current server.
1091
1092  -- Function: bot:server server-number
1093      Select the server to connect to. SERVER-NUMBER is the number of
1094      the server in the serverlist.
1095
1096  -- Function: bot:setfloodrate ?
1097
1098  -- Function: bot:setversion ?
1099
1100  -- Function: bot:tban channel nick-or-mask time
1101      Bans NICK or MASK from CHANNEL for TIME seconds.
1102
1103  -- Function: bot:tkban channel nick-or-mask time [reason]
1104      Bans NICK or MASK from CHANNEL for TIME seconds, then kicks
1105      him/them because of REASON.
1106
1107  -- Function: bot:topic channel topic
1108      If no TOPIC is given, prints CHANNEL's topic. Otherwise, the bot
1109      will change CHANNEL's topic to TOPIC.
1110
1111  -- Function: bot:unlock channel
1112      Makes the bot unlock topic on CHANNEL.
1113
1114  -- Function: bot:getnickname
1115      [ Gets the bot's nickname? ]
1116
1117  -- Function: bot:getserver
1118
1119  -- Function: bot:getserverlist
1120
1121  -- Function: bot:flush
1122      [ Flushes the socket to the server? ]
1123
1124  -- Function: bot:flushport
1125      [ Flushes the log port? ]
1126
1127  -- Function: bot:random ?
1128      [ Returns a random number?  What range?  Why? ]
1129
1130  -- Function: bot:delcommand
1131      [ Probably deletes a command added with `bot:addcommand' ? ]
1132
1133  -- Function: bot:addtimer ? ?
1134
1135  -- Function: bot:deltimer ?
1136
1137  -- Function: bot:dcc-chat-send ? ?
1138
1139      [ And what about the stuff defined in `bobot-utils.scm' ? I just
1140      added it here so it could be somewhere.  There should also be a
1141      section dealing with modules.  How to use them.  What module
1142      scripts are in.  What module bobot++ provided primites are in.
1143      And so on. ]
1144
1145  -- Function: bot:log . messages
1146      Write as many MESSAGES as you want to the log.  If the arg is a
1147      thunk it will be executed and it's output will be written to the
1148      log.
1149
1150  -- Function: bot:load file
1151
1152  -- Function: bot:load-module module-spec
1153
1154  -- Function: bot:use-module module-spec
1155
1156  -- Function: bot:match-not-channel regex
1157      match-not-channel adds a prefix regex to your REGEX so it doesn't
1158      match the sender or channel in a PUBLIC message
1159
1160  -- Function: bot:match-to-me regex
1161      match-to-me matches text that was addressed to the bot with a ':',
1162      ',',  or nothing after the bot name.
1163
1164  -- Function: bot:sent-to-me? message
1165
1166  -- Function: bot:ctcp-quote message
1167      Returns the CTCP quoted message Input _MUST NOT_ contain the
1168      trailing `\r\n' (it is added by the message sending code).
1169
1170  -- Variable: %bot:loadpath
1171
1172  -- Function: %bot:load-extensions
1173
1174 \1f
1175 File: bobot++.info,  Node: Concept Index,  Next: Function Index,  Prev: Scripting,  Up: Top
1176
1177 Concept Index
1178 *************
1179
1180