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    * `[--debug-scripts][-S]' Enabled the Guile debugging evaluator for
 306      verbose script errors and backtraces while still running the bot
 307      in the background.
 308
 309    The default configuration is read from
 310 `$HOME/.bobotpp/config/default/' and then `/etc/bobotpp/default/' if
 311 the user config is not found.
 312
 313    The bot defaults to running in the background as a daemon.
 314
 315 \1f
 316 File: bobot++.info,  Node: User Levels,  Next: Protection,  Prev: Starting the Bot,  Up: Using the Bot
 317
 318 3.2 User Levels
 319 ===============
 320
 321 There are several user levels available in Bobot++ to provide gradated
 322 access to commands. `!adduser' and `bot.users' use the numeric code;
 323 Scheme uses the textual name for the level. By default (if no catch-all
 324 setting is found in *Note bot.users::.) a user is not even a
 325 `bot:user-none' and cannot execute *any* commands, even commands
 326 available to `bot:user-none'.
 327
 328   0. `bot:user-none' - No *built-in* commands may be executed _by
 329      default_ (commands may be added from Scheme that can be executed
 330      by users of level none and the level required to execute a command
 331      may be changed from Scheme).
 332
 333   1. `bot:user-user' - Will be able to execute most commands but not
 334      all and cannot use masks on kicks and bans.
 335
 336   2. `bot:user-trusted' - For built-ins with a default configuration
 337      this user has access to the same set of commands as an `user' but
 338      may use masks on kicks and bans. Scheme commands may be added
 339      which require a user to be of this level.
 340
 341   3. `bot:user-friend' - In the default configuration a user who is a
 342      friend will be able to do everything short of stopping the bot.
 343      Again, there may be user added commands that require a higher user
 344      level.
 345
 346   4. `bot:user-master' - This is the highest user level and has access
 347      to every feature of the bot.
 348
 349
 350 \1f
 351 File: bobot++.info,  Node: Protection,  Next: Automatic Op,  Prev: User Levels,  Up: Using the Bot
 352
 353 3.3 Protection
 354 ==============
 355
 356 A user added via Scheme, the `bot.users' file, or `!adduser' may be
 357 protected from being deoped, kicked, or banned. There are currently no
 358 symbolic levels in Scheme; just use the numeric code.
 359
 360   0. No protection
 361
 362   1. No ban. If a user is banned the bot will unban him..
 363
 364   2. No kick. The user may still be kicked but the bot will kickban the
 365      user who kicked the protected user.
 366
 367   3. No deop. The bot will ensure that the user always maintains
 368      operator status.
 369
 370 \1f
 371 File: bobot++.info,  Node: Automatic Op,  Next: Built-In Commands,  Prev: Protection,  Up: Using the Bot
 372
 373 3.4 Automatic Op
 374 ================
 375
 376 A user may be automatically given operator status upon entering a
 377 channel. Set the AOP field to "0" to disable auto-op or "1" to enable
 378 auto-op.
 379
 380 \1f
 381 File: bobot++.info,  Node: Built-In Commands,  Prev: Automatic Op,  Up: Using the Bot
 382
 383 3.5 Built-In Commands
 384 =====================
 385
 386 Bobot++ has many built-in commands that make it useful without
 387 scripting support. The reference leaves off the command char; remember
 388 to use whatever you defined the command char to be in `bot.conf'. If a
 389 command needs the channel name then you must specify the channel as the
 390 first argument to the command when private messaging the bot a command.
 391
 392 COMMAND        NEEDS       MIN LEVEL   DESCRIPTION
 393                CHANNEL     TO USE
 394 `action' `do'  Yes         USER         Causes the bot to perform the
 395                                        action `do' in the current channel.
 396 `adduser'
 397 `addserver'                            Adds the server specified by HOST
 398                                        NAME or IP ADDRESS to the server
 399                                        list.
 400 `addshit'
 401 `alias'                                Makes an alias, and adds the
 402                                        function NEW NAME, that will do
 403                                        exactly the same command as OLD
 404                                        NAME.
 405 `ban'                                  Bans MASK or NICK from CHANNEL. You
 406                                        need to be a trusted user to ban
 407                                        with a MASK.
 408 `banlist'
 409 `channels'                             Prints the channel(s) where the bot
 410                                        is currently.
 411 `cycle'        Yes                     Makes the bot leave and join
 412                                        CHANNEL.
 413 `dcclist'                              Gives the list of all DCC Chat
 414                                        connections.
 415 `deban'        Yes                     Debans MASK or NICK from CHANNEL.
 416                                        You need to be a trusted user to
 417                                        deban with a MASK.
 418 `delserver'                            Deletes server from server list
 419                                        whose number in the server list is
 420                                        SERVER NUMBER.
 421 `deluser'                              Removes NICK or MASK from the
 422                                        userlist.
 423 `delshit'                              Removes NICK or MASK from the
 424                                        shitlist.
 425 `deop'         Yes                     Deops MASK or NICK on CHANNEL.
 426 `die'                                  Makes the bot stop immediately.
 427 `do'
 428 `execute'                              *Only available if scripting
 429                                        support is enabled*
 430 `help'
 431 `ident'                                Identifies you on the bot. Note
 432                                        that you should not use this
 433                                        command in public ...
 434 `invite'       Yes                     Invites NICK on CHANNEL.
 435 `join'                                 Makes the bot join CHANNEL.
 436 `keep'         Yes                     Sets the MODES that the bot will
 437                                        keep for CHANNEL.
 438 `kick'         Yes                     Kicks MASK or NICK out of CHANNEL,
 439                                        because of REASON. You need to be a
 440                                        trusted user to use a MASK.
 441 `kickban'      Yes                     Bans then kicks MASK or NICK out of
 442                                        CHANNEL, because of REASON. You need
 443                                        to be a trusted user to use a MASK.
 444 `load'                                 Reloads the userlist from disk.
 445 `loadscript'                           *Only available if scripting
 446                                        support is enabled*
 447 `lock'                                 Locks topic on CHANNEL.
 448 `mode'         Yes                     Sends MODE STRING as mode for
 449                                        CHANNEL.
 450 `msg'
 451 `names'        Yes                     Shows the nicknames and status of
 452                                        users on CHANNEL.
 453 `nextserver'                           Makes the bot connect to the next
 454                                        server in its server list.
 455 `nick'                                 Makes the bot use nickname NICK.
 456 `nslookup'                             Does a nameserver query about NICK
 457                                        host, HOST or IP ADDRESS.
 458 `op'           Yes                     Ops NICK on CHANNEL.
 459 `part'         Yes                     Makes the bot leave CHANNEL.
 460 `password'                             Changes your password on the bot.
 461                                        Use `NONE' as password if you want
 462                                        to clear it. Do not use this
 463                                        command in public!
 464 `reconnect'                            Makes the bot reconnect to its
 465                                        current server.
 466 `rspymessage'                          Removes you from the spy list.
 467 `save'                                 Saves the userlist.
 468 `say'          Yes                     Makes the bot say MESSAGE on
 469                                        CHANNEL.
 470 `server'                               Select the server to connect to.
 471                                        SERVER NUMBER is the number of the
 472                                        server in the serverlist.
 473 `serverlist'                           Shows the bot's serverlist.
 474 `setfloodrate'
 475 `setversion'
 476 `shitlist'                             Shows the bot's shitlist.
 477 `spylist'                              Shows the bot's spylist.
 478 `spymessage'                           Adds you to the spylist
 479 `stats'        Yes                     Gives CHANNEL's statistics.
 480 `tban'         Yes                     Bans NICK or MASK from CHANNEL for
 481                                        TIME seconds.
 482 `tkban'        Yes                     Bans NICK or MASK from CHANNEL for
 483                                        TIME seconds, then kicks him/them
 484                                        because of REASON.
 485 `topic'        Yes                     If no TOPICis given, prints
 486                                        CHANNEL's topic. Otherwise, the bot
 487                                        will change CHANNEL's topic to
 488                                        TOPIC.
 489 `unlock'       Yes                     Makes the bot unlock topic on
 490                                        CHANNEL
 491 `userlist'                             Shows the bot's userlist
 492 `who'          Yes                     Show your level on CHANNEL
 493 `whois'        Yes                     Shows information about NICK on
 494                                        CHANNEL
 495
 496 \1f
 497 File: bobot++.info,  Node: Scripting,  Next: Concept Index,  Prev: Using the Bot,  Up: Top
 498
 499 4 Scripting
 500 ***********
 501
 502 Bobot++'s most powerful feature is its scripting system. You write
 503 scripts using Guile Scheme. This manual does not cover how to use Guile
 504 or how to learn Scheme. *Note Guile Reference Manual: (guile)Top, for
 505 the Guile reference manual and
 506 `http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html' for a
 507 good tutorial on Scheme.
 508
 509    Note that in previous versions the scripting commands where in the
 510 form `bot-FUNCTION'. They are now in the form `bot:FUNCTION'. The old
 511 names are still available, but are deprecated and will be removed in
 512 Bobot++ 3.0. New commands are only available with the `bot:' prefix.
 513 The command `perl -pi -e ``s/bot-/bot:/g'' YOUR-FILES' should be enough
 514 to convert your code to use the new functions.
 515
 516 * Menu:
 517
 518 * Adding New Commands::
 519 * Hooks::
 520 * Scheme User Levels::
 521 * Sending Messages::
 522 * Misc Scripting Stuff::
 523
 524 \1f
 525 File: bobot++.info,  Node: Adding New Commands,  Next: Hooks,  Prev: Scripting,  Up: Scripting
 526
 527 4.1 Adding New Commands
 528 =======================
 529
 530 Adding a new command is simple. To register a new command use
 531 `bot:addcommand'.
 532
 533  -- Function: bot:addcommand name func needs-channel? num-of-args
 534           min-level
 535      The NAME is a string representing the name of the command being
 536      added.  FUNC is a function accepting NUM-OF-ARGS arguments.
 537      NEEDS-CHANNEL? is a bool that is true if the function needs the
 538      channel name as its first arg, and false otherwise.  NUM-OF-ARGS
 539      is the number of args FUNC will take and must be within zero (0)
 540      and twenty (20).  MIN-LEVEL is one of the *Note Scheme User
 541      Levels::.  A user must be at least a `min-level' user to use the
 542      new command.  None of the arguments are guaranteed to be passed;
 543      if they aren't they are set to the empty string `""'.  An example
 544      of a new command would be:
 545
 546           (define (hello channel name)
 547             (if (string=? name "")
 548               (bot:say channel "Hello world!")
 549               (bot:say channel (string-append "Hello " name "!")))
 550
 551           (bot:addcommand "hello" hello #t 2 0)
 552
 553      This will display "Hello World!" if called as `!hello' and "Hello
 554      World `USER'" if called as `!hello USER'.
 555
 556 \1f
 557 File: bobot++.info,  Node: Hooks,  Next: Scheme User Levels,  Prev: Adding New Commands,  Up: Scripting
 558
 559 4.2 Hooks
 560 =========
 561
 562 Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
 563 and tiny fugue (a MUD bot) hooks with a little bit of extra stuff added
 564 in. A hook is called when a regular expression is matched against a
 565 message sent to or by the bot.
 566
 567    Bobot++ uses different hook types for each IRC message type, and also
 568 includes a hook for accessing raw irc messages. Hooks are tagged with a
 569 priority and a flag that specifies whether to call the next hook that
 570 matches after calling the current one or to stop processing.
 571
 572    Hooks are processed from the highest to lowest priority, with
 573 fallthrough hooks of equal priority to non-fallthrough hooks being
 574 executed first.
 575
 576 * Menu:
 577
 578 * Creating a Hook::
 579 * Hook Types::
 580
 581 \1f
 582 File: bobot++.info,  Node: Creating a Hook,  Next: Hook Types,  Prev: Hooks,  Up: Hooks
 583
 584 4.2.1 Creating a Hook
 585 ---------------------
 586
 587 To add a new hook you use the function `bot:addhook'.
 588
 589  -- Function: bot:addhook type regex function [pri fall name]
 590      TYPE specifies the type of hook (the types of hooks are listed in
 591      *Note Hook Types::). REGEX is a standard regular expression. If
 592      REGEX is matched, FUNCTION will be called. FUNCTION will take a
 593      different number of args depending on the hook type. PRI specifies
 594      the priority of the hook--higher priority hooks are executed
 595      first. This argument is optional and defaults to `0'. FALL is `#t'
 596      if the hook is a fallthrough hook and `#f' is the hook is not a
 597      fallthrough hook. This arg is also optional and default to `#t'.
 598      NAME is the optional name of the hook that defaults to "DEFAULT".
 599      If you set the name then you can have more than one hook that
 600      matches the same regexp, as long as they have the same name. E.g.
 601      in a log script you could have the regexps for the log function
 602      all be `".*"' and set their names to `"log"' to avoid a conflict
 603      with other hooks.
 604
 605 \1f
 606 File: bobot++.info,  Node: Hook Types,  Prev: Creating a Hook,  Up: Hooks
 607
 608 4.2.2 Hook Types
 609 ----------------
 610
 611 Here is a list of the various hooks funtions and notes on each one. The
 612 general format of each hook description is as if it was was function to
 613 be defined, but these describe the function to be passwd to
 614 `bot:add-hook'.  Do _not_ name your functions these names.
 615
 616      [ Boy, that's clumsy.  I want to say that the hook/xx functions
 617      that are documented below are not funtions that you call.  They
 618      are the functions that needs to be passed to bot:addhook for that
 619      kind of hook.
 620
 621      Still clumsy.  Oh well. ]
 622
 623    That said, here is the list of available hooks functions.  FIXME:
 624 write docs
 625
 626  -- Function: hooks/action from to action
 627      This hook is triggered when someone performs an action.  FROM is
 628      the address of the person that performed the action in the form
 629      `NICK ! USER @ HOST' (without the spaces).  TO is the target of
 630      the action, which is either a channel or the Bot's nick.  ACTION
 631      is the text of the action. E.g. if someone did `* foobar does
 632      baz', then ACTION would be the string `"does baz"'.
 633
 634  -- Function: hooks/nickname old-nick new-nick
 635      This hook gets called when someone changes thir nickname from
 636      OLD-NICK to NEW-NICK.
 637
 638  -- Function: hooks/signoff nick rest
 639
 640  -- Function: hooks/ctcp nick to command rest
 641
 642  -- Function: hooks/ctcp-reply nick command rest
 643
 644  -- Function: hooks/disconnect server
 645      This is called when the bot is disconnected from a server
 646      unintentionally. `hooks/signoff' is called when the bot
 647      purposefully disconnected. The hook function is passed the
 648      hostname of the server it was disconnected from.
 649
 650  -- Function: hooks/flood nick
 651
 652  -- Function: hooks/invite nick channel
 653
 654  -- Function: hooks/join nick channel
 655
 656  -- Function: hooks/kick target from channel reason
 657
 658  -- Function: hooks/leave nick channel
 659  -- Function: hooks/part nick channel
 660
 661  -- Function: hooks/mode nick channel modes
 662
 663  -- Function: hooks/message from message
 664
 665  -- Function: hooks/notice nick message
 666
 667  -- Function: hooks/public from to message
 668
 669  -- Function: hooks/public-notice nick to message
 670
 671  -- Function: hooks/raw raw-message
 672
 673  -- Function: hooks/timer time
 674      This hook seems to be called once a minute.  TIME is in `hh:mm'
 675      format.
 676
 677  -- Function: hooks/topic nick channel new-topic
 678
 679  -- Function: hooks/send/public mynick dest message
 680
 681  -- Function: hooks/send/message botnick message
 682
 683  -- Function: hooks/send/action mynick to message
 684
 685  -- Function: hooks/send/ctcp mynick to command message
 686
 687  -- Function: hooks/dcc/chat-begin from
 688      This hook is triggered when a user begins a DCC CHAT with the bot.
 689      FROM is the user's address in the form `nick!user@host'.
 690
 691  -- Function: hooks/dcc/chat-message from message
 692      This hook is triggered when a user sends a message to the bot
 693      through a DCC CHAT FROM is the user's address in the form
 694      `nick!user@host'.  MESSAGE is the message the user sent to the bot.
 695
 696 \1f
 697 File: bobot++.info,  Node: Scheme User Levels,  Next: Sending Messages,  Prev: Hooks,  Up: Scripting
 698
 699 4.3 Scheme User Levels
 700 ======================
 701
 702 There are five levels that a user may be when interfacing with a bot:
 703 NONE, USER, TRUSTED_USER, FRIEND, MASTER. The Scheme variables for the
 704 user levels are `bot:user-none', `bot:user-user', `bot:user-trusted',
 705 `bot:user-friend', and `bot:user-master'. See *Note User Levels:: for
 706 more information on User Levels.
 707
 708    When adding a new command, think about who should be able to use it.
 709 Is your command a general purpose command that helps the channel (e.g.
 710 `!seen') that everyone should be able to use? Or is it something that
 711 should be restricted? See *Note User Levels:: for information on what
 712 level users can do what with the built in bot commands and think about
 713 what level a user your command is targetted towards. You must be _very_
 714 careful when giving new commands to lower level users because you can
 715 do basically everything the bot can do with a script. As the scripting
 716 interface becomes more powerful, you must think more about what users
 717 can use new commands you add.
 718
 719 \1f
 720 File: bobot++.info,  Node: Sending Messages,  Next: Misc Scripting Stuff,  Prev: Scheme User Levels,  Up: Scripting
 721
 722 4.4 Sending Messages
 723 ====================
 724
 725 There are several types of messages you can send with Bobot++ from
 726 scripts. There is the simple, but rather limited, `bot:say',
 727 `bot:action' and `bot:msg', and the more powerful, but lower level,
 728 `bot:send-MESSAGE' functions. Most bots will probably only need the
 729 higher level functions, but for the sake of why-not Bobot++ lets you
 730 use the lower level functions (in progress).
 731
 732 * Menu:
 733
 734 * High Level Message Functions::
 735 * Low Level Message Functions::
 736
 737 \1f
 738 File: bobot++.info,  Node: High Level Message Functions,  Next: Low Level Message Functions,  Prev: Sending Messages,  Up: Sending Messages
 739
 740 4.4.1 "High Level" Message Functions
 741 ------------------------------------
 742
 743  -- Function: bot:say channel message
 744      Send a public or private MESSAGE to CHANNEL.
 745
 746      Sends a normal text message, as if a user had typed it in.  The
 747      DEST can be a nickname or a channel.
 748
 749  -- Function: bot:action channel message
 750      Send an "action" type  MESSAGE to CHANNEL
 751
 752  -- Function: bot:msg nick message
 753      The same as if a user typed `/msg nick message' to their IRC
 754      client.
 755
 756  -- Function: bot:notice target message
 757      Sends MESSAGE as a NOTICE to TARGET. TARGET may be a user (nick)
 758      or a channel. This returns 0 on success.
 759
 760 \1f
 761 File: bobot++.info,  Node: Low Level Message Functions,  Prev: High Level Message Functions,  Up: Sending Messages
 762
 763 4.4.2 "Low Level" Message Functions
 764 -----------------------------------
 765
 766 The "Low Level" messaging functions allow you to do things like send
 767 CTCP messages. You probably want to read rfc 2812 and the CTCP spec
 768 before using these. If you have no idea what these do, read rfc 2812
 769 (IRC Client Protocol) and CTCP spec. These functions all return
 770 `*unspecified*' always, so don't use the return value for anything.
 771
 772  -- Function: bot:send-ctcp to command message
 773      `to' is the target of your CTCP message, `command' is the CTCP
 774      command, and `message' is the message (or arguments) of the
 775      command. Make sure to `bot:ctcp-quote' the message!
 776
 777  -- Function: bot:send-ctcp-reply to command message
 778      `to' is the target of your CTCP reply, `command' is the CTCP
 779      command, and `message' is the message (or arguments) of the
 780      command. Make sure to `bot:ctcp-quote' the message!
 781
 782      This is used to reply to a ctcp that the bot has received.
 783
 784 \1f
 785 File: bobot++.info,  Node: Misc Scripting Stuff,  Prev: Sending Messages,  Up: Scripting
 786
 787 4.5 Misc. Scripting Stuff
 788 =========================
 789
 790 These are a few useful things that I thought people writing scripts
 791 might want to know.
 792
 793    If you want to execute code when the bot exits, just do `add-hook!
 794 bot:exit-hook THUNK' where THUNK is an argumentless procedure (a
 795 thunk). When the bot exits your thunk will be called.
 796
 797      [ I didn't know where to put any of these, so I jsut stuck them in
 798      here.
 799
 800      There probably needs to be several sections added, like dealing
 801      with users (kicking, added, etc), dealing with the bot (channels,
 802      nickname of the bot, etc), server issues (serverlist), useful
 803      tools (nslookup, whois), and do on. ]
 804
 805  -- Function: bot:adduser nick-or-mask cbannel-mask level prot auto-op
 806      Adds an user to the userlist, for a `nick!user@host' matching the
 807      one given, on a channel matching the CHANNELMASK given.
 808
 809      The LEVEL can be:      The PROT can be:       The AUTO-OP can be:
 810      0 - No level           0 - No protection      0 - No auto-op
 811      1 - User               1 - No ban             1 - Op on join
 812      2 - Trusted User       2 - No kick
 813      3 - Friend             3 - No deop
 814      4 - Master
 815
 816
 817  -- Function: bot:addserver hostname ip-address [portnumber]
 818      Adds the server specified by HOSTNAME or IP-ADDRESS to the server
 819      list.
 820
 821  -- Function: bot:addshit nick-or-mask channel-mask level [time reason]
 822      Adds an user to the shitlist, for a nick!user@host matching the
 823      one given, on a channel matching the CHANNELMASK given.
 824
 825           The LEVEL can be:
 826             0 - No shit
 827             1 - No op
 828             2 - Kick and Ban on join
 829             3 - Kick and Ban on join, no deban
 830
 831
 832  -- Function: bot:ban channel mask-or-nick
 833      Bans MASK or NICK from CHANNEL. You need to be a trusted user to
 834      ban with a MASK.
 835
 836  -- Function: bot:change-command-level nick-or-mask channel-mask
 837           new-level
 838      Gives NICK or MASK level NEW-LEVEL on channel(s) CHANNEL-MASK.
 839      Note that you can not change level for someone whose level is
 840      greater than yours, and that you can not give a level greater than
 841      yours.
 842
 843  -- Function: bot:cycle channel
 844      Makes the bot leave and join CHANNEL.
 845
 846  -- Function: bot:deban channel mask-or-nick
 847      Debans MASK or NICK from CHANNEL. You need to be a trusted user to
 848      deban with a MASK.
 849
 850  -- Function: bot:delserver server-number
 851      Deletes server from server list whose number in the server list is
 852      SERVER-NUMBER
 853
 854  -- Function: bot:deluser nick-or-mask channel-mask
 855      Removes NICK or MASK from the userlist.
 856
 857  -- Function: bot:delshit nick-or-mask channel-mask
 858      Removes NICK or MASK from the shitlist.
 859
 860  -- Function: bot:deop channel mask-or-nick
 861      Deops MASK or NICK on CHANNEL.
 862
 863  -- Function: bot:die reason
 864      Makes the bot stop immediately.
 865
 866  -- Function: bot:do ?
 867
 868  -- Function: bot:invite channel nick
 869      Invites NICK on CHANNEL.
 870
 871  -- Function: bot:join channel
 872      Makes the bot join CHANNEL.
 873
 874  -- Function: bot:keep channel modes
 875      Sets the MODES that the bot will keep for CHANNEL.  See also STATS.
 876
 877  -- Function: bot:kick channel mask-or-nick [reason]
 878      Kicks MASK or NICK out of CHANNEL, because of REASON.  You need to
 879      be a trusted user to use a MASK.
 880
 881  -- Function: bot:kickban channel mask-or-nick [reason]
 882      Bans then kicks MASK or NICK out of CHANNEL, because of REASON.
 883      You need to be a trusted user to use a MASK.
 884
 885  -- Function: bot:lock channel
 886      Locks topic on CHANNEL.
 887
 888  -- Function: bot:logport
 889      [ Probably returns the log port? ]
 890
 891  -- Function: bot:mode channel mode-string
 892      Sends MODE-STRING as mode for CHANNEL.
 893
 894  -- Function: bot:nextserver
 895      Makes the bot connect to the next server in its server list.
 896
 897  -- Function: bot:nick nick
 898      Makes the bot use nickname NICK.
 899
 900  -- Function: bot:op channel nick
 901      Ops NICK on CHANNEL.
 902
 903  -- Function: bot:part channel
 904      Makes the bot leave CHANNEL.
 905
 906  -- Function: bot:reconnect
 907      Makes the bot reconnect to its current server.
 908
 909  -- Function: bot:server server-number
 910      Select the server to connect to. SERVER-NUMBER is the number of
 911      the server in the serverlist.
 912
 913  -- Function: bot:setfloodrate ?
 914
 915  -- Function: bot:setversion ?
 916
 917  -- Function: bot:tban channel nick-or-mask time
 918      Bans NICK or MASK from CHANNEL for TIME seconds.
 919
 920  -- Function: bot:tkban channel nick-or-mask time [reason]
 921      Bans NICK or MASK from CHANNEL for TIME seconds, then kicks
 922      him/them because of REASON.
 923
 924  -- Function: bot:topic channel topic
 925      If no TOPIC is given, prints CHANNEL's topic. Otherwise, the bot
 926      will change CHANNEL's topic to TOPIC.
 927
 928  -- Function: bot:unlock channel
 929      Makes the bot unlock topic on CHANNEL.
 930
 931  -- Function: bot:getnickname
 932      [ Gets the bot's nickname? ]
 933
 934  -- Function: bot:getserver
 935
 936  -- Function: bot:getserverlist
 937
 938  -- Function: bot:flush
 939      [ Flushes the socket to the server? ]
 940
 941  -- Function: bot:flushport
 942      [ Flushes the log port? ]
 943
 944  -- Function: bot:random ?
 945      [ Returns a random number?  What range?  Why? ]
 946
 947  -- Function: bot:delcommand
 948      [ Probably deletes a command added with `bot:addcommand' ? ]
 949
 950  -- Function: bot:addtimer ? ?
 951
 952  -- Function: bot:deltimer ?
 953
 954  -- Function: bot:dcc-chat-send ? ?
 955
 956      [ And what about the stuff defined in `bobot-utils.scm' ? I just
 957      added it here so it could be somewhere.  There should also be a
 958      section dealing with modules.  How to use them.  What module
 959      scripts are in.  What module bobot++ provided primites are in.
 960      And so on. ]
 961
 962  -- Function: bot:log . messages
 963      Write as many MESSAGES as you want to the log.  If the arg is a
 964      thunk it will be executed and it's output will be written to the
 965      log.
 966
 967  -- Function: bot:load file
 968
 969  -- Function: bot:load-module module-spec
 970
 971  -- Function: bot:use-module module-spec
 972
 973  -- Function: bot:match-not-channel regex
 974      match-not-channel adds a prefix regex to your REGEX so it doesn't
 975      match the sender or channel in a PUBLIC message
 976
 977  -- Function: bot:match-to-me regex
 978      match-to-me matches text that was addressed to the bot with a ':',
 979      ',',  or nothing after the bot name.
 980
 981  -- Function: bot:sent-to-me? message
 982
 983  -- Function: bot:ctcp-quote message
 984      Returns the CTCP quoted message Input _MUST NOT_ contain the
 985      trailing `\r\n' (it is added by the message sending code).
 986
 987  -- Variable: %bot:loadpath
 988
 989  -- Function: %bot:load-extensions
 990
 991 \1f
 992 File: bobot++.info,  Node: Concept Index,  Next: Function Index,  Prev: Scripting,  Up: Top
 993
 994 Concept Index
 995 *************
 996
 997