mirror of https://github.com/Mikaela/Limnoria.git
312 lines
14 KiB
Plaintext
312 lines
14 KiB
Plaintext
<!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>
|
|
</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>get</botcommand>,
|
|
<botcommand>set</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
|
|
– 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>
|
|
<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
|
|
</ircsession>
|
|
<para>
|
|
These are all the configuration values you can set which
|
|
are under the base <registrygroup>supybot</registrygroup>
|
|
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.
|
|
</para>
|
|
<para>
|
|
Now, to see all of the available configuration groups
|
|
under the base <registrygroup>supybot</registrygroup>
|
|
group, we simply use the <flag>--groups</flag> flag to
|
|
<botcommand>config list</botcommand>:
|
|
</para>
|
|
<ircsession>
|
|
<jemfinch|lambda> @config list --groups supybot
|
|
<supybot> jemfinch|lambda: commands, databases, directories, drivers,
|
|
log, plugins, replies, and reply
|
|
</ircsession>
|
|
<para>
|
|
These are all the subgroups of
|
|
<registrygroup>supybot</registrygroup>. Again, the full
|
|
name of these would have “supybot.” prepended
|
|
to them. So really, we have
|
|
<registrygroup>supybot.commands</registrygroup>,
|
|
<registrygroup>supybot.databases</registrygroup>, etc.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</note>
|
|
</sect3>
|
|
<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.prefixChars</registrygroup>
|
|
configuration variable is all about, we'd do this:
|
|
</para>
|
|
<ircsession>
|
|
<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.
|
|
</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>
|
|
<jemfinch|lambda> @config supybot.prefixChars
|
|
<supybot> jemfinch|lambda: '@'
|
|
</ircsession>
|
|
<para>
|
|
To set this value, just stick an extra argument after
|
|
the name:
|
|
</para>
|
|
<ircsession>
|
|
<jemfinch|lambda> @config supybot.prefixChars @$
|
|
<supybot> jemfinch|lambda: The operation succeeded.
|
|
</ircsession>
|
|
<para>
|
|
Now, check this out:
|
|
</para>
|
|
<ircsession>
|
|
<jemfinch|lambda> $config supybot.prefixChars
|
|
<supybot> 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>
|
|
<jemfinch|lambda> $config supybot.prefixChars @
|
|
<supybot> jemfinch|lambda: The operation succeeded.
|
|
<jemfinch|lambda> $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>
|
|
<jemfinch|lambda> @config default supybot.prefixChars
|
|
<supybot> jemfinch|lambda: ''
|
|
</ircsession>
|
|
<para>
|
|
Thus, to reset a configuration variable to its default
|
|
value, you can simply say:
|
|
</para>
|
|
<ircsession>
|
|
<jemfinch|lambda> @config supybot.prefixChars [config default
|
|
supybot.prefixChars]
|
|
<supybot> jemfinch|lambda: The operation succeeded.
|
|
<jemfinch|lambda> @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>
|
|
<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
|
|
</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>
|
|
</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>
|
|
|
|
|