Mikaela/Limnoria
1
0
Fork 0
mirror of https://github.com/Mikaela/Limnoria.git synced 2024-12-23 11:12:47 +01:00
Code Issues Projects Releases Wiki Activity

New DocBook file for the capabilities doc, updated the Makefile

Browse Source 
correspondingly, also fixed a few minor things in the capabilities doc itself.
This commit is contained in:
Daniel DiPaolo 2004-02-19 01:15:04 +00:00
parent bfea2fcc3f
commit 9e51729d9f
3 changed files with 227 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/CAPABILITIES
View File

@ -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

23
docs/DocBook/Makefile
View File

@ -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

205
docs/DocBook/capabilities.sgml Normal file
View File

@ -0,0 +1,205 @@
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<article>
<articleinfo>
<authorgroup>
<author>
<firstname>Jeremiah</firstname>
<surname>Fincher</surname>
</author>
<editor>
<firstname>Daniel</firstname>
<surname>DiPaolo</surname>
<contrib>DocBook translator</contrib>
</editor>
</authorgroup>
<title>Supybot capabilities system explanation</title>
<revhistory>
<revision>
<revnumber>0.1</revnumber>
<date>18 Feb 2004</date>
<revremark>Initial revision</revremark>
</revision>
</revhistory>
</articleinfo>
<sect1>
<title>Introduction</title>
<subtitle>
Supybot's capabilities overview and comparisons to other bots
</subtitle>
<para>
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) &ldquo;what a user can do&rdquo; is set
in one of two ways. On the <emphasis>really</emphasis> simple
bots, each user has a numeric &ldquo;level&rdquo; and commands
check to see if a user has a &ldquo;high enough level&rdquo; to
perform some operation. On bots that are slightly more
complicated, users have a list of &ldquo;flags&rdquo; 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.
</para>
<para>
This bot is different. Every user has a set of
&ldquo;capabilities&rdquo; 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 <varname>o</varname>
flag, are instead able to check if a user has the
<varname>owner</varname> 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.
</para>
</sect1>
<sect1>
<title>What sets supybot's capabilities apart</title>
<para>
If that was all, well, the capability system would be
&ldquo;cool&rdquo;, but not many people would say it was
&ldquo;awesome&rdquo;. But it <emphasis>is</emphasis> 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
&ldquo;anticapability&rdquo; for that command. An anticapability is
a capability that, instead of saying &ldquo;what a user can
do&rdquo;, says what a user <emphasis>cannot</emphasis> do. It's
formed rather simply by adding a dash (&ldquo;-&rdquo;) to the
beginning of a capability; <varname>rot13</varname> is a
capability, and <varname>-rot13</varname> is an anticapability.
Anyway, when a user issues the bot a command, perhaps
<function>calc</function> or <function>help</function> the bot
first checks to make sure the user doesn't have the
<varname>-calc</varname> or the <varname>-help</varname>
capabilities before even considering responding to the user. So
commands can be turned on or off on a <emphasis>per
user</emphasis> basis, offering finegrained control not often (if
at all!) seen in other bots.
</para>
<sect2>
<title>Channel capabilities</title>
<para>
But that's not all! The capabilities system also supports
<emphasis>Channel</emphasis> capabilities, which are
capabilities that only apply to a specific channel; they're of
the form <varname>#channel.capability</varname>. 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 <emphasis>in that
channel</emphasis> 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!
</para>
<para>
So when a user <varname>foo</varname> sends a command
<function>bar</function> to the bot on channel
<varname>#baz</varname>, first the bot checks to see if the
user has the anticapability for the command by itself,
<varname>-bar</varname>. 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,
<varname>#baz.-bar</varname>. 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.
</para>
</sect2>
</sect1>
<sect1>
<title>Motivations behind the capabilities system</title>
<sect2>
<title>A programmer's perspective</title>
<para>
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 &ndash; it's as easy as just checking for a
capability and documenting somewhere that a user needs that
capability to do something.
</para>
</sect2>
<sect2>
<title>An end-user's perspective</title>
<para>
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.
</para>
<para>
It's really a revolution!
</para>
</sect1>
<sect1>
<title>Hard-coded supybot capabilities</title>
<para>
There are several default capabilities the bot uses. The most
important of these is the <varname>owner</varname> capability.
This capability allows the person having it to use
<emphasis>any</emphasis> command. It's best to keep this
capability reserved to people who actually have access to the
shell the bot is running on.
</para>
<para>
There is also the <varname>admin</varname> 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.
</para>
<para>
People who are to administer channels with the bot should have the
<varname>#channel.op</varname> capability -- whatever channel they
are to administrate, they should have that channel capability for
<varname>op</varname>. For example, since I want
<varname>inkedmn</varname> to be an administrator in
<varname>#supybot</varname>, I'll give him the
<varname>#supybot.op</varname> capability. This is in addition to
his <varname>admin</varname> capability, since the
<varname>admin</varname> capability doesn't give the person having
it control over channels. <varname>#channel.op</varname> 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 <varname>#channel.op</varname>
capability is also basically the equivalent of the owner
capability for capabilities involving <varname>#channel</varname>
&ndash; basically anyone with the <varname>#channel.op</varname>
capability is considered to have all positive capabilities and no
negative capabilities for <varname>#channel</varname>.
</para>
<para>
One other globally important capability exists:
<varname>trusted</varname>. This is a command that basically says
&ldquo;This user can be trusted not to try and crash the
bot.&rdquo; It allows users to call commands like
<function>Math.icalc</function>, 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 <function>Utilties.re</function>, 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 &hellip;) which can allow a regular expression to
take exponential time to process). Consider what would happen if
the someone gave the bot the command <literal>re [strjoin "" s/./
[dict go] /] [dict go]</literal>.
</para>
</sect1>
</article>