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