* bot.conf::
* bot.users::
+* bot.shit::
bot.conf
* User Levels::
* Protection::
* Automatic Op::
+* Shit Levels::
* Built-In Commands::
Scripting
* Adding New Commands::
* Hooks::
-* Scheme User Levels::
* Sending Messages::
* Misc Scripting Stuff::
1 Introduction
**************
-This manual feels abused and neglected because it has almost no content.
+Bobot++ is a powerful IRC bot written in C++. It can be used standalone
+as a channel maintenence bot, or extended to do almost anything using
+Scheme scripts.
+
+ FIXME: Fill the intro in more?
\1f
File: bobot++.info, Node: Configuration, Next: Using the Bot, Prev: Introduction, Up: Top
* bot.conf::
* bot.users::
+* bot.shit::
\1f
File: bobot++.info, Node: bot.conf, Next: bot.users, Prev: Configuration Files, Up: Configuration Files
* server syntax::
* channel syntax::
+ * MAXNICKLENGTH <9>: The maximum length a valid nickname may be.
+ This should be set before setting the bot's nickname if it will be
+ more than nine characters long. Most IRC servers support nicknames
+ longer than nine characters, but Bobot++ still follows the old spec
+ and defaults to nine.
+
* NICKNAME <Bobot>: The nickname of the bot (NICK is an alias for
NICKNAME)
attempt to maintain any modes.
\1f
-File: bobot++.info, Node: bot.users, Prev: bot.conf, Up: Configuration Files
+File: bobot++.info, Node: bot.users, Next: bot.shit, Prev: bot.conf, Up: Configuration Files
-2.2.2 bot.users
----------------
+2.2.2 bot.users (User List)
+---------------------------
`bot.users' is the default file name of the userlist. It may be changed
-in `bot.conf'. The file contains lines with the format:
+in `bot.conf'. You must add an entry for yourself manually. You will
+probably want to add other entries using the IRC command interface as
+it is more intuitive than editing the file by hand.
+
+ The file contains lines with the format:
- `MASK:CHANNEL:LEVEL:PROTECTION:AUTO-OP'
+ `HOST_MASK:CHANNEL_MASK:LEVEL:PROTECTION:AUTO-OP:EXPIRATION:PASSWORD'
- * MASK is the host mask (e.g. `*!*username
+ * HOST_MASK is the host mask (e.g. `*!*username
.domain.com') of the user
- * CHANNEL is a channel mask of the channels that the user has
+ * CHANNEL_MASK is a channel mask of the channels that the user has
priviliges to use the bot in (e.g. `*' for all channels, `#*' for
all non-local channel, `#foo*' for all channels starting with
"foo," `#bar' for channel "#bar" only, etc.)
* AUTO-OP is set to control whether a user is automatically given
operator priviliges on channel entry (*Note Automatic Op::).
+ * EXPIRATION is the UNIX timestamp of when the user entry becomes
+ invalid. Setting this to -1 will make the entry permanent.
+
+ * PASSWORD is the password the user must supply to the bot to
+ authenticate. This can be set to `*NONE*' to not have a password.
+
+
+\1f
+File: bobot++.info, Node: bot.shit, Prev: bot.users, Up: Configuration Files
+
+2.2.3 bot.shit (Ban/Shit List)
+------------------------------
+
+This file stores the ban list. The name may be changed in `bot.conf'.
+You will most likely want to use the IRC command interface to edit this
+file instead of editing it directly.
+
+ The file contains lines in the form:
+
+ `HOST_MASK:CHANNEL_MASK:LEVEL:EXPIRATION:REASON'
+
+ * HOST_MASK is the host mask (e.g. `*!*username
+ .domain.com') of the user
+
+ * CHANNEL_MASK is a channel mask of the channels that the user is
+ banned on (e.g. `*' for all channels, `#*' for all non-local
+ channel, `#foo*' for all channels starting with "foo," `#bar' for
+ channel "#bar" only, etc.
+
+ * LEVEL is a number specifying if the bot should not allow the user
+ to gain ops, to kick the user upon joining, or to prevent the user
+ from being debanned by other users. *Note Shit Levels:: for
+ information on the available levels.
+
+ * EXPIRATION is the UNIX timestamp of when the shit entry becomes
+ invalid. This may be set to -1 to make it valid forever.
+
+ * REASON is text that is sent to the user when they are kicked or
+ banned from the channel.
+
\1f
File: bobot++.info, Node: Using the Bot, Next: Scripting, Prev: Configuration, Up: Top
* User Levels::
* Protection::
* Automatic Op::
+* Shit Levels::
* Built-In Commands::
\1f
* `[--debug][-D]' Makes Bobot++ print debugging info and run in the
foreground
- * `[--debug-scripts][-S]' Enabled the Guile debugging evaluator for
+ * `[--debug-scripts][-S]' Enables the Guile debugging evaluator for
verbose script errors and backtraces while still running the bot
in the background.
user always maintains operator status.
\1f
-File: bobot++.info, Node: Automatic Op, Next: Built-In Commands, Prev: Protection, Up: Using the Bot
+File: bobot++.info, Node: Automatic Op, Next: Shit Levels, Prev: Protection, Up: Using the Bot
3.4 Automatic Op
================
1. `bot:aop/yes' Do automatically op the user
\1f
-File: bobot++.info, Node: Built-In Commands, Prev: Automatic Op, Up: Using the Bot
+File: bobot++.info, Node: Shit Levels, Next: Built-In Commands, Prev: Automatic Op, Up: Using the Bot
-3.5 Built-In Commands
+3.5 Shit Levels
+===============
+
+The shit list and shit list related commands use different levels to
+define how much the bot hates a user. Scheme uses the symbolic names,
+the shit list and IRC commands use the numbers.
+
+ 0. `bot:shit/none' The bot doesn't hate the user (this is the normal
+ level)
+
+ 1. `bot:shit/no-op' The bot will deop the user any time he gains
+ operator priviliges in the channel
+
+ 2. `bot:shit/no-join' The bot will kick and ban the user when he
+ joins the channel
+
+ 3. `bot:shit/no-deban' The bot will kick and ban usre when he joins
+ the channel, and will prevent other users from debanning him.
+
+\1f
+File: bobot++.info, Node: Built-In Commands, Prev: Shit Levels, Up: Using the Bot
+
+3.6 Built-In Commands
=====================
Bobot++ has many built-in commands that make it useful without
* Adding New Commands::
* Hooks::
-* Scheme User Levels::
* Sending Messages::
* Misc Scripting Stuff::
NEEDS-CHANNEL? is a bool that is true if the function needs the
channel name as its first arg, and false otherwise. NUM-OF-ARGS
is the number of args FUNC will take and must be within zero (0)
- and twenty (20). MIN-LEVEL is one of the *Note Scheme User
- Levels::. A user must be at least a `min-level' user to use the
- new command. None of the arguments are guaranteed to be passed;
- if they aren't they are set to the empty string `""'. An example
- of a new command would be:
+ and twenty (20). MIN-LEVEL is one of the *Note User Levels::. A
+ user must be at least a MIN-LEVEL user to use the new command.
+ None of the arguments are guaranteed to be passed; if they aren't
+ they are set to the empty string `""'. An example of a new
+ command would be:
(define (hello channel name)
(if (string=? name "")
World USER" if called as `!hello USER'.
\1f
-File: bobot++.info, Node: Hooks, Next: Scheme User Levels, Prev: Adding New Commands, Up: Scripting
+File: bobot++.info, Node: Hooks, Next: Sending Messages, Prev: Adding New Commands, Up: Scripting
4.2 Hooks
=========
MESSAGE is a string containing the arguments to the CTCP command.
+ -- Function: hooks/send/who who
+ This is called when the bot sends a WHO message. The regex is
+ matched on WHO, which is also passed as the only argument to your
+ function.
+
+ WHO is the channel or nick that was WHOed.
+
+ -- Function: hooks/send/whois nick
+ This is called when the bot sends a WHOIS message. The regex is
+ matched on NICK, which is also passed as the only argument to your
+ function.
+
+ NICK is the nickname of the person who was WHOISed.
+
\1f
File: bobot++.info, Node: DCC CHAT Hooks, Next: Miscellaneous Hooks, Prev: Sent Message Hooks, Up: Hook Types
TIME is the in zero-padded `hh:mm' format.
\1f
-File: bobot++.info, Node: Scheme User Levels, Next: Sending Messages, Prev: Hooks, Up: Scripting
-
-4.3 Scheme User Levels
-======================
-
-There are five levels that a user may be when interfacing with a bot:
-NONE, USER, TRUSTED_USER, FRIEND, MASTER. The Scheme variables for the
-user levels are `bot:user-none', `bot:user-user', `bot:user-trusted',
-`bot:user-friend', and `bot:user-master'. See *Note User Levels:: for
-more information on User Levels.
-
- When adding a new command, think about who should be able to use it.
-Is your command a general purpose command that helps the channel (e.g.
-`!seen') that everyone should be able to use? Or is it something that
-should be restricted? See *Note User Levels:: for information on what
-level users can do what with the built in bot commands and think about
-what level a user your command is targetted towards. You must be _very_
-careful when giving new commands to lower level users because you can
-do basically everything the bot can do with a script. As the scripting
-interface becomes more powerful, you must think more about what users
-can use new commands you add.
+File: bobot++.info, Node: Sending Messages, Next: Misc Scripting Stuff, Prev: Hooks, Up: Scripting
-\1f
-File: bobot++.info, Node: Sending Messages, Next: Misc Scripting Stuff, Prev: Scheme User Levels, Up: Scripting
-
-4.4 Sending Messages
+4.3 Sending Messages
====================
There are several types of messages you can send with Bobot++ from
-scripts. There is the simple, but rather limited, `bot:say',
-`bot:action' and `bot:msg', and the more powerful, but lower level,
-`bot:send-MESSAGE' functions. Most bots will probably only need the
-higher level functions, but for the sake of why-not Bobot++ lets you
-use the lower level functions (in progress).
+scripts. They are split into High and Low level message sending
+functions. Most bots will only use the high level functions, but the
+low level ones are provided for when a bot needs to do things like send
+raw IRC messages or CTCP commands.
* Menu:
\1f
File: bobot++.info, Node: High Level Message Functions, Next: Low Level Message Functions, Prev: Sending Messages, Up: Sending Messages
-4.4.1 "High Level" Message Functions
+4.3.1 "High Level" Message Functions
------------------------------------
-- Function: bot:say channel message
-- Function: bot:action channel message
Send an "action" type MESSAGE to CHANNEL
- -- Function: bot:msg nick message
- The same as if a user typed `/msg nick message' to their IRC
- client.
+ -- Function: bot:msg target message
+ -- Function: bot:say target message
+ Send a public or private message to TARGET.
+
+ TARGET may be a channel or a nickname.
+
+ In versions of Bobot++ prior to 2.1.8 `bot:say' could only send to
+ channels, and `bot:msg' could only send private messages to users.
+ They are aliases of the same command now, but it may be worth
+ using them as they used to for clarity.
-- Function: bot:notice target message
Sends MESSAGE as a NOTICE to TARGET. TARGET may be a user (nick)
- or a channel. This returns 0 on success.
+ or a channel.
\1f
File: bobot++.info, Node: Low Level Message Functions, Prev: High Level Message Functions, Up: Sending Messages
-4.4.2 "Low Level" Message Functions
+4.3.2 "Low Level" Message Functions
-----------------------------------
The "Low Level" messaging functions allow you to do things like send
\1f
File: bobot++.info, Node: Misc Scripting Stuff, Prev: Sending Messages, Up: Scripting
-4.5 Misc. Scripting Stuff
+4.4 Misc. Scripting Stuff
=========================
These are a few useful things that I thought people writing scripts
* bot:nick: Misc Scripting Stuff.
(line 114)
* bot:notice: High Level Message Functions.
- (line 20)
+ (line 27)
* bot:op: Misc Scripting Stuff.
(line 117)
* bot:part: Misc Scripting Stuff.
* hooks/send/ctcp: Sent Message Hooks. (line 33)
* hooks/send/message: Sent Message Hooks. (line 18)
* hooks/send/public: Sent Message Hooks. (line 10)
+* hooks/send/who: Sent Message Hooks. (line 43)
+* hooks/send/whois: Sent Message Hooks. (line 50)
* hooks/signoff: Received Message Hooks.
(line 24)
* hooks/timer: Miscellaneous Hooks. (line 12)
(line 212)
* exit-hook: Misc Scripting Stuff.
(line 9)
-* user-friend: Scheme User Levels. (line 6)
-* user-master: Scheme User Levels. (line 6)
-* user-none: Scheme User Levels. (line 6)
-* user-trusted: Scheme User Levels. (line 6)
-* user-user: Scheme User Levels. (line 6)
\1f
Tag Table:
Node: Top\7f538
-Node: Introduction\7f1948
-Node: Configuration\7f2140
-Node: Configuration File Placement\7f2584
-Node: Configuration Files\7f3085
-Node: bot.conf\7f3278
-Node: server syntax\7f4885
-Node: channel syntax\7f5683
-Node: bot.users\7f6727
-Node: Using the Bot\7f7630
-Node: Starting the Bot\7f7880
-Node: User Levels\7f9389
-Node: Protection\7f10777
-Node: Automatic Op\7f11495
-Node: Built-In Commands\7f11914
-Node: Scripting\7f18893
-Node: Adding New Commands\7f19965
-Node: Hooks\7f21286
-Node: Creating a Hook\7f22126
-Node: Hook Types\7f23332
-Node: Received Message Hooks\7f23896
-Node: Sent Message Hooks\7f29123
-Node: DCC CHAT Hooks\7f30520
-Node: Miscellaneous Hooks\7f31560
-Node: Scheme User Levels\7f32009
-Node: Sending Messages\7f33143
-Node: High Level Message Functions\7f33759
-Node: Low Level Message Functions\7f34539
-Node: Misc Scripting Stuff\7f35592
-Node: Concept Index\7f42417
-Node: Function Index\7f42636
-Node: Variable Index\7f54144
+Node: Introduction\7f1954
+Node: Configuration\7f2266
+Node: Configuration File Placement\7f2710
+Node: Configuration Files\7f3211
+Node: bot.conf\7f3417
+Node: server syntax\7f5337
+Node: channel syntax\7f6135
+Node: bot.users\7f7179
+Node: bot.shit\7f8614
+Node: Using the Bot\7f9839
+Node: Starting the Bot\7f10105
+Node: User Levels\7f11614
+Node: Protection\7f13002
+Node: Automatic Op\7f13720
+Node: Shit Levels\7f14133
+Node: Built-In Commands\7f14884
+Node: Scripting\7f21862
+Node: Adding New Commands\7f22911
+Node: Hooks\7f24222
+Node: Creating a Hook\7f25060
+Node: Hook Types\7f26266
+Node: Received Message Hooks\7f26830
+Node: Sent Message Hooks\7f32057
+Node: DCC CHAT Hooks\7f33941
+Node: Miscellaneous Hooks\7f34981
+Node: Sending Messages\7f35430
+Node: High Level Message Functions\7f35962
+Node: Low Level Message Functions\7f37026
+Node: Misc Scripting Stuff\7f38079
+Node: Concept Index\7f44904
+Node: Function Index\7f45123
+Node: Variable Index\7f56777
\1f
End Tag Table
HCoop / clinton / bobotpp.git / blobdiff