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