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