Limnoria/docs/DocBook/configuration.sgml

<!DOCTYPE article SYSTEM "supybot.dtd">

<article>
    <articleinfo>
        <authorgroup>
            <author>
                <firstname>Jeremiah</firstname>
                <surname>Fincher</surname>
            </author>
            <author>
                <firstname>Daniel</firstname>
                <surname>DiPaolo</surname>
            </author>
            <editor>
                <firstname>Daniel</firstname>
                <surname>DiPaolo</surname>
                <contrib>DocBook translator</contrib>
            </editor>
        </authorgroup>
        <title>Supybot configuration system explanation</title>
        <revhistory>
            <revision>
                <revnumber>0.1</revnumber>
                <date>18 Feb 2004</date>
                <revremark>Initial Docbook translation</revremark>
            </revision>
            <revision>
                <revnumber>0.2</revnumber>
                <date>26 Feb 2004</date>
                <revremark>Conversion to Supybot DTD</revremark>
            </revision>
            <revision>
                <revnumber>0.3</revnumber>
                <date>4 Sep 2004</date>
                <revremark>Update Docbook translation</revremark>
            </revision>
        </revhistory>
    </articleinfo>
    <sect1>
        <title>Introduction</title>
        <para>
            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.
        </para>
        <para>
            Configuration of Supybot is handled via the
            <plugin>Config</plugin> plugin, which controls runtime access to
            Supybot's registry (the configuration file generated by the
            <script>supybot-wizard</script> program you ran).  The
            <plugin>Config</plugin> 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: <botcommand>config</botcommand>,
            <botcommand>list</botcommand>, and
            <botcommand>help</botcommand>.  If you don't know how to get help on
            those commands, go ahead and read our
            <filename>GETTING_STARTED</filename> document before this one.
        </para>
    </sect1>
    <sect1>
        <title>Supybot's registry</title>
        <para>
            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
            &ndash; 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
            <registrygroup>supybot.reply</registrygroup>; variables having to
            do with the way a plugin works all start with
            <registrygroup>supybot.plugins.Plugin</registrygroup> (where
            <plugin>Plugin</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.
        </para>
        <para>
            Some of the more important configuration values are located
            directly under the base group,
            <registrygroup>supybot</registrygroup>.  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: <registrygroup>plugins</registrygroup> (where all
            the plugin-specific configuration is held),
            <registrygroup>reply</registrygroup> (where variables affecting
            the way a Supybot makes its replies resides),
            <registrygroup>replies</registrygroup> (where all the specific
            standard replies are kept), and
            <registrygroup>directories</registrygroup> (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.
        </para>
        <sect2>
            <title>Config plugin commands</title>
            <sect3>
                <title>Listing registry contents</title>
                <para>
                    Using the <plugin>Config</plugin> 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 <registrygroup>supybot</registrygroup> (the base
                    group) hierarchy.  You would simply issue this command:
                </para>
                <ircsession>
&lt;jemfinch|lambda&gt; @config list supybot
&lt;supybot&gt; @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
                </ircsession>
                <para>
                    These are all the configuration groups and values which
                    are under the base <registrygroup>supybot</registrygroup>
                    group.  Actually, their full names would each have a
                    &ldquo;supybot.&rdquo; 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.
                </para>
            </sect3>
        <sect2>
            <title>Supybot's registry</title>
            <sect3>
                <title>Dealing with registry values</title>
                <para>
                    Okay, now that you've used the <plugin>Config</plugin>
                    plugin to list configuration variables, it's time that we
                    start looking at individual variables and their values.
                </para>
                <sect4>
                    <title>Built-in help for registry values</title>
                    <para>
                        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 <botcommand>config help</botcommand>.  To see the
                        help string for any value or group, simply use the
                        <botcommand>config help</botcommand> command.  For
                        example, to see what this
                        <registrygroup>supybot.snarfThrottle</registrygroup>
                        configuration variable is all about, we'd do this:
                    </para>
                    <ircsession>
&lt;jemfinch|lambda&gt; @config help supybot.snarfThrottle
&lt;supybot&gt; 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)
                    </ircsession>
                    <para>
                        Pretty simple, eh?
                    </para>
                </sect4>
				<sect4>
				    <title>Getting/setting registry values</title>
					<para>
						Now, if you're curious what the current value of a
						configuration variable is, you'll use the
                        <botcommand>config</botcommand> command with one
                        argument, the name of the variable you want to see the
                        value of:
					</para>
					<ircsession>
&lt;jemfinch|lambda&gt; @config supybot.reply.whenAddressedBy.chars
&lt;supybot&gt; jemfinch|lambda: '@'
					</ircsession>
					<para>
						To set this value, just stick an extra argument after
						the name:
					</para>
					<ircsession>
&lt;jemfinch|lambda&gt; @config supybot.reply.whenAddressedBy.chars @$
&lt;supybot&gt; jemfinch|lambda: The operation succeeded.
					</ircsession>
					<para>
						Now, check this out:
					</para>
					<ircsession>
&lt;jemfinch|lambda&gt; $config supybot.reply.whenAddressedBy.chars
&lt;supybot&gt; jemfinch|lambda: '@$'
					</ircsession>
					<para>
						Note that we used <literal>$</literal> as our prefix
						character, and that the value of the configuration
						variable changed.  If I were to use the
                        <botcommand>flush</botcommand> 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
                        <keycombo>
                            <keycap>Ctrl</keycap>
                            <keycap>C</keycap>
						</keycombo>
                        in the terminal the bot was running in).  Instead,
                        I'll revert the change:
					</para>
					<ircsession>
