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. The basic idea of a hook if that you match a text against regular
 561 expression and call a function if text in a message matches that regex.
 562 The different types of hooks provided by Bobot++ correspond to the
 563 different classes of messages that Bobot++ can recieve. A Hook also has
 564 several properties, including its priority and whether or not it is a
 565 fallthrough hook. Higher priority hooks are executed before lower
 566 priority hooks and fallthrough hooks are executed before
 567 non-fallthrough hooks of the same priority. A fallthrough hook can
 568 match and processing of hooks will continue; as soon as the first
 569 non-fallthrough hooks matches processing of hooks stops.
 570
 571 * Menu:
 572
 573 * Creating a Hook::
 574 * Hook Types::
 575
 576 \1f
 577 File: bobot++.info,  Node: Creating a Hook,  Next: Hook Types,  Prev: Hooks,  Up: Hooks
 578
 579 4.2.1 Creating a Hook
 580 ---------------------
 581
 582 To add a new hook you use the function `bot:addhook'.
 583
 584  -- Function: bot:addhook type regex function [pri fall name]
 585      TYPE specifies the type of hook (the types of hooks are listed in
 586      *Note Hook Types::). REGEX is a standard regular expression. If
 587      REGEX is matched, FUNCTION will be called. FUNCTION will take a
 588      different number of args depending on the hook type. PRI specifies
 589      the priority of the hook--higher priority hooks are executed
 590      first. This argument is optional and defaults to `0'. FALL is `#t'
 591      if the hook is a fallthrough hook and `#f' is the hook is not a
 592      fallthrough hook. This arg is also optional and default to `#t'.
 593      NAME is the optional name of the hook that defaults to "DEFAULT".
 594      If you set the name then you can have more than one hook that
 595      matches the same regexp, as long as they have the same name. E.g.
 596      in a log script you could have the regexps for the log function
 597      all be `".*"' and set their names to `"log"' to avoid a conflict
 598      with other hooks.
 599
 600 \1f
 601 File: bobot++.info,  Node: Hook Types,  Prev: Creating a Hook,  Up: Hooks
 602
 603 4.2.2 Hook Types
 604 ----------------
 605
 606 Here is a list of the various hooks funtions and notes on each one. The
 607 general format of each hook description is as if it was was function to
 608 be defined, but these describe the function to be passwd to
 609 `bot:add-hook'.  Do _not_ name your functions these names.
 610
 611      [ Boy, that's clumsy.  I want to say that the hook/xx functions
 612      that are documented below are not funtions that you call.  They
 613      are the functions that needs to be passed to bot:addhook for that
 614      kind of hook.
 615
 616      Still clumsy.  Oh well. ]
 617
 618    That said, here is the list of available hooks functions.  FIXME:
 619 write docs
 620
 621  -- Function: hooks/action from to action
 622      This hook is triggered when someone performs an action.  FROM is
 623      the address of the person that performed the action in the form
 624      `NICK ! USER @ HOST' (without the spaces).  TO is the target of
 625      the action, which is either a channel or the Bot's nick.  ACTION
 626      is the text of the action. E.g. if someone did `* foobar does
 627      baz', then ACTION would be the string `"does baz"'.
 628
 629  -- Function: hooks/nickname old-nick new-nick
 630      This hook gets called when someone changes thir nickname from
 631      OLD-NICK to NEW-NICK.
 632
 633  -- Function: hooks/signoff nick rest
 634
 635  -- Function: hooks/ctcp nick to command rest
 636
 637  -- Function: hooks/ctcp-reply nick command rest
 638
 639  -- Function: hooks/disconnect ?
 640      [ Is this ever called?  I can't find it in the source ]
 641
 642  -- Function: hooks/flood nick
 643
 644  -- Function: hooks/invite nick channel
 645
 646  -- Function: hooks/join nick channel
 647
 648  -- Function: hooks/kick target from channel reason
 649
 650  -- Function: hooks/leave nick channel
 651  -- Function: hooks/part nick channel
 652
 653  -- Function: hooks/mode nick channel modes
 654
 655  -- Function: hooks/message from message
 656
 657  -- Function: hooks/notice nick message
 658
 659  -- Function: hooks/public from to message
 660
 661  -- Function: hooks/public-notice nick to message
 662
 663  -- Function: hooks/raw raw-message
 664
 665  -- Function: hooks/timer time
 666      This hook seems to be called once a minute.  TIME is in `hh:mm'
 667      format.
 668
 669  -- Function: hooks/topic nick channel new-topic
 670
 671  -- Function: hooks/send/public mynick dest message
 672
 673  -- Function: hooks/send/message botnick message
 674
 675  -- Function: hooks/send/action mynick to message
 676
 677  -- Function: hooks/send/ctcp mynick to command message
 678
 679  -- Function: hooks/dcc/chat-begin from
 680      This hook is triggered when a user begins a DCC CHAT with the bot.
 681      FROM is the user's address in the form `nick!user@host'.
 682
 683  -- Function: hooks/dcc/chat-message from message
 684      This hook is triggered when a user sends a message to the bot
 685      through a DCC CHAT FROM is the user's address in the form
 686      `nick!user@host'.  MESSAGE is the message the user sent to the bot.
 687
 688 \1f
 689 File: bobot++.info,  Node: Scheme User Levels,  Next: Sending Messages,  Prev: Hooks,  Up: Scripting
 690
 691 4.3 Scheme User Levels
 692 ======================
 693
 694 There are five levels that a user may be when interfacing with a bot:
 695 NONE, USER, TRUSTED_USER, FRIEND, MASTER. The Scheme variables for the
 696 user levels are `bot:user-none', `bot:user-user', `bot:user-trusted',
 697 `bot:user-friend', and `bot:user-master'. See *Note User Levels:: for
 698 more information on User Levels.
 699
 700    When adding a new command, think about who should be able to use it.
 701 Is your command a general purpose command that helps the channel (e.g.
 702 `!seen') that everyone should be able to use? Or is it something that
 703 should be restricted? See *Note User Levels:: for information on what
 704 level users can do what with the built in bot commands and think about
 705 what level a user your command is targetted towards. You must be _very_
 706 careful when giving new commands to lower level users because you can
 707 do basically everything the bot can do with a script. As the scripting
 708 interface becomes more powerful, you must think more about what users
 709 can use new commands you add.
 710
 711 \1f
 712 File: bobot++.info,  Node: Sending Messages,  Next: Misc Scripting Stuff,  Prev: Scheme User Levels,  Up: Scripting
 713
 714 4.4 Sending Messages
 715 ====================
 716
 717 There are several types of messages you can send with Bobot++ from
 718 scripts. There is the simple, but rather limited, `bot:say',
 719 `bot:action' and `bot:msg', and the more powerful, but lower level,
 720 `bot:send-MESSAGE' functions. Most bots will probably only need the
 721 higher level functions, but for the sake of why-not Bobot++ lets you
 722 use the lower level functions (in progress).
 723
 724 * Menu:
 725
 726 * High Level Message Functions::
 727 * Low Level Message Functions::
 728
 729 \1f
 730 File: bobot++.info,  Node: High Level Message Functions,  Next: Low Level Message Functions,  Prev: Sending Messages,  Up: Sending Messages
 731
 732 4.4.1 "High Level" Message Functions
 733 ------------------------------------
 734
 735  -- Function: bot:say channel message
 736      Send a public or private MESSAGE to CHANNEL.
 737
 738      Sends a normal text message, as if a user had typed it in.  The
 739      DEST can be a nickname or a channel.
 740
 741  -- Function: bot:action channel message
 742      Send an "action" type  MESSAGE to CHANNEL
 743
 744  -- Function: bot:msg nick message
 745      The same as if a user typed `/msg nick message' to their IRC
 746      client.
 747
 748 \1f
 749 File: bobot++.info,  Node: Low Level Message Functions,  Prev: High Level Message Functions,  Up: Sending Messages
 750
 751 4.4.2 "Low Level" Message Functions
 752 -----------------------------------
 753
 754 The "Low Level" messaging functions allow you to do things like send
 755 CTCP messages. You probably want to read rfc 2812 and the CTCP spec
 756 before using these. If you have no idea what these do, read rfc 2812
 757 (IRC Client Protocol) and CTCP spec. These functions all return
 758 `*unspecified*' always, so don't use the return value for anything.
 759
 760  -- Function: bot:send-CTCP to command message
 761      `to' is the target of your CTCP message, `command' is the CTCP
 762      command, and `message' is the message (or arguments) of the
 763      command. Make sure to `bot:ctcp-quote' the message!
 764
 765 \1f
 766 File: bobot++.info,  Node: Misc Scripting Stuff,  Prev: Sending Messages,  Up: Scripting
 767
 768 4.5 Misc. Scripting Stuff
 769 =========================
 770
 771 These are a few useful things that I thought people writing scripts
 772 might want to know.
 773
 774    If you want to execute code when the bot exits, just do `add-hook!
 775 bot:exit-hook THUNK' where THUNK is an argumentless procedure (a
 776 thunk). When the bot exits your thunk will be called.
 777
 778      [ I didn't know where to put any of these, so I jsut stuck them in
 779      here.
 780
 781      There probably needs to be several sections added, like dealing
 782      with users (kicking, added, etc), dealing with the bot (channels,
 783      nickname of the bot, etc), server issues (serverlist), useful
 784      tools (nslookup, whois), and do on. ]
 785
 786  -- Function: bot:adduser nick-or-mask cbannel-mask level prot auto-op
 787      Adds an user to the userlist, for a `nick!user@host' matching the
 788      one given, on a channel matching the CHANNELMASK given.
 789
 790      The LEVEL can be:      The PROT can be:       The AUTO-OP can be:
 791      0 - No level           0 - No protection      0 - No auto-op
 792      1 - User               1 - No ban             1 - Op on join
 793      2 - Trusted User       2 - No kick
 794      3 - Friend             3 - No deop
 795      4 - Master
 796
 797
 798  -- Function: bot:addserver hostname ip-address [portnumber]
 799      Adds the server specified by HOSTNAME or IP-ADDRESS to the server
 800      list.
 801
 802  -- Function: bot:addshit nick-or-mask channel-mask level [time reason]
 803      Adds an user to the shitlist, for a nick!user@host matching the
 804      one given, on a channel matching the CHANNELMASK given.
 805
 806           The LEVEL can be:
 807             0 - No shit
 808             1 - No op
 809             2 - Kick and Ban on join
 810             3 - Kick and Ban on join, no deban
 811
 812
 813  -- Function: bot:ban channel mask-or-nick
 814      Bans MASK or NICK from CHANNEL. You need to be a trusted user to
 815      ban with a MASK.
 816
 817  -- Function: bot:change-command-level nick-or-mask channel-mask
 818           new-level
 819      Gives NICK or MASK level NEW-LEVEL on channel(s) CHANNEL-MASK.
 820      Note that you can not change level for someone whose level is
 821      greater than yours, and that you can not give a level greater than
 822      yours.
 823
 824  -- Function: bot:cycle channel
 825      Makes the bot leave and join CHANNEL.
 826
 827  -- Function: bot:deban channel mask-or-nick
 828      Debans MASK or NICK from CHANNEL. You need to be a trusted user to
 829      deban with a MASK.
 830
 831  -- Function: bot:delserver server-number
 832      Deletes server from server list whose number in the server list is
 833      SERVER-NUMBER
 834
 835  -- Function: bot:deluser nick-or-mask channel-mask
 836      Removes NICK or MASK from the userlist.
 837
 838  -- Function: bot:delshit nick-or-mask channel-mask
 839      Removes NICK or MASK from the shitlist.
 840
 841  -- Function: bot:deop channel mask-or-nick
 842      Deops MASK or NICK on CHANNEL.
 843
 844  -- Function: bot:die reason
 845      Makes the bot stop immediately.
 846
 847  -- Function: bot:do ?
 848
 849  -- Function: bot:invite channel nick
 850      Invites NICK on CHANNEL.
 851
 852  -- Function: bot:join channel
 853      Makes the bot join CHANNEL.
 854
 855  -- Function: bot:keep channel modes
 856      Sets the MODES that the bot will keep for CHANNEL.  See also STATS.
 857
 858  -- Function: bot:kick channel mask-or-nick [reason]
 859      Kicks MASK or NICK out of CHANNEL, because of REASON.  You need to
 860      be a trusted user to use a MASK.
 861
 862  -- Function: bot:kickban channel mask-or-nick [reason]
 863      Bans then kicks MASK or NICK out of CHANNEL, because of REASON.
 864      You need to be a trusted user to use a MASK.
 865
 866  -- Function: bot:lock channel
 867      Locks topic on CHANNEL.
 868
 869  -- Function: bot:logport
 870      [ Probably returns the log port? ]
 871
 872  -- Function: bot:mode channel mode-string
 873      Sends MODE-STRING as mode for CHANNEL.
 874
 875  -- Function: bot:nextserver
 876      Makes the bot connect to the next server in its server list.
 877
 878  -- Function: bot:nick nick
 879      Makes the bot use nickname NICK.
 880
 881  -- Function: bot:op channel nick
 882      Ops NICK on CHANNEL.
 883
 884  -- Function: bot:part channel
 885      Makes the bot leave CHANNEL.
 886
 887  -- Function: bot:reconnect
 888      Makes the bot reconnect to its current server.
 889
 890  -- Function: bot:server server-number
 891      Select the server to connect to. SERVER-NUMBER is the number of
 892      the server in the serverlist.
 893
 894  -- Function: bot:setfloodrate ?
 895
 896  -- Function: bot:setversion ?
 897
 898  -- Function: bot:tban channel nick-or-mask time
 899      Bans NICK or MASK from CHANNEL for TIME seconds.
 900
 901  -- Function: bot:tkban channel nick-or-mask time [reason]
 902      Bans NICK or MASK from CHANNEL for TIME seconds, then kicks
 903      him/them because of REASON.
 904
 905  -- Function: bot:topic channel topic
 906      If no TOPIC is given, prints CHANNEL's topic. Otherwise, the bot
 907      will change CHANNEL's topic to TOPIC.
 908
 909  -- Function: bot:unlock channel
 910      Makes the bot unlock topic on CHANNEL.
 911
 912  -- Function: bot:getnickname
 913      [ Gets the bot's nickname? ]
 914
 915  -- Function: bot:getserver
 916
 917  -- Function: bot:getserverlist
 918
 919  -- Function: bot:flush
 920      [ Flushes the socket to the server? ]
 921
 922  -- Function: bot:flushport
 923      [ Flushes the log port? ]
 924
 925  -- Function: bot:random ?
 926      [ Returns a random number?  What range?  Why? ]
 927
 928  -- Function: bot:delcommand
 929      [ Probably deletes a command added with `bot:addcommand' ? ]
 930
 931  -- Function: bot:addtimer ? ?
 932
 933  -- Function: bot:deltimer ?
 934
 935  -- Function: bot:dcc-chat-send ? ?
 936
 937      [ And what about the stuff defined in `bobot-utils.scm' ? I just
 938      added it here so it could be somewhere.  There should also be a
 939      section dealing with modules.  How to use them.  What module
 940      scripts are in.  What module bobot++ provided primites are in.
 941      And so on. ]
 942
 943  -- Function: bot:log . messages
 944      Write as many MESSAGES as you want to the log.  If the arg is a
 945      thunk it will be executed and it's output will be written to the
 946      log.
 947
 948  -- Function: bot:load file
 949
 950  -- Function: bot:load-module module-spec
 951
 952  -- Function: bot:use-module module-spec
 953
 954  -- Function: bot:match-not-channel regex
 955      match-not-channel adds a prefix regex to your REGEX so it doesn't
 956      match the sender or channel in a PUBLIC message
 957
 958  -- Function: bot:match-to-me regex
 959      match-to-me matches text that was addressed to the bot with a ':',
 960      ',',  or nothing after the bot name.
 961
 962  -- Function: bot:sent-to-me? message
 963
 964  -- Function: bot:ctcp-quote message
 965      Returns the CTCP quoted message Input _MUST NOT_ contain the
 966      trailing `\r\n' (it is added by the message sending code).
 967
 968  -- Variable: %bot:loadpath
 969
 970  -- Function: %bot:load-extensions
 971
 972 \1f
 973 File: bobot++.info,  Node: Concept Index,  Next: Function Index,  Prev: Scripting,  Up: Top
 974
 975 Concept Index
 976 *************
 977
 978