mirror of
https://github.com/Mikaela/Limnoria.git
synced 2024-11-02 17:29:22 +01:00
317 lines
15 KiB
Plaintext
317 lines
15 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>
|
|
<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
|
|
– 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> @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
|
|
“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.
|
|
</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>
|
|
<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)
|
|
</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.reply.whenAddressedBy.chars
|
|
<supybot> jemfinch|lambda: '@'
|
|
</ircsession>
|
|
<para>
|
|
To set this value, just stick an extra argument after
|
|
the name:
|
|
</para>
|
|
<ircsession>
|
|
<jemfinch|lambda> @config supybot.reply.whenAddressedBy.chars @$
|
|
<supybot> jemfinch|lambda: The operation succeeded.
|
|
</ircsession>
|
|
<para>
|
|
Now, check this out:
|
|
</para>
|
|
<ircsession>
|
|
<jemfinch|lambda> $config supybot.reply.whenAddressedBy.chars
|
|
<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.reply.whenAddressedBy.chars @
|
|
<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.reply.whenAddressedBy.chars
|
|
<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.reply.whenAddressedBy.chars [config default
|
|
supybot.reply.whenAddressedBy.chars]
|
|
<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.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>
|
|
|
|
|