Limnoria/docs/CAPABILITIES

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.

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.

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.

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.

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!