bobot++.info

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