bobot++.info

   1 This is bobot++.info, produced by makeinfo version 4.8 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 must be a trusted user to deban with
 691      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 must 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  -- Command: topic channel [topic]
 725      Sets the topic in CHANNEL to TOPIC. If TOPIC is not supplied the
 726      current topic is sent as a notice to the user calling the command.
 727
 728  -- Command: unlock channel
 729      Unlocks the topic on CHANNEL
 730
 731 \1f
 732 File: bobot++.info,  Node: Spylist Commands,  Next: User List Commands,  Prev: Channel Control,  Up: Built-In Commands
 733
 734 3.3.4 Spylist Commands
 735 ----------------------
 736
 737    * `spylist'    Shows the bot's spylist.
 738
 739    * `spymessage'    Adds you to the spylist
 740
 741    * `rspymessage'    Removes you from the spy list.
 742
 743
 744 \1f
 745 File: bobot++.info,  Node: User List Commands,  Next: Server List Commands,  Prev: Spylist Commands,  Up: Built-In Commands
 746
 747 3.3.5 User List Commands
 748 ------------------------
 749
 750  -- Command: adduser mask
 751      Adds the user
 752
 753    `deluser'    Removes NICK or MASK from the userlist.
 754
 755  -- Command: save
 756      Saves the userlist.
 757
 758    `userlist'    Shows the bot's userlist
 759
 760 \1f
 761 File: bobot++.info,  Node: Server List Commands,  Next: Shit List Commands,  Prev: User List Commands,  Up: Built-In Commands
 762
 763 3.3.6 Server List Commands
 764 --------------------------
 765
 766    * `addserver'    Adds the server specified by HOST NAME or IP
 767      ADDRESS to the server list.
 768
 769    * `delserver'    Deletes server from server list whose number in the
 770      server list is SERVER NUMBER.
 771
 772    * `nextserver'    Makes the bot connect to the next server in its
 773      server list.
 774
 775    * `reconnect'    Makes the bot reconnect to its current server.
 776
 777    * `server'    Select the server to connect to. SERVER NUMBER is the
 778      number of the server in the serverlist.
 779
 780    * `serverlist'    Shows the bot's serverlist.
 781
 782
 783 \1f
 784 File: bobot++.info,  Node: Shit List Commands,  Next: Channel Info,  Prev: Server List Commands,  Up: Built-In Commands
 785
 786 3.3.7 Shit List Commands
 787 ------------------------
 788
 789    * `addshit'
 790
 791    * `delshit'    Removes NICK or MASK from the shitlist
 792
 793    * `shitlist'    Shows the bot's shitlist.
 794
 795
 796 \1f
 797 File: bobot++.info,  Node: Channel Info,  Next: Scripting Commands,  Prev: Shit List Commands,  Up: Built-In Commands
 798
 799 3.3.8 Channel Info
 800 ------------------
 801
 802    * `banlist'
 803
 804    * `channels'    Prints the channel(s) where the bot is currently.
 805
 806    * `names'  Yes   Shows the nicknames and status of users on CHANNEL.
 807
 808    * `stats'  Yes   Gives CHANNEL's statistics.
 809
 810 \1f
 811 File: bobot++.info,  Node: Scripting Commands,  Next: Authentication Commands,  Prev: Channel Info,  Up: Built-In Commands
 812
 813 3.3.9 Scripting Commands
 814 ------------------------
 815
 816    * `execute'    *Only available if scripting support is enabled*
 817
 818    * `load'    Reloads the userlist from disk.
 819
 820    * `loadscript'    *Only available if scripting support is enabled*
 821
 822
 823 \1f
 824 File: bobot++.info,  Node: Authentication Commands,  Next: Miscellaneous Commands,  Prev: Scripting Commands,  Up: Built-In Commands
 825
 826 3.3.10 Authentication Commands
 827 ------------------------------
 828
 829    * `ident'    Identifies you on the bot. Note that you should not use
 830      this command in public ...
 831
 832    * `password'    Changes your password on the bot. Use `NONE' as
 833      password if you want to clear it. Do not use this command in
 834      public!
 835
 836
 837 \1f
 838 File: bobot++.info,  Node: Miscellaneous Commands,  Prev: Authentication Commands,  Up: Built-In Commands
 839
 840 3.3.11 Miscellaneous Commands
 841 -----------------------------
 842
 843    * `alias'    Makes an alias, and adds the function NEW NAME, that
 844      will do exactly the same command as OLD NAME.
 845
 846    * `dcclist'    Gives the list of all DCC Chat connections.
 847
 848    * `help'
 849
 850    * `nslookup'    Does a nameserver query about NICK host, HOST or IP
 851      ADDRESS.
 852
 853    * `who'  Yes   Show your level on CHANNEL
 854
 855    * `whois'  Yes   Shows information about NICK on CHANNEL
 856
 857
 858 \1f
 859 File: bobot++.info,  Node: Scripting,  Next: Concept Index,  Prev: Using the Bot,  Up: Top
 860
 861 4 Scripting
 862 ***********
 863
 864 Bobot++'s most powerful feature is its scripting system. You write
 865 scripts using Guile Scheme. This manual does not cover how to use Guile
 866 or how to learn Scheme. *Note Guile Reference Manual: (guile)Top, for
 867 the Guile reference manual and
 868 `http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html' for a
 869 good tutorial on Scheme.
 870
 871    Note that in previous versions the scripting commands where in the
 872 form `bot-FUNCTION'. They are now in the form `bot:FUNCTION'. The old
 873 names are still available, but are deprecated and will be removed in
 874 Bobot++ 3.0. New commands are only available with the `bot:' prefix.
 875 The command `perl -pi -e ``s/bot-/bot:/g'' YOUR-FILES' should be enough
 876 to convert your code to use the new functions.
 877
 878    *NOTE*: All arguments to functions and hooks called by the bot are
 879 strings unless otherwise specified.
 880
 881 * Menu:
 882
 883 * Adding New Commands::
 884 * Hooks::
 885 * Sending Messages::
 886 * Misc Scripting Stuff::
 887 * Scheme Commands::
 888 * Query Functions::
 889
 890 \1f
 891 File: bobot++.info,  Node: Adding New Commands,  Next: Hooks,  Prev: Scripting,  Up: Scripting
 892
 893 4.1 Adding New Commands
 894 =======================
 895
 896 Adding a new command is simple. To register a new command use
 897 `bot:addcommand'.
 898
 899  -- Function: bot:addcommand name func needs-channel? num-of-args
 900           min-level
 901      The NAME is a string representing the name of the command being
 902      added.  FUNC is a function accepting NUM-OF-ARGS arguments.
 903      NEEDS-CHANNEL? is a bool that is true if the function needs the
 904      channel name as its first arg, and false otherwise.  NUM-OF-ARGS
 905      is the number of args FUNC will take and must be within zero (0)
 906      and twenty (20).  MIN-LEVEL is one of the *Note User Levels::.  A
 907      user must be at least a MIN-LEVEL user to use the new command.
 908      None of the arguments are guaranteed to be passed; if they aren't
 909      they are set to the empty string `""'.  An example of a new
 910      command would be:
 911
 912           (define (hello channel name)
 913             (if (string=? name "")
 914               (bot:say channel "Hello world!")
 915               (bot:say channel (string-append "Hello " name "!")))
 916
 917           (bot:addcommand "hello" hello #t 2 0)
 918
 919      This will display "Hello World!" if called as `!hello' and "Hello
 920      World USER" if called as `!hello USER'.
 921
 922 \1f
 923 File: bobot++.info,  Node: Hooks,  Next: Sending Messages,  Prev: Adding New Commands,  Up: Scripting
 924
 925 4.2 Hooks
 926 =========
 927
 928 Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
 929 and tiny fugue (a MUD bot) hooks with a little bit of extra stuff added
 930 in. A hook is called when a regular expression is matched against a
 931 message sent to or by the bot.
 932
 933    Bobot++ uses different hook types for each IRC message type, and also
 934 includes a hook for accessing raw irc messages. Hooks are tagged with a
 935 priority and a flag that specifies whether to call the next hook that
 936 matches after calling the current one or to stop processing.
 937
 938    Hooks are processed from the highest to lowest priority, with
 939 fallthrough hooks of equal priority to non-fallthrough hooks being
 940 executed first.
 941
 942 * Menu:
 943
 944 * Creating a Hook::
 945 * Hook Types::
 946
 947 \1f
 948 File: bobot++.info,  Node: Creating a Hook,  Next: Hook Types,  Prev: Hooks,  Up: Hooks
 949
 950 4.2.1 Creating a Hook
 951 ---------------------
 952
 953 To add a new hook you use the function `bot:addhook'.
 954
 955  -- Function: bot:addhook type regex function [pri fall name]
 956      TYPE specifies the type of hook (the types of hooks are listed in
 957      *Note Hook Types::).
 958
 959      REGEX is a standard regular expression. If REGEX is matched,
 960      FUNCTION will be called.
 961
 962      FUNCTION will take a different number of args depending on the
 963      hook type.
 964
 965      PRI specifies the priority of the hook--higher priority hooks are
 966      executed first. This argument is optional and defaults to `0'.
 967
 968      FALL is `#t' if the hook is a fallthrough hook and `#f' is the
 969      hook is not a fallthrough hook. This arg is also optional and
 970      defaults to `#t'.
 971
 972      NAME is the optional name of the hook that defaults to
 973      `"DEFAULT"'. If you set the name then you can have more than one
 974      hook that matches the same regexp, as long as they have the same
 975      name. E.g. in a log script you could have the regexps for the log
 976      function all be `".*"' and set their names to `"log"' to avoid a
 977      conflict with other hooks.
 978
 979 \1f
 980 File: bobot++.info,  Node: Hook Types,  Prev: Creating a Hook,  Up: Hooks
 981
 982 4.2.2 Hook Types
 983 ----------------
 984
 985 The following sections document the different hooks Bobot++ exposes.
 986
 987    The general format of each hook description is as if it were a
 988 function to be defined, but these describe the function to be passed to
 989 `bot:add-hook'.  Do _not_ name your functions these names.
 990
 991    That said, here is the list of available hooks functions.  FIXME:
 992 write docs
 993
 994 * Menu:
 995
 996 * Received Message Hooks::
 997 * Sent Message Hooks::
 998 * DCC CHAT Hooks::
 999 * Miscellaneous Hooks::
1000
1001 \1f
1002 File: bobot++.info,  Node: Received Message Hooks,  Next: Sent Message Hooks,  Prev: Hook Types,  Up: Hook Types
1003
1004 4.2.2.1 Receieved Message Hooks
1005 ...............................
1006
1007 The following hooks are triggered when a mesage is received by the bot.
1008
1009  -- Function: hooks/action from to action
1010      This hook is triggered when someone performs an action.
1011
1012      FROM is the nickname the person that performed the action.
1013
1014      TO is the target of the action, which is either a channel or the
1015      Bot's nick if the user private messages the bot.
1016
1017      ACTION is the text of the action. E.g. if someone did `* foobar
1018      does baz', then ACTION would be the string `"does baz"'.
1019
1020  -- Function: hooks/nickname old-nick new-nick
1021      This hook is called when someone changes his nickname from
1022      OLD-NICK to NEW-NICK.
1023
1024  -- Function: hooks/signoff nick message
1025      This hook is called when someone signs off of IRC.
1026
1027      NICK is the nickname of the person signing off.
1028
1029      MESSAGE is his quit message
1030
1031  -- Function: hooks/ctcp nick to command rest
1032      This hook is called when a CTCP request is received by the bot.
1033
1034      NICK is the nickname of the sender.
1035
1036      TO is the target of the CTCP request. This will either be a
1037      channel the bot is in, or the nickname of the bot.
1038
1039      COMMAND is the CTCP command issued.
1040
1041      REST contains the arguments to the CTCP command.
1042
1043  -- Function: hooks/ctcp-reply nick command rest
1044      This hook is called when a CTCP REPLY is received. This occurs when
1045      the bot has sent a CTCP request to another client. The CTCP REPLY
1046      is always addressed to the bot directly.
1047
1048      NICK is the nickname of the person who replied.
1049
1050      COMMAND is the command to which NICK is replying.
1051
1052      REST contains the body of the reply.
1053
1054  -- Function: hooks/disconnect server intentional
1055      This is called when the bot is disconnected from a server.
1056
1057      SERVER is the hostname of the server from which the bot was
1058      disconnected.
1059
1060      INTENTIONAL is a flag set to `#t' when the bot disonnected from
1061      the server as the result of a command (issued by a user from IRC,
1062      SIGHUP, or from a script), or `#f' when the bot disconnected from
1063      the server unintentionally..
1064
1065  -- Function: hooks/invite nick channel
1066      This hook is called when a user invited the bot to join a channel.
1067
1068      NICK is the nickname of the user who sent the invite.
1069
1070      CHANNEL is the channel to which the bot was invited.
1071
1072  -- Function: hooks/join nick channel
1073      This is called when a user or the bot joins a channel.
1074
1075      NICK is the nickname of the user who joined CHANNEL. This may be
1076      the bot's nickname (the IRC server sends the JOIN command back to
1077      the the bot after it joins a channel).
1078
1079      CHANNEL is the channel that was joined
1080
1081  -- Function: hooks/kick target from channel reason
1082      This hook is called when a user, including the bot, is kicked out
1083      of a channel.
1084
1085      TARGET is the nick of the user who was kicked. This may be the
1086      bot's nick.
1087
1088      FROM is the nick of the user who issued the kick. This may also be
1089      the bot's nick.
1090
1091      CHANNEL is the channel the kick was issued in.
1092
1093      REASON is the reason the user was kicked.
1094
1095  -- Function: hooks/part nick channel
1096      This hook is called when a user parts a channel.
1097
1098      NICK is the user who parted the channel. This may be the bot.
1099
1100      CHANNEL is the channel from which the user parted.
1101
1102  -- Function: hooks/mode nick target modes
1103      This hook is called when someone sets the modes of TARGET.
1104
1105      NICK is the user who set the modes. This may be the bot.
1106
1107      TARGET is the target of the MODE command. This may be a channel or
1108      a user. If it is a user, it may be the bot.
1109
1110      MODES is the MODE string.
1111
1112  -- Function: hooks/message nick message
1113      This hook is called when someone sends a private message to the
1114      bot.
1115
1116      NICK is the nickname of the user who sent the message.
1117
1118      MESSAGE is the message the user sent.
1119
1120  -- Function: hooks/notice nick message
1121      This hook is called when a user send a private notice to the bot.
1122
1123      NICK is the user who sent the notice.
1124
1125      MESSAGE is the message the user sent.
1126
1127  -- Function: hooks/public nick channel message
1128      This hook is called when a user sends a normal message to a
1129      channel.
1130
1131      NICK is the user who sent the message.
1132
1133      CHANNEL is the channel to which the message was sent.
1134
1135      MESSAGE is the message that was sent.
1136
1137  -- Function: hooks/public-notice nick channel message
1138      This hook is called when a user send a notice to a channel.
1139
1140      NICK is the user who sent the notice.
1141
1142      CHANNEL is the channel to which the notice was sent.
1143
1144      MESSAGE is the message that was sent.
1145
1146  -- Function: hooks/raw raw-message
1147      This hook is called every time a message is received. This matches
1148      on the raw message text and passes the hook function the raw IRC
1149      message.
1150
1151      RAW-MESSAGE is the raw IRC message.
1152
1153  -- Function: hooks/topic nick channel new-topic
1154      This hook is called when a user changes the topic in a channel.
1155
1156      NICK is the user who set the topic. This may be the bot.
1157
1158      CHANNEL is the channel that's topic was changed.
1159
1160      NEW-TOPIC is the new topic.
1161
1162 \1f
1163 File: bobot++.info,  Node: Sent Message Hooks,  Next: DCC CHAT Hooks,  Prev: Received Message Hooks,  Up: Hook Types
1164
1165 4.2.2.2 Sent Message Hooks
1166 ..........................
1167
1168 These hooks are called when the bot sends a message. MYNICK is always
1169 the bot's nick and will not be documented in each hook description.
1170
1171  -- Function: hooks/send/public mynick channel message
1172      This hook is called when the bot sends a normal message to a
1173      channel.
1174
1175      CHANNEL is the channel to which the bot sent the message.
1176
1177      MESSAGE is the message the bot sent.
1178
1179  -- Function: hooks/send/message mynick to message
1180      This hook is called when the bot sends a private message to a user.
1181
1182      TO is the nick of the user to whom the message was sent.
1183
1184      MESSAGE is the message that was sent.
1185
1186  -- Function: hooks/send/action mynick to message
1187      This hook is called when the bot sents an action to a channel or a
1188      user.
1189
1190      TO is the channel or nick of the user to which the action was sent.
1191
1192      MESSAGE is the text of the action.
1193
1194  -- Function: hooks/send/ctcp mynick to command message
1195      This hook is called when the bot sends a CTCP message _other than_
1196      an ACTION to a channel or user.
1197
1198      TO is the channel or nick of the user to which the CTCP was sent.
1199
1200      COMMAND is the CTCP command that was sent.
1201
1202      MESSAGE is a string containing the arguments to the CTCP command.
1203
1204  -- Function: hooks/send/who who
1205      This is called when the bot sends a WHO message. The regex is
1206      matched on WHO, which is also passed as the only argument to your
1207      function.
1208
1209      WHO is the channel or nick that was WHOed.
1210
1211  -- Function: hooks/send/whois nick
1212      This is called when the bot sends a WHOIS message. The regex is
1213      matched on NICK, which is also passed as the only argument to your
1214      function.
1215
1216      NICK is the nickname of the person who was WHOISed.
1217
1218 \1f
1219 File: bobot++.info,  Node: DCC CHAT Hooks,  Next: Miscellaneous Hooks,  Prev: Sent Message Hooks,  Up: Hook Types
1220
1221 4.2.2.3 DCC CHAT Hooks
1222 ......................
1223
1224 These hooks are called when a user initializes a DCC CHAT and when the
1225 bot receives messages from the user in a DCC CHAT.
1226
1227  -- Function: hooks/dcc/chat-begin from
1228      This hook is called when a user begins a DCC CHAT with the bot.
1229      FROM is the user's address in the form `nick!user@host'.
1230
1231  -- Function: hooks/dcc/chat-end address
1232      This hook is called when a DCC CHAT is purged after being idle for
1233      a while, or when the user closes the DCC CHAT. As such, you cannot
1234      write any more data to the DCC CHAT.
1235
1236      ADDRESS is the address (nick!user@host) of the person on the other
1237      side of the DCC.
1238
1239  -- Function: hooks/dcc/chat-message from message
1240      This hook is called when a user sends a message to the bot through
1241      a DCC CHAT.
1242
1243      FROM is the user's address in the form `nick!user@host'.
1244
1245      MESSAGE is the message the user sent to the bot.
1246
1247 \1f
1248 File: bobot++.info,  Node: Miscellaneous Hooks,  Prev: DCC CHAT Hooks,  Up: Hook Types
1249
1250 4.2.2.4 Miscellaneous Hooks
1251 ...........................
1252
1253  -- Function: hooks/flood nick
1254      This hook is called when a user is detected flooding the bot.
1255
1256      NICK is the nickname of the user flooding the bot.
1257
1258  -- Function: hooks/timer time
1259      This hook is called once a minute. The regex is *not* used.
1260
1261      TIME is the in zero-padded `hh:mm' format.
1262
1263 \1f
1264 File: bobot++.info,  Node: Sending Messages,  Next: Misc Scripting Stuff,  Prev: Hooks,  Up: Scripting
1265
1266 4.3 Sending Messages
1267 ====================
1268
1269 There are several types of messages you can send with Bobot++ from
1270 scripts. They are split into High and Low level message sending
1271 functions. Most bots will only use the high level functions, but the
1272 low level ones are provided for when a bot needs to do things like send
1273 raw IRC messages or CTCP commands.
1274
1275 * Menu:
1276
1277 * High Level Message Functions::
1278 * Low Level Message Functions::
1279
1280 \1f
1281 File: bobot++.info,  Node: High Level Message Functions,  Next: Low Level Message Functions,  Prev: Sending Messages,  Up: Sending Messages
1282
1283 4.3.1 "High Level" Message Functions
1284 ------------------------------------
1285
1286  -- Function: bot:action channel message
1287      Send an "action" type  MESSAGE to CHANNEL
1288
1289  -- Function: bot:msg target message
1290  -- Function: bot:say target message
1291      Send a public or private message to TARGET.
1292
1293      TARGET may be a channel or a nickname.
1294
1295      In versions of Bobot++ prior to 2.1.8 `bot:say' could only send to
1296      channels, and `bot:msg' could only send private messages to users.
1297      They are aliases of the same command now, but it may be worth
1298      using them as they used to for clarity.
1299
1300  -- Function: bot:notice target message
1301      Sends MESSAGE as a NOTICE to TARGET. TARGET may be a user (nick)
1302      or a channel.
1303
1304 \1f
1305 File: bobot++.info,  Node: Low Level Message Functions,  Prev: High Level Message Functions,  Up: Sending Messages
1306
1307 4.3.2 "Low Level" Message Functions
1308 -----------------------------------
1309
1310 The "Low Level" messaging functions allow you to do things like send
1311 CTCP messages. You probably want to read rfc 2812 and the CTCP spec
1312 before using these. If you have no idea what these do, read rfc 2812
1313 (IRC Client Protocol) and CTCP spec. These functions all return
1314 `*unspecified*' always, so don't use the return value for anything.
1315
1316  -- Function: bot:ctcp to command message
1317      TO is the target of your CTCP message, COMMAND is the CTCP
1318      command, and MESSAGE is the message (or arguments) of the command.
1319      Make sure to `bot:ctcp-quote' the message!
1320
1321  -- Function: bot:ctcp-reply to command message
1322      TO is the target of your CTCP reply, COMMAND is the CTCP command,
1323      and MESSAGE is the message (or arguments) of the command. Make
1324      sure to `bot:ctcp-quote' the message!
1325
1326      This is used to reply to a ctcp that the bot has received.
1327
1328 \1f
1329 File: bobot++.info,  Node: Misc Scripting Stuff,  Next: Scheme Commands,  Prev: Sending Messages,  Up: Scripting
1330
1331 4.4 Misc. Scripting Stuff
1332 =========================
1333
1334 These are a few useful things that I thought people writing scripts
1335 might want to know.
1336
1337    If you want to execute code when the bot exits, just do `add-hook!
1338 bot:exit-hook THUNK' where THUNK is an argumentless procedure (a
1339 thunk). When the bot exits your thunk will be called.
1340
1341 * Menu:
1342
1343 * Scheme Commands::
1344 * Query Functions::
1345
1346 \1f
1347 File: bobot++.info,  Node: Scheme Commands,  Next: Query Functions,  Prev: Misc Scripting Stuff,  Up: Scripting
1348
1349 4.5 Scheme Commands
1350 ===================
1351
1352 These scheme functions are the same as the commands.  They allow you to
1353 execute bot commands from scheme scripts.
1354
1355  -- Function: bot:adduser nick-or-mask cbannel-mask level prot auto-op
1356      Adds an user to the userlist, for a `nick!user@host' matching the
1357      one given, on a channel matching the CHANNELMASK given.
1358
1359      The LEVEL can be:      The PROT can be:       The AUTO-OP can be:
1360      0 - No level           0 - No protection      0 - No auto-op
1361      1 - User               1 - No ban             1 - Op on join
1362      2 - Trusted User       2 - No kick
1363      3 - Friend             3 - No deop
1364      4 - Master
1365
1366
1367  -- Function: bot:addserver hostname ip-address [portnumber]
1368      Adds the server specified by HOSTNAME or IP-ADDRESS to the server
1369      list.
1370
1371  -- Function: bot:addshit nick-or-mask channel-mask level [time reason]
1372      Adds an user to the shitlist, for a nick!user@host matching the
1373      one given, on a channel matching the CHANNELMASK given.
1374
1375           The LEVEL can be:
1376             0 - No shit
1377             1 - No op
1378             2 - Kick and Ban on join
1379             3 - Kick and Ban on join, no deban
1380
1381
1382  -- Function: bot:ban channel mask-or-nick
1383      Bans MASK or NICK from CHANNEL. You must be a trusted user to ban
1384      with a MASK.
1385
1386  -- Function: bot:change-command-level nick-or-mask channel-mask
1387           new-level
1388      Gives NICK or MASK level NEW-LEVEL on channel(s) CHANNEL-MASK.
1389      Note that you can not change level for someone whose level is
1390      greater than yours, and that you can not give a level greater than
1391      yours.
1392
1393  -- Function: bot:cycle channel
1394      Makes the bot leave and join CHANNEL.
1395
1396  -- Function: bot:deban channel mask-or-nick
1397      Debans MASK or NICK from CHANNEL. You must be a trusted user to
1398      deban with a MASK.
1399
1400  -- Function: bot:delserver server-number
1401      Deletes server from server list whose number in the server list is
1402      SERVER-NUMBER
1403
1404  -- Function: bot:deluser nick-or-mask channel-mask
1405      Removes NICK or MASK from the userlist.
1406
1407  -- Function: bot:delshit nick-or-mask channel-mask
1408      Removes NICK or MASK from the shitlist.
1409
1410  -- Function: bot:deop channel mask-or-nick
1411      Deops MASK or NICK on CHANNEL.
1412
1413  -- Function: bot:die reason
1414      Makes the bot stop immediately.
1415
1416  -- Function: bot:do ?
1417
1418  -- Function: bot:invite channel nick
1419      Invites NICK on CHANNEL.
1420
1421  -- Function: bot:join channel
1422      Makes the bot join CHANNEL.
1423
1424  -- Function: bot:keep channel modes
1425      Sets the MODES that the bot will keep for CHANNEL.  See also STATS.
1426
1427  -- Function: bot:kick channel mask-or-nick [reason]
1428      Kicks MASK or NICK out of CHANNEL, because of REASON.  You must be
1429      a trusted user to use a MASK.
1430
1431  -- Function: bot:kickban channel mask-or-nick [reason]
1432      Bans then kicks MASK or NICK out of CHANNEL, because of REASON.
1433      You must be a trusted user to use a MASK.
1434
1435  -- Function: bot:lock channel
1436      Locks topic on CHANNEL.
1437
1438  -- Function: bot:mode channel mode-string
1439      Sends MODE-STRING as mode for CHANNEL.
1440
1441  -- Function: bot:nextserver
1442      Makes the bot connect to the next server in its server list.
1443
1444  -- Function: bot:nick nick
1445      Makes the bot use nickname NICK.
1446
1447  -- Function: bot:op channel nick
1448      Ops NICK on CHANNEL.
1449
1450  -- Function: bot:part channel
1451      Makes the bot leave CHANNEL.
1452
1453  -- Function: bot:reconnect
1454      Makes the bot reconnect to its current server.
1455
1456  -- Function: bot:server server-number
1457      Select the server to connect to. SERVER-NUMBER is the number of
1458      the server in the serverlist.
1459
1460  -- Function: bot:setfloodrate ?
1461
1462  -- Function: bot:setversion ?
1463
1464  -- Function: bot:tban channel nick-or-mask time
1465      Bans NICK or MASK from CHANNEL for TIME seconds.
1466
1467  -- Function: bot:tkban channel nick-or-mask time [reason]
1468      Bans NICK or MASK from CHANNEL for TIME seconds, then kicks
1469      him/them because of REASON.
1470
1471  -- Function: bot:topic channel topic
1472      If no TOPIC is given, prints CHANNEL's topic. Otherwise, the bot
1473      will change CHANNEL's topic to TOPIC.
1474
1475  -- Function: bot:unlock channel
1476      Makes the bot unlock topic on CHANNEL.
1477
1478  -- Function: bot:who target
1479      Sends a WHO command to TARGET. TARGET may be either a channel or a
1480      user.
1481
1482  -- Function: bot:whois nick
1483      Sends a WHOIS command to NICK. NICK *must* be a nickname, you
1484      cannot send a WHOIS to a channel.
1485
1486  -- Function: bot:delcommand
1487      [ Probably deletes a command added with `bot:addcommand' ? ]
1488
1489 \1f
1490 File: bobot++.info,  Node: Query Functions,  Prev: Scheme Commands,  Up: Scripting
1491
1492 4.6 Query Functions
1493 ===================
1494
1495      [ I didn't know where to put any of these, so I just stuck them in
1496      here.
1497
1498      There probably needs to be several sections added, like dealing
1499      with users (kicking, added, etc), dealing with the bot (channels,
1500      nickname of the bot, etc), server issues (serverlist), useful
1501      tools (nslookup, whois), and do on. ]
1502
1503    These functions allow scripts to get various bits of information.
1504
1505  -- Function: bot:logport
1506      [ Probably returns the log port? ]
1507
1508  -- Function: bot:getnickname
1509      [ Gets the bot's nickname? ]
1510
1511  -- Function: bot:getserver
1512
1513  -- Function: bot:getserverlist
1514
1515  -- Function: bot:flush
1516      [ Flushes the socket to the server? ]
1517
1518  -- Function: bot:flushport
1519      [ Flushes the log port? ]
1520
1521  -- Function: bot:random ?
1522      [ Returns a random number?  What range?  Why? ]
1523
1524  -- Function: bot:addtimer ? ?
1525
1526  -- Function: bot:deltimer ?
1527
1528  -- Function: bot:dcc-chat-send ? ?
1529
1530      [ And what about the stuff defined in `bobot-utils.scm' ? I just
1531      added it here so it could be somewhere.  There should also be a
1532      section dealing with modules.  How to use them.  What module
1533      scripts are in.  What module bobot++ provided primites are in.
1534      And so on. ]
1535
1536  -- Function: bot:log . messages
1537      Write as many MESSAGES as you want to the log.  If the arg is a
1538      thunk it will be executed and it's output will be written to the
1539      log.
1540
1541  -- Function: bot:load file
1542
1543  -- Function: bot:load-module module-spec
1544
1545  -- Function: bot:use-module module-spec
1546
1547  -- Function: bot:match-not-channel regex
1548      `bot:match-not-channel' adds a prefix regex to your REGEX so it
1549      doesn't match the sender or channel in a PUBLIC message
1550
1551  -- Function: bot:match-to-me regex
1552      `bot:match-to-me' matches text that was addressed to the bot with a
1553      ':',  ',',  or nothing after the bot name.
1554
1555  -- Function: bot:sent-to-me? message
1556
1557  -- Function: bot:ctcp-quote message
1558      Returns the CTCP quoted message Input _MUST NOT_ contain the
1559      trailing `\r\n' (it is added by the message sending code).
1560
1561  -- Variable: %bot:loadpath
1562
1563  -- Function: %bot:load-extensions
1564
1565 \1f
1566 File: bobot++.info,  Node: Concept Index,  Next: Function Index,  Prev: Scripting,  Up: Top
1567
1568 Concept Index
1569 *************
1570
1571