mirror of
https://github.com/Mikaela/Limnoria.git
synced 2024-11-09 20:39:23 +01:00
298 lines
12 KiB
Plaintext
298 lines
12 KiB
Plaintext
<!DOCTYPE article SYSTEM "supybot.dtd">
|
|
|
|
<article>
|
|
<articleinfo>
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Jeremiah</firstname>
|
|
<surname>Fincher</surname>
|
|
</author>
|
|
<editor>
|
|
<firstname>Daniel</firstname>
|
|
<surname>DiPaolo</surname>
|
|
<contrib>DocBook translator</contrib>
|
|
</editor>
|
|
</authorgroup>
|
|
<title>Getting started with Supybot</title>
|
|
<revhistory>
|
|
<revision>
|
|
<revnumber>0.1</revnumber>
|
|
<date>18 Feb 2004</date>
|
|
<revremark>Initial Docbook translation</revremark>
|
|
</revision>
|
|
</revhistory>
|
|
</articleinfo>
|
|
<sect1>
|
|
<title>Introduction</title>
|
|
<para>
|
|
Ok, so you've decided to try out Supybot. That's great! The more
|
|
people who use Supybot, the more people can submit bugs and help
|
|
us to make it the best IRC bot in the world :)
|
|
</para>
|
|
<para>
|
|
First things first: Supybot <emphasis>requires</emphasis> Python
|
|
2.3. There ain't no getting around it. If you're a Python
|
|
developer, you probably know how superior 2.3 is to previous
|
|
incarnations. If you're not, just think about the difference
|
|
between a bowl of plain vanilla ice cream and a banana split. Or
|
|
something like that. Either way, <emphasis>we're</emphasis>
|
|
Python developers and we like banana splits.
|
|
</para>
|
|
</sect1>
|
|
<sect1>
|
|
<title>Installing the bot and its utilities</title>
|
|
<para>
|
|
So what do you do? First thing you'll want to do is run (with
|
|
root/admin privileges) <application>python setup.py
|
|
install</application>. This will install Supybot globally. If
|
|
you need to install locally for whatever reason, see this <ulink
|
|
url="http://tinyurl.com/2tb37">forum post</ulink> on how to do so.
|
|
You'll then have several new programs installed where Python
|
|
scripts are normally installed on your system
|
|
(<filename>/usr/bin</filename> or
|
|
<filename>/usr/local/bin</filename> are common on UNIX systems;
|
|
<filename>C:\Python23\Scripts</filename> is a common place on
|
|
Windows; and (watch out, this is a long one :))
|
|
<filename>/System/Library/Frameworks/Python.framework/Versions/2.3/bin</filename>
|
|
is a common place on MacOS X.). The two that might be of
|
|
particular interest to you, the new user, are
|
|
<script>supybot</script> and
|
|
<script>supybot-wizard</script> The former
|
|
(<script>supybot</script> is the script to run an actual
|
|
bot; the latter (<script>supybot-wizard</script> is an
|
|
in-depth wizard that provides a nice user interface for creating
|
|
configuration files for your bot. We'd prefer you to the use
|
|
<script>supybot-wizard</script>, but if you're in a
|
|
hurry or don't feel like being asked many questions, just run
|
|
supybot with no arguments and it'll ask you only the questions
|
|
necessary ")to run a bot.
|
|
</para>
|
|
</sect1>
|
|
<sect1>
|
|
<title>Firing up the bot for the first time</title>
|
|
<para>
|
|
So after running either of those two programs, you've got a nice
|
|
registry file handy. If you're not satisfied with your answers
|
|
to any of the questions you were asked, feel free to run the
|
|
program again until you're satisfied with all your answers. Once
|
|
you're satisfied, though, run the
|
|
<script>supybot</script> program with the
|
|
registry file you created as an argument. This will start the
|
|
bot; unless you turned off logging to stdout, you'll see some nice
|
|
log messages describing what the bot is doing at any particular
|
|
moment; it may pause for a significant amount of time after saying
|
|
"Connecting to ..." while the server tries to check its ident.
|
|
</para>
|
|
</sect1>
|
|
<sect1>
|
|
<title>Your first interactions with the bot</title>
|
|
<para>
|
|
Ok, so let's assume your bot connected to the server fine and
|
|
joined the channels you told it to join. For now we'll assume you
|
|
named your bot <nick>supybot</nick> (you probably didn't,
|
|
but it'll make it much clearer in the examples that follow to
|
|
assume that you did). We'll also assume that you told it to join
|
|
<channel>#channel</channel> (a nice generic name for a channel,
|
|
isn't it? :)) So what do you do with this bot that you just made
|
|
to join your channel? Try this in the channel:
|
|
</para>
|
|
<ircsession>
|
|
supybot: list
|
|
</ircsession>
|
|
<para>
|
|
Replacing <nick>supybot</nick> with the actual name you
|
|
picked for your bot, of course. Your bot should reply with a list
|
|
of the plugins he currently has loaded. At least
|
|
<plugin>Admin</plugin>, <plugin>Channel</plugin>,
|
|
<plugin>Config</plugin>, <plugin>Misc</plugin>,
|
|
<plugin>Owner</plugin>, and <plugin>User</plugin> should be
|
|
there; if you used <script>supybot-wizard</script> to
|
|
create your configuration file you may have many more plugins
|
|
loaded. The <botcommand>list</botcommand> command can also be used to
|
|
list the commands in a given plugin:
|
|
</para>
|
|
<ircsession>
|
|
supybot: list Misc
|
|
</ircsession>
|
|
<para>
|
|
Will list all the commands in the <plugin>Misc</plugin> plugin.
|
|
</para>
|
|
<sect2>
|
|
<title>Accessing the bot's online help</title>
|
|
<para>
|
|
If you want to see the help for any command, just use
|
|
the <botcommand>help</botcommand> command:
|
|
</para>
|
|
<ircsession>
|
|
supybot: help help
|
|
supybot: help list
|
|
supybot: help load
|
|
</ircsession>
|
|
</sect2>
|
|
<sect2>
|
|
<title>Dealing with ambiguous commands</title>
|
|
<para>
|
|
Sometimes more than one plugin will have a given command; for
|
|
instance, the <botcommand>list</botcommand> command exists in both
|
|
the <plugin>Misc</plugin> and <plugin>Config</plugin>
|
|
plugins (both loaded by default). <plugin>List</plugin>, in
|
|
this case, defaults to the <plugin>Misc</plugin> plugin, but
|
|
you may want to get the help for the
|
|
<botcommand>list</botcommand>
|
|
command in the <plugin>Config</plugin> plugin. In that
|
|
case, you'll want to give your command like this:
|
|
</para>
|
|
<ircsession>
|
|
supybot: help config list
|
|
</ircsession>
|
|
<para>
|
|
Anytime your bot tells you that a given command is defined in
|
|
several plugins, you'll want to use this syntax
|
|
(<botcommand>plugin command</botcommand>) to disambiguate which
|
|
plugin's command you wish to call. For instance, if you
|
|
wanted to call the <plugin>Config</plugin> plugin's
|
|
<botcommand>list</botcommand> command, then you'd need to say:
|
|
</para>
|
|
<ircsession>
|
|
supybot: config list
|
|
</ircsession>
|
|
<para>
|
|
Rather than just <botcommand>list</botcommand>.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>Loading plugins</title>
|
|
<para>
|
|
Now that you know how to deal with plugins having commands
|
|
with the same name, let's take a look at loading other
|
|
plugins. If you didn't use
|
|
<script>supybot-wizard</script>, though, you might
|
|
do well to try it before playing around with loading plugins
|
|
yourself: each plugin has its own
|
|
<function>configure</function> function that the wizard uses
|
|
to setup the appropriate registry entries if the plugin
|
|
requires any.
|
|
</para>
|
|
<sect3>
|
|
<title>Identifying yourself as the bot owner</title>
|
|
<para>
|
|
Now, if you do want to play around with loading plugins,
|
|
you're going to need to have the
|
|
<capability>owner</capability>
|
|
capability. If you ran the wizard, then chances are you
|
|
already added an owner user for yourself. If not,
|
|
however, you can add one via the handy-dandy
|
|
<script>supybot-adduser</script> script. You'll
|
|
want to run it while the bot is not running (otherwise it
|
|
could overwrite
|
|
<script>supybot-adduser</script>'s changes to
|
|
your user database before you get a chance to reload
|
|
them). Just follow the prompts, and when it asks if you
|
|
want to give the user any capabilities, say yes and then
|
|
give yourself the <capability>owner</capability> capability
|
|
(without the quotes), restart the bot and you'll be ready
|
|
to load some plugins!
|
|
</para>
|
|
<para>
|
|
Now, in order for the bot to recognize you as your owner
|
|
user, you'll have to identify with the bot. Open up a
|
|
query window in your irc client (/query should do it; if
|
|
not, just know that you can't identify in a channel
|
|
because it requires sending your password to the bot).
|
|
Then type this:
|
|
</para>
|
|
<ircsession>
|
|
help identify
|
|
</ircsession>
|
|
<para>
|
|
And follow the instructions; the command you send will
|
|
probably look like this, with your owner user and password
|
|
replaced:
|
|
</para>
|
|
<ircsession>
|
|
identify myowneruser myuserpassword
|
|
</ircsession>
|
|
<para>
|
|
The bot will tell you that “The operation
|
|
succeeded” if you got the right name and password.
|
|
Now that you're identified, you can do anything that
|
|
requires any privilege: that includes all the commands in
|
|
the <plugin>Owner</plugin> and <plugin>Admin</plugin>
|
|
plugins, which you may want to take a look at (using the
|
|
<botcommand>list</botcommand> and
|
|
<botcommand>help</botcommand>
|
|
commands, of course). One command in particular that you
|
|
might want to use (it's from the <plugin>User</plugin>
|
|
plugin) is the <botcommand>addhostmask</botcommand> command: it
|
|
lets you add a hostmask to your user record so the bot
|
|
recognizes you by your hostmask instead of requiring you
|
|
to always identify with it before it recognizes you. Use
|
|
the <botcommand>help</botcommand> command to see how this
|
|
command works. Here's how I often use it:
|
|
</para>
|
|
<ircsession>
|
|
addhostmask myuser [hostmask] mypassword
|
|
</ircsession>
|
|
<para>
|
|
You may not have seen that "[hostmask]" syntax before.
|
|
Supybot allows nested commands, which means that any
|
|
command's output can be nested as an argument to another
|
|
command. The hostmask command from the
|
|
<plugin>Misc</plugin> plugin returns the hostmask of a
|
|
given nick, but if given no arguments, it returns the
|
|
hostmask of the person giving the command. So the command
|
|
above adds the hostmask I'm currently using to my user's
|
|
list of recognized hostmasks. I'm only required to give
|
|
<literal>mypassword</literal> if I'm not already
|
|
identified with the bot.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2>
|
|
<title>The <botcommand>more</botcommand> command</title>
|
|
<para>
|
|
Another command you might find yourself needing somewhat often
|
|
is the <botcommand>more</botcommand> command. The IRC protocol
|
|
limits messages to 512 bytes, 60 or so of which must be
|
|
devoted to some bookkeeping. Sometimes, however, Supybot
|
|
wants to send a message that's longer than that. What it
|
|
does, then, is break it into "chunks" and send the first one,
|
|
following it with "(X more messages)" where X is how many more
|
|
chunks there are. To get to these chunks, use the more
|
|
command. One way to try is to look at the listing of
|
|
configuration groups for the bot (more on this in the
|
|
CONFIGURATION document) by giving the command "config list
|
|
supybot". Last I checked, it'll overflow into a second chunk.
|
|
When you invoke this command, you should see output like:
|
|
</para>
|
|
<ircsession>
|
|
<supybot> nick, ident, user, server, password, channels, prefixChars,
|
|
defaultCapabilities, defaultAllow, defaultIgnore,
|
|
humanTimestampFormat, externalIP, bracketSyntax, pipeSyntax,
|
|
followIdentificationThroughNickChanges, alwaysJoinOnInvite,
|
|
showSimpleSyntax, maxHistoryLength, nickmods, throttleTime,
|
|
snarfThrottle, threadAllCommands, pingServer, pingInterval,
|
|
upkeepInterval, flush, (1 more message)
|
|
</ircsession>
|
|
<para>
|
|
Now, to see the rest of the output, simply give the command
|
|
<botcommand>more</botcommand>, and it will show you the rest:
|
|
</para>
|
|
<ircsession>
|
|
<jemfinch> more
|
|
<supybot> httpPeekSize, and defaultSocketTimeout
|
|
</ircsession>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1>
|
|
<title>You're ready!</title>
|
|
<para>
|
|
You should now have a solid foundation for using Supybot. Be sure
|
|
to check the help that is built-in to the bot itself if you have
|
|
any questions, and enjoy using Supybot!
|
|
</para>
|
|
</sect1>
|
|
</article>
|
|
|
|
|