mirror of
https://github.com/Mikaela/Limnoria.git
synced 2024-12-23 11:12:47 +01:00
Add docs/CONFIGURATION
Signed-off-by: James Vega <jamessan@users.sourceforge.net>
This commit is contained in:
James Vega
parent
5fda0df4a9
commit
babb4082d9
191
docs/CONFIGURATION
Normal file
191
docs/CONFIGURATION
Normal file
@ -0,0 +1,191 @@
|
|||||||
|
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 simply, 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 his 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.
|
||||||
Loading…
Reference in New Issue
Block a user