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.

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> @capabilities, @commands, @databases, @debug, @directories, @drivers,
            @log, @networks, @nick, @plugins, @protocols, @replies, @reply,
            alwaysJoinOnInvite, channels, defaultIgnore, defaultSocketTimeout,
            externalIP, flush, followIdentificationThroughNickChanges,
            humanTimestampFormat, 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. appended on to the front of 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.

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 the bot was running in). 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.

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?

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.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.maz, 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.

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:

  config channel supybot.reply.whenAddressedBy.chars !

That'll set the prefix chars in the channel that message is sent in to !. Voila, channel-specific values! Also, note that when using the Config plugin's list command, channel-specific values are preceded by a # character to indicate such.

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

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