Limnoria/docs/CONFIGURATION

So you've got your Supybot up and running and there are some things
you don't like about it.  Fortunately for you, chances are that these
things are configurable, and this document is here to tell you how to
configure them.

Configuration of Supybot is handled via the Config plugin, which
controls runtime access to Supybot's registry (the configuration file
generated by the supybot-wizard program you ran).  The Config plugin
provides a way to get or set variables, to list the available
variables, and even to get help for certain variables.  Take a moment
now to read the help for each of those commands: config, list, and
help.  If you don't know how to get help on those commands, go ahead
and read our GETTING_STARTED document before this one.

Now, if you're used to the Windows registry, don't worry, Supybot's
registry is completely different.  For one, it's completely plain
text.  There's no binary database sensitive to corruption, it's not
necessary to use another program to edit it -- all you need is a
simple text editor.  But there is at least one good idea in Windows'
registry: hierarchical configuration.  Supybot's configuration
variables are organized in a hierarchy: variables having to do with
the way Supybot makes replies all start with supybot.reply; variables
having to do with the way a plugin works all start with
supybot.plugins.Plugin (where Plugin is the name of the plugin in
question).  This hierarchy is nice because it means the user isn't
inundated with hundreds of unrelated and unsorted configuration
variables.

Some of the more important configuration values are located directly
under the base group, supybot.  Things like the bot's nick, its ident,
etc.  Along with these config values are a few subgroups that contain
other values.  Some of the more prominent subgroups are: plugins
(where all the plugin-specific configuration is held), reply (where
variables affecting the way a Supybot makes its replies resides),
replies (where all the specific standard replies are kept), and
directories (where all the directories a Supybot uses are defined).
There are other subgroups as well, but these are the ones we'll use in
our example.

Using the Config plugin, you can list the values in a subgroup and get
or set any of the values anywhere in the configuration hierarchy.  For
example, let's say you wanted to see what configuration values were
under the "supybot" (the base group) hierarchy.  You would simply
issue this command:

<jemfinch|lambda> @config list supybot
<supybot> jemfinch|lambda: nick, ident, user, server,
	  password, channels, prefixChars, defaultCapabilities,
	  defaultAllow, defaultIgnore, humanTimestampFormat,
	  externalIP, pipeSyntax,
	  followIdentificationThroughNickChanges, alwaysJoinOnInvite,
	  showSimpleSyntax, maxHistoryLength, nickmods, throttleTime,
	  snarfThrottle, threadAllCommands, pingServer, pingInterval,
	  upkeepInterval, flush, httpPeekSize, and
	  defaultSocketTimeout

These are all the configuration values you can set which are under the
base "supybot" group.  Actually, their full names would each have a
"supybot." appended on to the front of them, but it is omitted in the
listing in order to shorten the output.

Now, to see all of the available configuration groups under the base
"supybot" group, we simply use the "--groups" flag to config list:

<jemfinch|lambda> @config list --groups supybot
<supybot> jemfinch|lambda: commands, databases,
	  directories, drivers, log, plugins, replies, and reply

These are all the subgroups of "supybot".  Again, the full name of
these would have "supybot." prepended to them.  So really, we have
supybot.commands, supybot.databases, etc.

Note: an item can show up in both lists if it is a group that itself
has a value.  For example, all plugins fall under this category, as
their value is a boolean value determining whether or not that plugin
is to be loaded when the bot is started.  

One last listing example, and then we'll start actually reading and
modifying the configuration values.  It's important to know that when
you provide the group argument to config list that you must always
provide the full name of the group.  For example, "config list
commands" would be incorrect, even though we see "commands" in the
listing above.  Remember, we just shorten the names by the group we're
listing so we can fit more such names in a single message. In this
case, that would be "supybot", so to list everything in the commands
subgroup of supybot, we do:

<jemfinch|lambda> @config list supybot.commands
<supybot> jemfinch|lambda: defaultPlugins

