HCoop / clinton / bobotpp.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
[project @ 2005-06-28 03:16:45 by unknown_lamer]
[clinton/bobotpp.git] / bobot++.info
CommitLineData
6b59e728 1This is bobot++.info, produced by makeinfo version 4.7 from
2e20c3e1 2bobot++.texinfo.
3
4 This file documents Bobot++ by Clinton Ebadi and Etienne Bernard
5(original author, no longer works on program).
6
2e18045a 7 Copyright 2002,2004,2005 Clinton Ebadi
2e20c3e1 8
9 Permission is granted to copy, distribute and/or modify this document
10under the terms of the GNU Free Documentation License, Version 1.1 or
11any later version published by the Free Software Foundation; with no
12Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
13Texts.
14
15\1f
16File: 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
c7d9fb19 21 This document applies to version 2.1.5 of the program named Bobot++
2e20c3e1 22
c7d9fb19 23 Copyright 2002,2004 Clinton Ebadi
439869bf 24
25 Permission is granted to copy, distribute and/or modify this document
26under the terms of the GNU Free Documentation License, Version 1.1 or
27any later version published by the Free Software Foundation; with no
28Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
29Texts.
30
2e20c3e1 31* Menu:
32
33* Introduction::
ad529fde 34* Configuration::
e07b6b46 35* Using the Bot::
ad529fde 36* Scripting::
37* Concept Index::
38* Function Index::
39* Variable Index::
2e20c3e1 40
c7d9fb19 41 --- The Detailed Node Listing ---
42
43Configuration
44
45* Configuration Files::
46* Configuration File Placement::
47
48Configuration Files
49
50* bot.conf::
c8f13c06 51* bot.users::
c7d9fb19 52
53bot.conf
54
55* server syntax::
56* channel syntax::
57
58Using Bobot++
59
6b59e728 60* Starting the Bot::
c7d9fb19 61* User Levels::
c8f13c06 62* Protection::
63* Automatic Op::
6b59e728 64* Built-In Commands::
c7d9fb19 65
66Scripting
67
68* Adding New Commands::
69* Hooks::
70* Scheme User Levels::
71* Sending Messages::
72* Misc Scripting Stuff::
73
74Hooks
75
76* Creating a Hook::
77* Hook Types::
78
79Sending Messages
80
81* High Level Message Functions::
82* Low Level Message Functions::
83
2e20c3e1 84\1f
ad529fde 85File: bobot++.info, Node: Introduction, Next: Configuration, Prev: Top, Up: Top
2e20c3e1 86
6b59e728 871 Introduction
88**************
2e20c3e1 89
5a8b0ec6 90This manual feels abused and neglected because it has almost no content.
2e20c3e1 91
ad529fde 92\1f
e07b6b46 93File: bobot++.info, Node: Configuration, Next: Using the Bot, Prev: Introduction, Up: Top
ad529fde 94
6b59e728 952 Configuration
96***************
ad529fde 97
c8f13c06 98Bobot++ is easy to configure. See the `examples' directory for an
99example configuration.
ad529fde 100
101* Menu:
102
c7d9fb19 103* Configuration Files::
104* Configuration File Placement::
ad529fde 105
106\1f
c7d9fb19 107File: bobot++.info, Node: Configuration Files, Next: Configuration File Placement, Prev: Configuration, Up: Configuration
ad529fde 108
6b59e728 1092.1 Configuration Files
110=======================
ad529fde 111
e171dcce 112* Menu:
113
114* bot.conf::
c8f13c06 115* bot.users::
e171dcce 116
117\1f
c8f13c06 118File: bobot++.info, Node: bot.conf, Next: bot.users, Prev: Configuration Files, Up: Configuration Files
e171dcce 119
6b59e728 1202.1.1 bot.conf
121--------------
e171dcce 122
c8f13c06 123* Menu:
124
125* server syntax::
126* channel syntax::
127
128 `bot.conf' contains key value pairs separated by `='.
c7d9fb19 129
130 `<key> = <value>'
131
132 Comments are started with a `#' and cause the entire line to be
133ignored. _Note that this only works when the `#' is the first character
134of the line_.
135
136 bot.conf is the main configuration file for a Bobot++. The available
e171dcce 137configuration 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
c7d9fb19 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
c7d9fb19 165\1f
166File: bobot++.info, Node: server syntax, Next: channel syntax, Prev: bot.conf, Up: bot.conf
167
6b59e728 1682.1.1.1 server syntax
169.....................
c7d9fb19 170
171SERVER = SERVER_NAME [PORT [PASSWORD]]
172
173 This will make Bobot++ attempt to connect to SERVER_NAME on port
174PORT with the password PASSWORD. SERVER_NAME should be the address of
175the server. PORT and PASSWORD are optional. You may use more than one
176server line; Bobot++ will attempt to connect to the first one and, if
177it fails, will connect to the next one in the list. There is also a
178command to cause the bot to cycle servers. At the present time Bobot++
179cannot connect to more than one server at a time. This is a planned
180feature of 3.0 (which is a very long way away; the current structure of
181the program would make it very difficult to add support for connecting
182to multiple servers at a time in a usable manner).
183
184\1f
185File: bobot++.info, Node: channel syntax, Prev: server syntax, Up: bot.conf
186
6b59e728 1872.1.1.2 channel syntax
188......................
c7d9fb19 189
190CHANNEL = NAME:INITIAL_MODES:MODES_TO_KEEP:CHANNEL_KEY
191
192 You may have any number of channel lines. When Bobot++ starts it will
193attempt to join and gain ops in every channel listed. It will join NAME
194and set the channel modes to INITIAL_MODES (e.g. "nt") if it is able to
195gain operator status. It will then maintain MODES_TO_KEEP. If the
196channel requires a key to enter simply set CHANNEL_KEY. Every argument
197except 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
204maintain the modes `nt'.
205
206 `CHANNEL = #bar:::'
e171dcce 207
c7d9fb19 208 The bot will join `#bar' and will not set any modes nor will it
209attempt to maintain any modes.
ad529fde 210
c8f13c06 211\1f
212File: bobot++.info, Node: bot.users, Prev: bot.conf, Up: Configuration Files
213
6b59e728 2142.1.2 bot.users
215---------------
c8f13c06 216
217`bot.users' is the default file name of the userlist. It may be changed
218in `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
ad529fde 239\1f
c7d9fb19 240File: bobot++.info, Node: Configuration File Placement, Prev: Configuration Files, Up: Configuration
ad529fde 241
6b59e728 2422.2 Configuration File Placement
243================================
ad529fde 244
9efc3706 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
251if none is specified on the command line. Put the configuration files
252you want to be loaded by default in this directory. If you are not root
253or you want to have your own personal configuration, put it in
ad529fde 254`~/.bobotpp/config/default/'.
255
256\1f
e07b6b46 257File: bobot++.info, Node: Using the Bot, Next: Scripting, Prev: Configuration, Up: Top
258
6b59e728 2593 Using Bobot++
260***************
e07b6b46 261
5a8b0ec6 262FIXME: stuff here...
e07b6b46 263
264* Menu:
265
6b59e728 266* Starting the Bot::
e07b6b46 267* User Levels::
c8f13c06 268* Protection::
269* Automatic Op::
6b59e728 270* Built-In Commands::
e07b6b46 271
272\1f
6b59e728 273File: bobot++.info, Node: Starting the Bot, Next: User Levels, Prev: Using the Bot, Up: Using the Bot
274
2753.1 Starting the Bot
276====================
277
278The bot is usually installed with the binary name `bobotpp'. It accepts
279the 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
e07b6b46 304
6b59e728 305 The default configuration is read from
306`$HOME/.bobotpp/config/default/' and then `/etc/bobotpp/default/' if
307the user config is not found.
308
309 The bot defaults to running in the background as a daemon.
310
311\1f
312File: bobot++.info, Node: User Levels, Next: Protection, Prev: Starting the Bot, Up: Using the Bot
313
3143.2 User Levels
315===============
e07b6b46 316
c8f13c06 317There are several user levels available in Bobot++ to provide gradated
318access to commands. `!adduser' and `bot.users' use the numeric code;
319Scheme uses the textual name for the level. By default (if no catch-all
320setting is found in *Note bot.users::.) a user is not even a
321`bot:user-none' and cannot execute *any* commands, even commands
322available 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
347File: bobot++.info, Node: Protection, Next: Automatic Op, Prev: User Levels, Up: Using the Bot
348
6b59e728 3493.3 Protection
350==============
c8f13c06 351
352A user added via Scheme, the `bot.users' file, or `!adduser' may be
353protected from being deoped, kicked, or banned. There are currently no
354symbolic 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
c8f13c06 366\1f
6b59e728 367File: bobot++.info, Node: Automatic Op, Next: Built-In Commands, Prev: Protection, Up: Using the Bot
c8f13c06 368
6b59e728 3693.4 Automatic Op
370================
c8f13c06 371
372A user may be automatically given operator status upon entering a
373channel. Set the AOP field to "0" to disable auto-op or "1" to enable
374auto-op.
e07b6b46 375
6b59e728 376\1f
377File: bobot++.info, Node: Built-In Commands, Prev: Automatic Op, Up: Using the Bot
378
3793.5 Built-In Commands
380=====================
381
382Bobot++ has many built-in commands that make it useful without
383scripting support. The reference leaves off the command char; remember
384to use whatever you defined the command char to be in `bot.conf'. If a
385command needs the channel name then you must specify the channel as the
386first argument to the command when private messaging the bot a command.
387
9efc3706 388COMMAND 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
6b59e728 491
e07b6b46 492\1f
493File: bobot++.info, Node: Scripting, Next: Concept Index, Prev: Using the Bot, Up: Top
ad529fde 494
6b59e728 4954 Scripting
496***********
ad529fde 497
5a8b0ec6 498Bobot++'s most powerful feature is its scripting system. You write
ad529fde 499scripts using Guile Scheme. This manual does not cover how to use Guile
500or how to learn Scheme. *Note Guile Reference Manual: (guile)Top, for
501the Guile reference manual and
6b59e728 502`http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html' for a
ad529fde 503good tutorial on Scheme.
504
439869bf 505 Note that in previous versions the scripting commands where in the
506form `bot-FUNCTION'. They are now in the form `bot:FUNCTION'. The old
507names are still available, but are deprecated and will be removed in
c8f13c06 508Bobot++ 3.0. New commands are only available with the `bot:' prefix.
509The command `perl -pi -e ``s/bot-/bot:/g'' YOUR-FILES' should be enough
510to convert your code to use the new functions.
439869bf 511
512* Menu:
513
514* Adding New Commands::
515* Hooks::
e07b6b46 516* Scheme User Levels::
517* Sending Messages::
91dddabd 518* Misc Scripting Stuff::
439869bf 519
520\1f
521File: bobot++.info, Node: Adding New Commands, Next: Hooks, Prev: Scripting, Up: Scripting
522
6b59e728 5234.1 Adding New Commands
524=======================
439869bf 525
5a8b0ec6 526Adding a new command is simple. To register a new command use
9efc3706 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'.
439869bf 551
552\1f
e07b6b46 553File: bobot++.info, Node: Hooks, Next: Scheme User Levels, Prev: Adding New Commands, Up: Scripting
439869bf 554
6b59e728 5554.2 Hooks
556=========
439869bf 557
5a8b0ec6 558Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
6530edbf 559and tiny fugue (a MUD bot) hooks with a little bit of extra stuff added
02341ea9 560in. A hook is called when a regular expression is matched against a
561message sent to or by the bot.
562
563 Bobot++ uses different hook types for each IRC message type, and also
564includes a hook for accessing raw irc messages. Hooks are tagged with a
565priority and a flag that specifies whether to call the next hook that
566matches after calling the current one or to stop processing.
567
568 Hooks are processed from the highest to lowest priority, with
569fallthrough hooks of equal priority to non-fallthrough hooks being
570executed first.
439869bf 571
572* Menu:
573
574* Creating a Hook::
575* Hook Types::
576
577\1f
578File: bobot++.info, Node: Creating a Hook, Next: Hook Types, Prev: Hooks, Up: Hooks
579
6b59e728 5804.2.1 Creating a Hook
581---------------------
439869bf 582
9efc3706 583To add a new hook you use the function `bot:addhook'.
584
585 -- Function: bot:addhook type regex function [pri fall name]
586 TYPE specifies the type of hook (the types of hooks are listed in
587 *Note Hook Types::). REGEX is a standard regular expression. If
588 REGEX is matched, FUNCTION will be called. FUNCTION will take a
589 different number of args depending on the hook type. PRI specifies
590 the priority of the hook--higher priority hooks are executed
591 first. This argument is optional and defaults to `0'. FALL is `#t'
592 if the hook is a fallthrough hook and `#f' is the hook is not a
593 fallthrough hook. This arg is also optional and default to `#t'.
594 NAME is the optional name of the hook that defaults to "DEFAULT".
595 If you set the name then you can have more than one hook that
596 matches the same regexp, as long as they have the same name. E.g.
597 in a log script you could have the regexps for the log function
598 all be `".*"' and set their names to `"log"' to avoid a conflict
599 with other hooks.
439869bf 600
601\1f
602File: bobot++.info, Node: Hook Types, Prev: Creating a Hook, Up: Hooks
603
6b59e728 6044.2.2 Hook Types
605----------------
439869bf 606
9efc3706 607Here is a list of the various hooks funtions and notes on each one. The
608general format of each hook description is as if it was was function to
609be defined, but these describe the function to be passwd to
610`bot:add-hook'. Do _not_ name your functions these names.
439869bf 611
9efc3706 612 [ Boy, that's clumsy. I want to say that the hook/xx functions
613 that are documented below are not funtions that you call. They
614 are the functions that needs to be passed to bot:addhook for that
615 kind of hook.
439869bf 616
9efc3706 617 Still clumsy. Oh well. ]
439869bf 618
9efc3706 619 That said, here is the list of available hooks functions. FIXME:
620write docs
439869bf 621
9efc3706 622 -- Function: hooks/action from to action
623 This hook is triggered when someone performs an action. FROM is
624 the address of the person that performed the action in the form
625 `NICK ! USER @ HOST' (without the spaces). TO is the target of
626 the action, which is either a channel or the Bot's nick. ACTION
627 is the text of the action. E.g. if someone did `* foobar does
628 baz', then ACTION would be the string `"does baz"'.
439869bf 629
9efc3706 630 -- Function: hooks/nickname old-nick new-nick
631 This hook gets called when someone changes thir nickname from
632 OLD-NICK to NEW-NICK.
439869bf 633
9efc3706 634 -- Function: hooks/signoff nick rest
439869bf 635
9efc3706 636 -- Function: hooks/ctcp nick to command rest
439869bf 637
9efc3706 638 -- Function: hooks/ctcp-reply nick command rest
439869bf 639
1520dfbd 640 -- Function: hooks/disconnect server
02341ea9 641 This is called when the bot is disconnected from a server
642 unintentionally. `hooks/signoff' is called when the bot
643 purposefully disconnected. The hook function is passed the
644 hostname of the server it was disconnected from.
439869bf 645
9efc3706 646 -- Function: hooks/flood nick
439869bf 647
9efc3706 648 -- Function: hooks/invite nick channel
439869bf 649
9efc3706 650 -- Function: hooks/join nick channel
439869bf 651
9efc3706 652 -- Function: hooks/kick target from channel reason
439869bf 653
9efc3706 654 -- Function: hooks/leave nick channel
655 -- Function: hooks/part nick channel
439869bf 656
9efc3706 657 -- Function: hooks/mode nick channel modes
439869bf 658
9efc3706 659 -- Function: hooks/message from message
439869bf 660
9efc3706 661 -- Function: hooks/notice nick message
439869bf 662
9efc3706 663 -- Function: hooks/public from to message
439869bf 664
9efc3706 665 -- Function: hooks/public-notice nick to message
439869bf 666
9efc3706 667 -- Function: hooks/raw raw-message
439869bf 668
9efc3706 669 -- Function: hooks/timer time
670 This hook seems to be called once a minute. TIME is in `hh:mm'
671 format.
439869bf 672
9efc3706 673 -- Function: hooks/topic nick channel new-topic
439869bf 674
9efc3706 675 -- Function: hooks/send/public mynick dest message
439869bf 676
9efc3706 677 -- Function: hooks/send/message botnick message
439869bf 678
9efc3706 679 -- Function: hooks/send/action mynick to message
439869bf 680
9efc3706 681 -- Function: hooks/send/ctcp mynick to command message
0b7a49e2 682
9efc3706 683 -- Function: hooks/dcc/chat-begin from
684 This hook is triggered when a user begins a DCC CHAT with the bot.
685 FROM is the user's address in the form `nick!user@host'.
0b7a49e2 686
9efc3706 687 -- Function: hooks/dcc/chat-message from message
688 This hook is triggered when a user sends a message to the bot
689 through a DCC CHAT FROM is the user's address in the form
690 `nick!user@host'. MESSAGE is the message the user sent to the bot.
439869bf 691
e07b6b46 692\1f
693File: bobot++.info, Node: Scheme User Levels, Next: Sending Messages, Prev: Hooks, Up: Scripting
694
6b59e728 6954.3 Scheme User Levels
696======================
e07b6b46 697
5a8b0ec6 698There are five levels that a user may be when interfacing with a bot:
e07b6b46 699NONE, USER, TRUSTED_USER, FRIEND, MASTER. The Scheme variables for the
700user levels are `bot:user-none', `bot:user-user', `bot:user-trusted',
701`bot:user-friend', and `bot:user-master'. See *Note User Levels:: for
702more information on User Levels.
703
704 When adding a new command, think about who should be able to use it.
705Is your command a general purpose command that helps the channel (e.g.
706`!seen') that everyone should be able to use? Or is it something that
707should be restricted? See *Note User Levels:: for information on what
708level users can do what with the built in bot commands and think about
709what level a user your command is targetted towards. You must be _very_
710careful when giving new commands to lower level users because you can
711do basically everything the bot can do with a script. As the scripting
712interface becomes more powerful, you must think more about what users
713can use new commands you add.
714
715\1f
91dddabd 716File: bobot++.info, Node: Sending Messages, Next: Misc Scripting Stuff, Prev: Scheme User Levels, Up: Scripting
e07b6b46 717
6b59e728 7184.4 Sending Messages
719====================
e07b6b46 720
5a8b0ec6 721There are several types of messages you can send with Bobot++ from
e07b6b46 722scripts. There is the simple, but rather limited, `bot:say',
723`bot:action' and `bot:msg', and the more powerful, but lower level,
724`bot:send-MESSAGE' functions. Most bots will probably only need the
725higher level functions, but for the sake of why-not Bobot++ lets you
ce02032f 726use the lower level functions (in progress).
e07b6b46 727
728* Menu:
729
730* High Level Message Functions::
731* Low Level Message Functions::
732
733\1f
734File: bobot++.info, Node: High Level Message Functions, Next: Low Level Message Functions, Prev: Sending Messages, Up: Sending Messages
735
6b59e728 7364.4.1 "High Level" Message Functions
737------------------------------------
e07b6b46 738
9efc3706 739 -- Function: bot:say channel message
740 Send a public or private MESSAGE to CHANNEL.
741
742 Sends a normal text message, as if a user had typed it in. The
743 DEST can be a nickname or a channel.
744
745 -- Function: bot:action channel message
746 Send an "action" type MESSAGE to CHANNEL
747
748 -- Function: bot:msg nick message
749 The same as if a user typed `/msg nick message' to their IRC
750 client.
e07b6b46 751
5aec4622 752 -- Function: bot:notice target message
753 Sends MESSAGE as a NOTICE to TARGET. TARGET may be a user (nick)
5c73c60a 754 or a channel. This returns 0 on success.
5aec4622 755
e07b6b46 756\1f
757File: bobot++.info, Node: Low Level Message Functions, Prev: High Level Message Functions, Up: Sending Messages
758
6b59e728 7594.4.2 "Low Level" Message Functions
760-----------------------------------
e07b6b46 761
5a8b0ec6 762The "Low Level" messaging functions allow you to do things like send
fed59248 763CTCP messages. You probably want to read rfc 2812 and the CTCP spec
e07b6b46 764before using these. If you have no idea what these do, read rfc 2812
765(IRC Client Protocol) and CTCP spec. These functions all return
766`*unspecified*' always, so don't use the return value for anything.
767
9efc3706 768 -- Function: bot:send-CTCP to command message
769 `to' is the target of your CTCP message, `command' is the CTCP
770 command, and `message' is the message (or arguments) of the
771 command. Make sure to `bot:ctcp-quote' the message!
e07b6b46 772
91dddabd 773\1f
774File: bobot++.info, Node: Misc Scripting Stuff, Prev: Sending Messages, Up: Scripting
775
6b59e728 7764.5 Misc. Scripting Stuff
777=========================
91dddabd 778
5a8b0ec6 779These are a few useful things that I thought people writing scripts
91dddabd 780might want to know.
781
782 If you want to execute code when the bot exits, just do `add-hook!
783bot:exit-hook THUNK' where THUNK is an argumentless procedure (a
784thunk). When the bot exits your thunk will be called.
785
9efc3706 786 [ I didn't know where to put any of these, so I jsut stuck them in
787 here.
788
789 There probably needs to be several sections added, like dealing
790 with users (kicking, added, etc), dealing with the bot (channels,
791 nickname of the bot, etc), server issues (serverlist), useful
792 tools (nslookup, whois), and do on. ]
793
794 -- Function: bot:adduser nick-or-mask cbannel-mask level prot auto-op
795 Adds an user to the userlist, for a `nick!user@host' matching the
796 one given, on a channel matching the CHANNELMASK given.
797
798 The LEVEL can be: The PROT can be: The AUTO-OP can be:
799 0 - No level 0 - No protection 0 - No auto-op
800 1 - User 1 - No ban 1 - Op on join
801 2 - Trusted User 2 - No kick
802 3 - Friend 3 - No deop
803 4 - Master
804
805
806 -- Function: bot:addserver hostname ip-address [portnumber]
807 Adds the server specified by HOSTNAME or IP-ADDRESS to the server
808 list.
809
810 -- Function: bot:addshit nick-or-mask channel-mask level [time reason]
811 Adds an user to the shitlist, for a nick!user@host matching the
812 one given, on a channel matching the CHANNELMASK given.
813
814 The LEVEL can be:
815 0 - No shit
816 1 - No op
817 2 - Kick and Ban on join
818 3 - Kick and Ban on join, no deban
819
820
821 -- Function: bot:ban channel mask-or-nick
822 Bans MASK or NICK from CHANNEL. You need to be a trusted user to
823 ban with a MASK.
824
825 -- Function: bot:change-command-level nick-or-mask channel-mask
826 new-level
827 Gives NICK or MASK level NEW-LEVEL on channel(s) CHANNEL-MASK.
828 Note that you can not change level for someone whose level is
829 greater than yours, and that you can not give a level greater than
830 yours.
831
832 -- Function: bot:cycle channel
833 Makes the bot leave and join CHANNEL.
834
835 -- Function: bot:deban channel mask-or-nick
836 Debans MASK or NICK from CHANNEL. You need to be a trusted user to
837 deban with a MASK.
838
839 -- Function: bot:delserver server-number
840 Deletes server from server list whose number in the server list is
841 SERVER-NUMBER
842
843 -- Function: bot:deluser nick-or-mask channel-mask
844 Removes NICK or MASK from the userlist.
845
846 -- Function: bot:delshit nick-or-mask channel-mask
847 Removes NICK or MASK from the shitlist.
848
849 -- Function: bot:deop channel mask-or-nick
850 Deops MASK or NICK on CHANNEL.
851
852 -- Function: bot:die reason
853 Makes the bot stop immediately.
854
855 -- Function: bot:do ?
856
857 -- Function: bot:invite channel nick
858 Invites NICK on CHANNEL.
859
860 -- Function: bot:join channel
861 Makes the bot join CHANNEL.
862
863 -- Function: bot:keep channel modes
864 Sets the MODES that the bot will keep for CHANNEL. See also STATS.
865
866 -- Function: bot:kick channel mask-or-nick [reason]
867 Kicks MASK or NICK out of CHANNEL, because of REASON. You need to
868 be a trusted user to use a MASK.
869
870 -- Function: bot:kickban channel mask-or-nick [reason]
871 Bans then kicks MASK or NICK out of CHANNEL, because of REASON.
872 You need to be a trusted user to use a MASK.
873
874 -- Function: bot:lock channel
875 Locks topic on CHANNEL.
876
877 -- Function: bot:logport
878 [ Probably returns the log port? ]
879
880 -- Function: bot:mode channel mode-string
881 Sends MODE-STRING as mode for CHANNEL.
882
883 -- Function: bot:nextserver
884 Makes the bot connect to the next server in its server list.
885
886 -- Function: bot:nick nick
887 Makes the bot use nickname NICK.
888
889 -- Function: bot:op channel nick
890 Ops NICK on CHANNEL.
891
892 -- Function: bot:part channel
893 Makes the bot leave CHANNEL.
894
895 -- Function: bot:reconnect
896 Makes the bot reconnect to its current server.
897
898 -- Function: bot:server server-number
899 Select the server to connect to. SERVER-NUMBER is the number of
900 the server in the serverlist.
901
902 -- Function: bot:setfloodrate ?
903
904 -- Function: bot:setversion ?
905
906 -- Function: bot:tban channel nick-or-mask time
907 Bans NICK or MASK from CHANNEL for TIME seconds.
908
909 -- Function: bot:tkban channel nick-or-mask time [reason]
910 Bans NICK or MASK from CHANNEL for TIME seconds, then kicks
911 him/them because of REASON.
912
913 -- Function: bot:topic channel topic
914 If no TOPIC is given, prints CHANNEL's topic. Otherwise, the bot
915 will change CHANNEL's topic to TOPIC.
916
917 -- Function: bot:unlock channel
918 Makes the bot unlock topic on CHANNEL.
919
920 -- Function: bot:getnickname
921 [ Gets the bot's nickname? ]
922
923 -- Function: bot:getserver
924
925 -- Function: bot:getserverlist
926
927 -- Function: bot:flush
928 [ Flushes the socket to the server? ]
929
930 -- Function: bot:flushport
931 [ Flushes the log port? ]
932
933 -- Function: bot:random ?
934 [ Returns a random number? What range? Why? ]
935
936 -- Function: bot:delcommand
937 [ Probably deletes a command added with `bot:addcommand' ? ]
938
939 -- Function: bot:addtimer ? ?
940
941 -- Function: bot:deltimer ?
942
943 -- Function: bot:dcc-chat-send ? ?
944
945 [ And what about the stuff defined in `bobot-utils.scm' ? I just
946 added it here so it could be somewhere. There should also be a
947 section dealing with modules. How to use them. What module
948 scripts are in. What module bobot++ provided primites are in.
949 And so on. ]
950
951 -- Function: bot:log . messages
952 Write as many MESSAGES as you want to the log. If the arg is a
953 thunk it will be executed and it's output will be written to the
954 log.
955
956 -- Function: bot:load file
957
958 -- Function: bot:load-module module-spec
959
960 -- Function: bot:use-module module-spec
961
962 -- Function: bot:match-not-channel regex
963 match-not-channel adds a prefix regex to your REGEX so it doesn't
964 match the sender or channel in a PUBLIC message
965
966 -- Function: bot:match-to-me regex
967 match-to-me matches text that was addressed to the bot with a ':',
968 ',', or nothing after the bot name.
969
970 -- Function: bot:sent-to-me? message
971
972 -- Function: bot:ctcp-quote message
973 Returns the CTCP quoted message Input _MUST NOT_ contain the
974 trailing `\r\n' (it is added by the message sending code).
975
976 -- Variable: %bot:loadpath
977
978 -- Function: %bot:load-extensions
979
ad529fde 980\1f
981File: bobot++.info, Node: Concept Index, Next: Function Index, Prev: Scripting, Up: Top
982
983Concept Index
984*************
985
6b59e728 986\0\b[index\0\b]
ad529fde 987* Menu:
e07b6b46 988
6b59e728 989* Background on Hooks: Hooks. (line 6)
e07b6b46 990
ad529fde 991\1f
992File: bobot++.info, Node: Function Index, Next: Variable Index, Prev: Concept Index, Up: Top
993
994Function Index
995**************
996
6b59e728 997\0\b[index\0\b]
ad529fde 998* Menu:
e07b6b46 999
9efc3706 1000* %bot:load-extensions: Misc Scripting Stuff.
1001 (line 206)
1002* bot:action: High Level Message Functions.
1003 (line 13)
1004* bot:addcommand: Adding New Commands. (line 11)
1005* bot:addhook: Creating a Hook. (line 9)
1006* bot:addserver: Misc Scripting Stuff.
1007 (line 34)
1008* bot:addshit: Misc Scripting Stuff.
1009 (line 38)
1010* bot:addtimer: Misc Scripting Stuff.
1011 (line 167)
1012* bot:adduser: Misc Scripting Stuff.
1013 (line 22)
1014* bot:ban: Misc Scripting Stuff.
1015 (line 49)
1016* bot:change-command-level: Misc Scripting Stuff.
1017 (line 54)
1018* bot:ctcp-quote: Misc Scripting Stuff.
1019 (line 200)
1020* bot:cycle: Misc Scripting Stuff.
1021 (line 60)
1022* bot:dcc-chat-send: Misc Scripting Stuff.
1023 (line 171)
1024* bot:deban: Misc Scripting Stuff.
1025 (line 63)
1026* bot:delcommand: Misc Scripting Stuff.
1027 (line 164)
1028* bot:delserver: Misc Scripting Stuff.
1029 (line 67)
1030* bot:delshit: Misc Scripting Stuff.
1031 (line 74)
1032* bot:deltimer: Misc Scripting Stuff.
1033 (line 169)
1034* bot:deluser: Misc Scripting Stuff.
1035 (line 71)
1036* bot:deop: Misc Scripting Stuff.
1037 (line 77)
1038* bot:die: Misc Scripting Stuff.
1039 (line 80)
1040* bot:do: Misc Scripting Stuff.
1041 (line 83)
1042* bot:flush: Misc Scripting Stuff.
1043 (line 155)
1044* bot:flushport: Misc Scripting Stuff.
1045 (line 158)
1046* bot:getnickname: Misc Scripting Stuff.
1047 (line 148)
1048* bot:getserver: Misc Scripting Stuff.
1049 (line 151)
1050* bot:getserverlist: Misc Scripting Stuff.
1051 (line 153)
1052* bot:invite: Misc Scripting Stuff.
1053 (line 85)
1054* bot:join: Misc Scripting Stuff.
1055 (line 88)
1056* bot:keep: Misc Scripting Stuff.
1057 (line 91)
1058* bot:kick: Misc Scripting Stuff.
1059 (line 94)
1060* bot:kickban: Misc Scripting Stuff.
1061 (line 98)
1062* bot:load: Misc Scripting Stuff.
1063 (line 184)
1064* bot:load-module: Misc Scripting Stuff.
1065 (line 186)
1066* bot:lock: Misc Scripting Stuff.
1067 (line 102)
1068* bot:log: Misc Scripting Stuff.
1069 (line 179)
1070* bot:logport: Misc Scripting Stuff.
1071 (line 105)
1072* bot:match-not-channel: Misc Scripting Stuff.
1073 (line 190)
1074* bot:match-to-me: Misc Scripting Stuff.
1075 (line 194)
1076* bot:mode: Misc Scripting Stuff.
1077 (line 108)
1078* bot:msg: High Level Message Functions.
1079 (line 16)
1080* bot:nextserver: Misc Scripting Stuff.
1081 (line 111)
1082* bot:nick: Misc Scripting Stuff.
1083 (line 114)
5aec4622 1084* bot:notice: High Level Message Functions.
1085 (line 20)
9efc3706 1086* bot:op: Misc Scripting Stuff.
1087 (line 117)
1088* bot:part: Misc Scripting Stuff.
1089 (line 120)
1090* bot:random: Misc Scripting Stuff.
1091 (line 161)
1092* bot:reconnect: Misc Scripting Stuff.
1093 (line 123)
1094* bot:say: High Level Message Functions.
1095 (line 7)
1096* bot:send-CTCP: Low Level Message Functions.
1097 (line 13)
1098* bot:sent-to-me?: Misc Scripting Stuff.
1099 (line 198)
1100* bot:server: Misc Scripting Stuff.
1101 (line 126)
1102* bot:setfloodrate: Misc Scripting Stuff.
1103 (line 130)
1104* bot:setversion: Misc Scripting Stuff.
1105 (line 132)
1106* bot:tban: Misc Scripting Stuff.
1107 (line 134)
1108* bot:tkban: Misc Scripting Stuff.
1109 (line 137)
1110* bot:topic: Misc Scripting Stuff.
1111 (line 141)
1112* bot:unlock: Misc Scripting Stuff.
1113 (line 145)
1114* bot:use-module: Misc Scripting Stuff.
1115 (line 188)
1116* hooks/action: Hook Types. (line 22)
1117* hooks/ctcp: Hook Types. (line 36)
1118* hooks/ctcp-reply: Hook Types. (line 38)
02341ea9 1119* hooks/dcc/chat-begin: Hook Types. (line 83)
1120* hooks/dcc/chat-message: Hook Types. (line 87)
9efc3706 1121* hooks/disconnect: Hook Types. (line 40)
02341ea9 1122* hooks/flood: Hook Types. (line 46)
1123* hooks/invite: Hook Types. (line 48)
1124* hooks/join: Hook Types. (line 50)
1125* hooks/kick: Hook Types. (line 52)
1126* hooks/leave: Hook Types. (line 54)
1127* hooks/message: Hook Types. (line 59)
1128* hooks/mode: Hook Types. (line 57)
9efc3706 1129* hooks/nickname: Hook Types. (line 30)
02341ea9 1130* hooks/notice: Hook Types. (line 61)
1131* hooks/part: Hook Types. (line 55)
1132* hooks/public: Hook Types. (line 63)
1133* hooks/public-notice: Hook Types. (line 65)
1134* hooks/raw: Hook Types. (line 67)
1135* hooks/send/action: Hook Types. (line 79)
1136* hooks/send/ctcp: Hook Types. (line 81)
1137* hooks/send/message: Hook Types. (line 77)
1138* hooks/send/public: Hook Types. (line 75)
9efc3706 1139* hooks/signoff: Hook Types. (line 34)
02341ea9 1140* hooks/timer: Hook Types. (line 69)
1141* hooks/topic: Hook Types. (line 73)
e07b6b46 1142
ad529fde 1143\1f
1144File: bobot++.info, Node: Variable Index, Prev: Function Index, Up: Top
1145
1146Variable Index
1147**************
1148
6b59e728 1149\0\b[index\0\b]
ad529fde 1150* Menu:
2e20c3e1 1151
9efc3706 1152* %bot:loadpath: Misc Scripting Stuff.
1153 (line 204)
fed59248 1154* exit-hook: Misc Scripting Stuff.
6b59e728 1155 (line 9)
6b59e728 1156* user-friend: Scheme User Levels. (line 6)
1157* user-master: Scheme User Levels. (line 6)
1158* user-none: Scheme User Levels. (line 6)
1159* user-trusted: Scheme User Levels. (line 6)
1160* user-user: Scheme User Levels. (line 6)
e07b6b46 1161
1162
2e20c3e1 1163\1f
1164Tag Table:
2e18045a 1165Node: Top\7f527
1166Node: Introduction\7f1816
1167Node: Configuration\7f2008
1168Node: Configuration Files\7f2295
1169Node: bot.conf\7f2510
1170Node: server syntax\7f3948
1171Node: channel syntax\7f4812
1172Node: bot.users\7f5655
1173Node: Configuration File Placement\7f6558
9efc3706 1174Node: Using the Bot\7f7260
1175Node: Starting the Bot\7f7510
1176Node: User Levels\7f8853
1177Node: Protection\7f10309
1178Node: Automatic Op\7f10917
1179Node: Built-In Commands\7f11206
1180Node: Scripting\7f18185
1181Node: Adding New Commands\7f19150
1182Node: Hooks\7f20473
02341ea9 1183Node: Creating a Hook\7f21313
1184Node: Hook Types\7f22496
1185Node: Scheme User Levels\7f25525
1186Node: Sending Messages\7f26659
1187Node: High Level Message Functions\7f27275
5c73c60a 1188Node: Low Level Message Functions\7f28055
1189Node: Misc Scripting Stuff\7f28823
1190Node: Concept Index\7f35399
1191Node: Function Index\7f35618
1192Node: Variable Index\7f45606
2e20c3e1 1193\1f
1194End Tag Table
Unnamed repository; edit this file 'description' to name the repository.