Join GitHub today
GitHub is home to over 20 million developers working together to host and review code, manage projects, and build software together.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
SYNOPSIS Madcow is an extensible IRC/SILC/AIM bot written in Python. It is fully customizable and has a simple API for creating modules that extend its functionality. Madocw ships with modules that emulate classic Infobot behavior and much more. BASIC USAGE Copy madcow.ini-sample to madcow.ini, edit options, and run: $ ./madcow.py In IRC, message the bot with 'help' to see a list of commands. To trigger him publicly, most commands require that you address the bot, for example: 11:37 <cj_> madcow: wiki dinosaurs 11:37 <madcow> Dinosaur - Dinosaurs were the dominant vertebrate animals of terrestrial ecosystems for over 160 million years, from the late Triassic period to the end of the Cretaceous period, when most of them became extinct in the CretaceousTertiary extinction event. Note: by default, madcow runs as a commandline tool. Change the protocol to irc in madcow.ini (and edit the connection options in [irc]) to connect to IRC. AUTO-OPS / ADMIN In madcow.ini, set owner name to your IRC nick. Message bot with 'admin register <password>'. This will register you as an admin. Other users may now register, and you can give them auto-op flag with /msg madcow admin chflag <user> +o. You can also set the default flags in madcow.ini to give any user that registers auto-ops. If you wish to batch-add users for auto-op access without them registering, edit data/db-madcow-passwd and add a line for each user: nick:*:o Note they will not be able to login in this case. REQUIREMENTS * python 2.4 or higher Madcow can use a variety of protocol formats. Depending on which you choose, you may need a third-party library to handle the protocol. IRC - no modules needed SILC - pysilc (http://cheeseshop.python.org/pypi/pysilc/0.4) AIM - no modules needed Madcow also comes with a suite of plugins that provide functionality. Most of these use the core Python library, however a few need third-party libraries. If a plugin does not have the required components it will be disabled at runtime. You can find a description of each plugin in madcow.ini-sample urban.py: requires SOAPpy memebot.py: requeires sqlobject, pysqlite or MySQLdb WEB FRONTEND FOR MEMEBOT The builtin module memebot.py will track URLs posted to various channels. If you wish, you can enable a web frontend to display these links. An example can be found here: http://memebot.gruntle.org/ Please see README.django for full instructions on enabling this. ADVANCED USAGE By default, the bot will use IRC. If you wish to use SILC or AIM, uncomment the appropriate line in madcow.ini. You can also specify a config file to use on the command line (./madcow.py --help for full list of options). If you use this script to run multiple bots, you may wish to change the "dbNamespace" directive in config. This will keep your database files separate for each bot. If you do not change this, they will share the same data. If you wish to test the bots behavior before deploying, run: $ ./madcow.py -p cli NOTE: When deployed in a public chat channel (such as IRC or SILC), the bot will only respond to most queries when it is addressed. This consists of appending the bot's given nickname in the commandline. For example: madcow: quote aapl madcow - translate from english to german: this beer is really good If you wish to enable the "grufti response" module, you must copy grufti-responses.txt-sample to grufti-responses.txt. This is a database of hard-coded match/response directives. It will choose a random reply whenever it sees a match. It does not need to be addressed. By default the matchfile comes with a set of Zippy and Simpsons quotes. You can delete these and add your own if you wish, or just symlink the provided response file. See README.grufti for more detail on the syntax and advanced features. WRITING EXTENSIONS In the modules/ dir, copy template.py to your new module. Edit the various options in the MatchObject() class and make the response() function return desired output. See existing modules for example usage. The file must end in .py and exist in the modules subdirectory to load. If you write something cool and want to share, send it to firstname.lastname@example.org. WRITING OUTPUT PLUGINS If you wish to write support for a different protocol, this is done by making a new file with the name of the protocol you wish to support inside the protocols directory, and giving it a class called OutputHandler. It *must* subclass madcow.MadCow. The new class must have a start() method defined and the __init__ method must accept certain parameters. Please see existing protocols for an example. Currently we have: cli.py, irc.py, silc.py and aim.py. If you are developing for a new protocol you may request assistance from me at email@example.com. WRITING PLUGINS THAT RUN PERIODICALLY You can write a module that, instead of being triggered by chatter in channel, is invoked on a schedule. For example, if you want a module that checks a website every 5 minutes for an update then notifies the channel. These go in the 'periodic' directory, and you should use the template.py in that directory. The process() function of the PeriodicEvent class should return a string or None (for no response). LICENSE Copyright (C) 2007 Christopher Jones <firstname.lastname@example.org> This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA CONTRIBUTORS This release has module contributions from the following people: - toast: silcplugin, slutcheck, jinx - twid: woot - killfile: bbcnews Some third-party tools have been included for convenience, such as Mark Pilgrim's RSS parser and Joel Rosdahl's irclib. CONTACT You may reach me by e-mail at email@example.com or AIM as seejayunderscore.