Okay, now that you've used the Config plugin to list configuration
variables, it's time that we start looking at individual variables and
their values.

The first (and perhaps most important) thing you should know about
each configuration variable is that they all have an associated help
string to tell you what they represent.  So the first command we'll
cover is "config help".  To see the help string for any value or
group, simply use the "config help" command.  For example, to see what
this "supybot.prefixChars" configuration variable is all about, we'd
do this:

<jemfinch|lambda> @config help supybot.prefixChars
<supybot> jemfinch|lambda: Determines what prefix
	  characters the bot will reply to. A prefix character is a
	  single character that the bot will use to determine what
	  messages are addressed to it; when there are no prefix
	  characters set, it just uses its nick.

Pretty simple, eh?

Now, if you're curious what the current value of a configuration
variable is, you'll use the "config" command with one argument, the
name of the variable you want to see the value of:

<jemfinch|lambda> @config supybot.prefixChars
<supybot> jemfinch|lambda: '@'

To set this value, just stick an extra argument after the name:

<jemfinch|lambda> @config supybot.prefixChars @$
<supybot> jemfinch|lambda: The operation succeeded.

Now, check this out:

<jemfinch|lambda> $config supybot.prefixChars
<supybot> jemfinch|lambda: '@$'

Note that we used $ as our prefix character, and that the value of the
configuration variable changed.  If I were to use the "flush" command
now, this change would be flushed to the registry file on disk (this
would also happen if I made the bot quit, or pressed Ctrl-C in the
terminal the bot was running in).  Instead, I'll revert the change:

<jemfinch|lambda> $config supybot.prefixChars @
<supybot> jemfinch|lambda: The operation succeeded.
<jemfinch|lambda> $note that this makes no response.

If you're ever curious what the default for a given configuration
variable is, use the "config default" command:

<jemfinch|lambda> @config default supybot.prefixChars
<supybot> jemfinch|lambda: ''

Thus, to reset a configuration variable to its default value, you can
simply say:

<jemfinch|lambda> @config supybot.prefixChars [config default
		  supybot.prefixChars]
<supybot> jemfinch|lambda: The operation succeeded.
<jemfinch|lambda> @note that this does nothing

Simple, eh?

Now, let's say you want to find all configuration variables that might
be even remotely related to opping.  For that, you'll want the "config
search" command.  Check this out:

<jemfinch|lambda> @config search op
<supybot> jemfinch|lambda:
	  supybot.plugins.Enforcer.autoOp,
	  supybot.plugins.Enforcer.autoOp.#supybot,
	  supybot.plugins.Enforcer.autoHalfop,
	  supybot.plugins.Enforcer.cycleToGetOps, supybot.plugins.Topic,
	  supybot.plugins.Topic.separator, and
	  supybot.plugins.Relay.topicSync

Sure, it showed up all the topic-related stuff in there, but it also
showed you all the op-related stuff, too.  Do note, however, that you
can only see configuration variables for plugins that you have loaded
or that you loaded in the past; if you've never loaded a plugin,
there's no way for the bot to know what configuration variables it
registers.

Some people might like editing their registry file directly rather
than manipulating all these things through the bot.  For those people,
we offer the "config reload" command, which reloads both registry
configuration and user/channel/ignore database configuration.  Just
edit the interesting files and then give the bot the "config reload"
command and it'll work as expected.  Do note, however, that Supybot
flushes his configuration files and databases to disk every hour or
so, and if this happens after you've edited your configuration files
but before you reload your changes, you could lose the changes you
made.  To prevent this, set the supybot.flush value to Off, and no
automatic flushing will occur.

Many configuration variables can be specific to individual channels.
The Config plugin provides an easy way to configure something for a
specific channel; for instance, in order to set the prefixChar for a
specific channel, do this in that channel:

config channel supybot.prefixChars !

That'll set the prefixChar in the channel that message is sent in to
!.  Voila, channel-specific values!

Anyway, that's about it for configuration.  Have fun, and enjoy your
configurable bot!