&lt;jemfinch|lambda&gt; $config supybot.reply.whenAddressedBy.chars @
&lt;supybot&gt; jemfinch|lambda: The operation succeeded.
&lt;jemfinch|lambda&gt; $note that this makes no response.
					</ircsession>
					<para>
						If you're ever curious what the default for a given
                        configuration variable is, use the <botcommand>config
                        default</botcommand> command:
					</para>
					<ircsession>
&lt;jemfinch|lambda&gt; @config default supybot.reply.whenAddressedBy.chars
&lt;supybot&gt; jemfinch|lambda: ''
					</ircsession>
					<para>
						Thus, to reset a configuration variable to its default
						value, you can simply say: 
					</para>
					<ircsession>
&lt;jemfinch|lambda&gt; @config supybot.reply.whenAddressedBy.chars [config default
	supybot.reply.whenAddressedBy.chars]
&lt;supybot&gt; jemfinch|lambda: The operation succeeded.
&lt;jemfinch|lambda&gt; @note that this does nothing
					</ircsession>
					<para>
						Simple, eh?
					</para>
				</sect4>
            </sect3>
            <sect3>
                <title>Searching the registry</title>
                <para>
                    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 <botcommand>config
                    search</botcommand> command.  Check this out:
                </para>
                <ircsession>
&lt;jemfinch|lambda&gt; @config search op
&lt;supybot&gt; 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
                </ircsession>
                <para>
                    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.
                </para>
                <para>
                    Some people might like editing their registry file
                    directly rather than manipulating all these things through
                    the bot.  For those people, we offer the
                    <botcommand>config reload</botcommand> command, which
                    reloads both registry configuration and
                    user/channel/ignore database configuration.  Just edit the
                    interesting files and then give the bot the
                    <botcommand>config reload</botcommand> 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 <registrygroup>supybot.flush</registrygroup> value to
                    <literal>Off</literal>, and no automatic flushing will
                    occur.
                </para>
            </sect3>
            <sect3>
                <title>Channel-specific configuration</title>
                <para>
                    Many configuration variables can be specific to individual
                    channels.  The <plugin>Config</plugin> 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:
                </para>
                <ircsession>
config channel supybot.reply.whenAddressedBy.chars !
                </ircsession>
                <para>
                    That'll set the prefix chars in the channel that message
                    is sent in to <literal>!</literal>.  Voila,
                    channel-specific values!
                </para>
            </sect3>
        </sect2>
	</sect1>
	<sect1>
		<title>All done!</title>
        <para>
            Anyway, that's about it for configuration.  Have fun, and enjoy
            your configurable bot!
        </para>
    </sect1>
</article>