mirror of
https://github.com/Mikaela/Limnoria.git
synced 2024-12-21 02:02:53 +01:00
144 lines
7.0 KiB
Plaintext
144 lines
7.0 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
|
|
|
|
Speaking of the load command, that's the command you'll use to load
|
|
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 help for the configuration variable
|
|
"supybot.defaultCapabilities". Last I checked, it'll overflow into a
|
|
second chunk. The command you'll need to do this is "config help
|
|
supybot.defaultCapabilities".
|
|
|
|
Enjoy using Supybot!
|
|
|
|
|
|
###
|
|
# Addenda
|
|
###
|
|
Local installs: See this forum post: http://tinyurl.com/2tb37
|
|
|
|
The Registry: The Supybot registry is somewhat similar to Window's
|
|
registry in concept, but completely different in implementation.
|
|
It's still a hierarchical representation of configuration data, but
|
|
it's in a completely text-based and easy-to-use/modify format. We
|
|
think it's great :)
|