Limnoria/docs/CONFIGURATION.rst

=============
Configuration
=============

Introduction
------------
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, take a look at the
GETTING_STARTED document.

Configuration Registry
----------------------
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.

Configuration Groups
--------------------
Using the `Config` plugin, you can list 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: @abuse, @capabilities, @commands,
            @databases, @debug, @directories, @drivers, @log, @networks,
            @nick, @plugins, @protocols, @replies, @reply,
            alwaysJoinOnInvite, channels, defaultIgnore,
            defaultSocketTimeout, externalIP, flush,
            followIdentificationThroughNickChanges, ident, pidFile,
            snarfThrottle, upkeepInterval, and user

These are all the configuration groups and values which are under the
base `supybot` group.  Actually, their full names would each have a
'supybot.' prepended to them, but it is omitted in the listing in order
to shorten the output.  The first entries in the output are the groups
(distinguished by the '@' symbol in front of them), and the rest are the
configuration values.  The '@' symbol (like the '#' symbol we'll discuss
later) is simply a visual cue and is not actually part of the name.

Configuration Values
--------------------
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.snarfThrottle` configuration variable is all about, we'd do
this::

  <jemfinch|lambda> @config help supybot.snarfThrottle
  <supybot> jemfinch|lambda: A floating point number of seconds to
            throttle snarfed URLs, in order to prevent loops between two
            bots snarfing the same URLs and having the snarfed URL in
            the output of the snarf message.  (Current value: 10.0)

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.reply.whenAddressedBy.chars
  <supybot> jemfinch|lambda: '@'

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

  <jemfinch|lambda> @config supybot.reply.whenAddressedBy.chars @$
  <supybot> jemfinch|lambda: The operation succeeded.

Now check this out::

  <jemfinch|lambda> $config supybot.reply.whenAddressedBy.chars
  <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 which the bot was running).  Instead, I'll revert the change::

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

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

  <jemfinch|lambda> @config default supybot.reply.whenAddressedBy.chars
  <supybot> jemfinch|lambda: ''

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

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

Simple, eh?

Searching the Registry
----------------------
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|lamda> @config search op
  <supybot> jemfinch|lambda: supybot.plugins.Enforcer.autoOp,
            supybot.plugins.Enforcer.autoHalfop,
            supybot.plugins.Enforcer.takeRevenge.onOps,
            supybot.plugins.Enforcer.cycleToGetOps,
            supybot.plugins.Topic, supybot.plugins.Topic.public,
            supybot.plugins.Topic.separator,
            supybot.plugins.Topic.format,
            supybot.plugins.Topic.recognizeTopiclen,
            supybot.plugins.Topic.default,
            supybot.plugins.Topic.undo.max,
            supybot.plugins.Relay.topicSync

Sure, it showed 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 are currently 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.

Channel-Specific Configuration
------------------------------
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 prefix chars for a
specific channel, do this in that channel::

  <jemfinch|lambda> @config channel supybot.reply.whenAddressedBy.chars !
  <supybot> jemfinch|lambda: The operation succeeded.

That'll set the prefix chars in the channel from which the message was
sent to '!'.  Voila, channel-specific values!  Also, note that when
using the `Config` plugin's ``list`` command, channel-specific values are
preceeded by a '#' character to indicate such (similar to how '@' is
used to indicate a group of values).

Editing the Configuration Values by Hand
----------------------------------------
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 its configuration files and database 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' while editing
the files, and no automatic flushing will occur.