diff --git a/docs/CAPABILITIES b/docs/CAPABILITIES index c296bbfa0..1171d0a35 100644 --- a/docs/CAPABILITIES +++ b/docs/CAPABILITIES @@ -83,8 +83,8 @@ People who are to administer channels with the bot should have the #channel.op capability -- whatever channel they are to administrate, they should have that channel capability for "op". For example, since I want inkedmn to be an administrator in #supybot, I'll give him the #supybot.op capability. This is -in addition to his admin capability, since admin capability doesn't give the -person having it control over channels. #channel.op is object used for such +in addition to his admin capability, since the admin capability doesn't give +the person having it control over channels. #channel.op is used for such things as giving/receiving ops, kickbanning people, lobotomizing the bot, ignoring users in the channel, and managing the channel capabilities. The #channel.op capability is also basically the equivalent of the owner capability diff --git a/docs/DocBook/Makefile b/docs/DocBook/Makefile index fb1f24895..f9662593f 100644 --- a/docs/DocBook/Makefile +++ b/docs/DocBook/Makefile @@ -1,8 +1,25 @@ JADE=/usr/bin/jade -STYLESHEET=/usr/share/sgml/docbook/stylesheet/dsssl/modular/html/docbook.dsl +JADETEX=/usr/bin/jadetex +DVIPDF=/usr/bin/dvipdfm +HTMLSTYLESHEET=/usr/share/sgml/docbook/stylesheet/dsssl/modular/html/docbook.dsl +PRINTSTYLESHEET=/usr/share/sgml/docbook/stylesheet/dsssl/modular/print/docbook.dsl -example: example.sgml - $(JADE) -t xml -d $(STYLESHEET) $< +html: example.sgml capabilities.sgml + $(JADE) -t xml -d $(HTMLSTYLESHEET) $< + +example.dvi: example.sgml + $(JADE) -t tex -d $(PRINTSTYLESHEET) $< + $(JADETEX) $(addsuffix .tex, $(basename $<)) + +example.pdf: example.dvi + $(DVIPDF) -o $(addsuffix .pdf, $(basename $<)) $< + +capabilities.dvi: capabilities.sgml + $(JADE) -t tex -d $(PRINTSTYLESHEET) $< + $(JADETEX) $(addsuffix .tex, $(basename $<)) + +capabilities.pdf: capabilities.dvi + $(DVIPDF) -o $(addsuffix .pdf, $(basename $<)) $< clean: rm -f *.html diff --git a/docs/DocBook/capabilities.sgml b/docs/DocBook/capabilities.sgml new file mode 100644 index 000000000..e161cfb63 --- /dev/null +++ b/docs/DocBook/capabilities.sgml @@ -0,0 +1,205 @@ + + +
+ + + + Jeremiah + Fincher + + + Daniel + DiPaolo + DocBook translator + + + Supybot capabilities system explanation + + + 0.1 + 18 Feb 2004 + Initial revision + + + + + Introduction + + Supybot's capabilities overview and comparisons to other bots + + + Ok, some some explanation of the capabilities system is probably + in order. With most IRC bots (including the ones I've written + myself prior to this one) “what a user can do” is set + in one of two ways. On the really simple + bots, each user has a numeric “level” and commands + check to see if a user has a “high enough level” to + perform some operation. On bots that are slightly more + complicated, users have a list of “flags” whose + meanings are hardcoded, and the bot checks to see if a user + possesses the necessary flag before performing some operation. + Both methods, IMO, are rather arbitrary, and force the user and + the programmer to be unduly confined to less expressive + constructs. + + + This bot is different. Every user has a set of + “capabilities” that is consulted every time they give + the bot a command. Commands, rather than checking for a user + level of 100, or checking if the user has an o + flag, are instead able to check if a user has the + owner capability. At this point such a + difference might not seem revolutionary, but at least we can + already tell that this method is self-documenting, and easier for + users and developers to understand what's truly going on. + + + + What sets supybot's capabilities apart + + If that was all, well, the capability system would be + “cool”, but not many people would say it was + “awesome”. But it is awesome! + Several things are happening behind the scene that make it + awesome, and these are things that couldn't happen if the bot was + using numeric userlevels or single-character flags. First, + whenever a user issues the bot a command, the command dispatcher + checks to make sure the user doesn't have the + “anticapability” for that command. An anticapability is + a capability that, instead of saying “what a user can + do”, says what a user cannot do. It's + formed rather simply by adding a dash (“-”) to the + beginning of a capability; rot13 is a + capability, and -rot13 is an anticapability. + Anyway, when a user issues the bot a command, perhaps + calc or help the bot + first checks to make sure the user doesn't have the + -calc or the -help + capabilities before even considering responding to the user. So + commands can be turned on or off on a per + user basis, offering finegrained control not often (if + at all!) seen in other bots. + + + Channel capabilities + + But that's not all! The capabilities system also supports + Channel capabilities, which are + capabilities that only apply to a specific channel; they're of + the form #channel.capability. Whenever a + user issues a command to the bot in a channel, the command + dispatcher also checks to make sure the user doesn't have the + anticapability for that command in that + channel and if the user does, the bot won't respond + to the user in the channel. Thus now, in addition to having + the ability to turn individual commands on or off for an + individual user, we can now turn commands on or off for an + individual user on an individual channel! + + + So when a user foo sends a command + bar to the bot on channel + #baz, first the bot checks to see if the + user has the anticapability for the command by itself, + -bar. If so, it returns right then and + there, compltely ignoring the fact that the user issued that + command to it. If the user doesn't have that anticapability, + then the bot checks to see if the user issued the command over + a channel, and if so, checks to see if the user has the + antichannelcapability for that command, + #baz.-bar. If so, again, he returns right + then and there and doesn't even think about responding to the + bot. If neither of these anticapabilities are present, then + the bot just responds to the user like normal. + + + + + Motivations behind the capabilities system + + A programmer's perspective + + From a programmatical perspective, capabilties are easy to use + and flexible. Any command can check if a user has any + capability, even ones not thought of when the bot was + originally written. Commands/Callbacks can add their own + capabilities – it's as easy as just checking for a + capability and documenting somewhere that a user needs that + capability to do something. + + + + An end-user's perspective + + From an end-user perspective, capabilities remove a lot of the + mystery and esotery of bot control, in addition to giving the + user absolutely finegrained control over what users are + allowed to do with the bot. Additionally, defaults can be set + by the end-user for both individual channels and for the bot + as a whole, letting an end-user set the policy he wants the + bot to follow for users that haven't yet registered in his + user database. + + + It's really a revolution! + + + + Hard-coded supybot capabilities + + There are several default capabilities the bot uses. The most + important of these is the owner capability. + This capability allows the person having it to use + any command. It's best to keep this + capability reserved to people who actually have access to the + shell the bot is running on. + + + There is also the admin capability for + non-owners that are highly trusted to administer the bot + appropriately. They can do things such as change the bot's nick, + globally enable/disable commands, cause the bot to ignore a given + user, set the prefixchar, report bugs, etc. They generally cannot + do administration related to channels, which is reserved for + people with the next capability. + + + People who are to administer channels with the bot should have the + #channel.op capability -- whatever channel they + are to administrate, they should have that channel capability for + op. For example, since I want + inkedmn to be an administrator in + #supybot, I'll give him the + #supybot.op capability. This is in addition to + his admin capability, since the + admin capability doesn't give the person having + it control over channels. #channel.op is used + for such things as giving/receiving ops, kickbanning people, + lobotomizing the bot, ignoring users in the channel, and managing + the channel capabilities. The #channel.op + capability is also basically the equivalent of the owner + capability for capabilities involving #channel + – basically anyone with the #channel.op + capability is considered to have all positive capabilities and no + negative capabilities for #channel. + + + One other globally important capability exists: + trusted. This is a command that basically says + “This user can be trusted not to try and crash the + bot.” It allows users to call commands like + Math.icalc, which potentially could cause the + bot to begin a calculation that could potentially never return (a + calculation like 10**10**10**10). Another command that requires + the trusted capability is Utilties.re, which + (due to the regular expression implementation in Python (and any + other language that uses NFA regular expressions, like Perl or + Ruby or Lua or …) which can allow a regular expression to + take exponential time to process). Consider what would happen if + the someone gave the bot the command re [strjoin "" s/./ + [dict go] /] [dict go]. + + +
+ +