mirror of
https://github.com/Mikaela/Limnoria.git
synced 2024-11-05 02:29:22 +01:00
174 lines
8.3 KiB
Plaintext
174 lines
8.3 KiB
Plaintext
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 :)
|
|
|
|
First things first: Supybot *requires* 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, *We're*
|
|
Python developers and we like banana splits.
|
|
|
|
So what do you do? First thing you'll want to do is run (with
|
|
root/admin privileges) "python setup.py install". This will install
|
|
Supybot globally. If you need to install locally for whatever reason,
|
|
see the addendum near the end of this document. You'll then have
|
|
several new programs installed where Python scripts are normally
|
|
installed on your system (/usr/bin or /usr/local/bin are common on
|
|
UNIX systems; C:\Python23\Scripts is a common place on Windows; and
|
|
(watch out, this is a long one :))
|
|
/System/Library/Frameworks/Python.framework/Versions/2.3/bin is a
|
|
common place on MacOS X.). The two that might be of particular
|
|
interest to you, the new user, are "supybot" and "supybot-wizard".
|
|
The former ("supybot") is the script to run an actual bot; the latter
|
|
("supybot-wizard") 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 supybot-wizard, 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.
|
|
|
|
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 "supybot" 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.
|
|
|
|
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 "supybot" (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 (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:
|
|
|
|
supybot: list
|
|
|
|
Replacing "supybot" 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 Admin, Channel, Config, Misc, Owner, and User
|
|
should be there; if you used supybot-wizard to create your
|
|
configuration file you may have many more plugins loaded. The list
|
|
command can also be used to list the commands in a given plugin:
|
|
|
|
supybot: list Misc
|
|
|
|
Will list all the commands in the Misc plugin. If you want to see the
|
|
help for any command, just use the help command:
|
|
|
|
supybot: help help
|
|
supybot: help list
|
|
supybot: help load
|
|
|
|
Sometimes more than one plugin will have a given command; for
|
|
instance, the "list" command exists in both the Misc and Config
|
|
plugins (both loaded by default). List, in this case, defaults to the
|
|
Misc plugin, but you may want to get the help for the list command in
|
|
the Config plugin. In that case, you'll want to give your command
|
|
like this:
|
|
|
|
supybot: help config list
|
|
|
|
Anytime your bot tells you that a given command is defined in several
|
|
plugins, you'll want to use this syntax ("plugin command") to
|
|
disambiguate which plugin's command you wish to call. For instance,
|
|
if you wanted to call the Config plugin's list command, then you'd
|
|
need to say:
|
|
|
|
supybot: config list
|
|
|
|
Rather than just "list".
|
|
|
|
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 supybot-wizard, though, you might do well to try it before playing
|
|
around with loading plugins yourself: each plugin has its own
|
|
configure function that the wizard uses to setup the appropriate
|
|
registry entries if the plugin requires any.
|
|
|
|
Now, if you do want to play around with loading plugins, you're going
|
|
to need to have the owner 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 supybot-adduser script.
|
|
You'll want to run it while the bot is not running (otherwise it could
|
|
overwrite supybot-adduser'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 "owner" capability (without the quotes), restart the
|
|
bot and you'll be ready to load some plugins!
|
|
|
|
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:
|
|
|
|
help identify
|
|
|
|
And follow the instructions; the command you send will probably look
|
|
like this, with your owner user and password replaced:
|
|
|
|
identify myowneruser myuserpassword
|
|
|
|
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 Owner and Admin plugins, which you may want to take a look at
|
|
(using the list and help commands, of course). One command in
|
|
particular that you might want to use (it's from the User plugin) is
|
|
the addhostmask 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 help
|
|
command to see how this command works. Here's how I often use it:
|
|
|
|
addhostmask myuser [hostmask] mypassword
|
|
|
|
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 Misc
|
|
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
|
|
mypassword if I'm not already identified with the bot.
|
|
|
|
Another command you might find yourself needing somewhat often is the
|
|
"more" 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:
|
|
|
|
<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)
|
|
|
|
Now, to see the rest of the output, simply give the command "more",
|
|
and it will show you the rest:
|
|
|
|
<jemfinch> more
|
|
<supybot> httpPeekSize, and defaultSocketTimeout
|
|
|
|
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!
|
|
|
|
|
|
###
|
|
# Addenda
|
|
###
|
|
Local installs: See this forum post: http://tinyurl.com/2tb37
|