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