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