// $Id: README.txt,v 1.6.2.5.2.1 2009/05/08 17:13:16 morbus Exp $

CONTENTS OF THIS FILE

• Introduction
• Installation
• IRC API Hooks
• Design Decisions

INTRODUCTION

Current Maintainer: Morbus Iff [email protected]

Druplicon is an IRC bot that has been servicing #drupal, #drupal-support, and many other IRC channels since 2005, proving itself an invaluable resource. Originally a Perl Bot::BasicBot::Pluggable application coded by Morbus Iff, he always wanted to make the official #drupal bot an actual Drupal module.

This is the fruit of these labors. Whilst the needs of Druplicon are driving the future and design of the module, this is intended as a generic framework for IRC bots within Drupal, and usage outside of Druplicon is encouraged.

INSTALLATION

The bot.module is not like other Drupal modules and requires a bit more effort than normal to get going. Unlike a regular Drupal page load, an IRC bot has to run forever and, for reasons best explained elsewhere, this entails running the bot through a shell, NOT through web browser access.

1. This module REQUIRES Net_SmartIRC, a PHP class available from PEAR. In most cases, you can simply run "pear install Net_SmartIRC".

2. Copy this bot/ directory to your sites/SITENAME/modules directory.

3. Enable the module(s) and then configure them at admin/settings/bot.

4. Inside the bot/ directory is a bot_start.php script which is a wrapper around Drupal and the IRC network libraries. To run this script, you'll need to open up a shell to that directory and use the following command:

   php bot_start.php --root /path/to/drupal/root --url http://www.example.com

   --root refers to the full path to your Drupal installation directory and allows you to execute bot_start.php without moving it to the root directory. --url is required (and is equivalent to Drupal's base URL) to trick Drupal into thinking that it is being run as through a web browser. It sets HTTP_HOST and PHP_SELF, as required by Drupal.

5. Your bot is now started and is trying to connect.

6. Once your bot is connected, you can query it for more information:

   YOUR_BOTNAME: help : Detailed information is available by asking for "help " where is one of: Botagotchi, Drupal URLs, Factoids, Seen. YOUR_BOTNAME: help Seen If someone asks "seen Morbus", the bot will report the last time they've been seen, where, and what their last known message was. Directly addressing the bot will also allow the more complex syntax of "seen Morbus? seen d8uv?", "have you seen sbp?" and similar forms. * can be used as a wildcard, but only with a minimum of three other characters. A maximum of three results are displayed for any one request.

   You can also go to http://www.SITENAME.com/bot/ for a web-based version of all the feature help available through the IRC syntax above.

IRC API HOOKS

The following message types are supported by Net_SmartIRC:

UNKNOWN CHANNEL QUERY CTCP NOTICE WHO JOIN INVITE ACTION TOPICCHANGE NICKCHANGE KICK QUIT LOGIN INFO LIST NAME MOTD MODECHANGE PART ERROR BANLIST TOPIC NONRELEVANT WHOIS WHOWAS USERMODE CHANNELMODE CTCP_REQUEST CTCP_REPLY

A module may create a function in the form of:

MODULENAME_irc_msg_MESSAGETYPE

such that a module named "bot_example" could respond or act upon all channel messages with a function called bot_example_irc_msg_channel(). Passed to this function is $data, an object reference that contains the message, who said it, in what channel, and more.

Modules can respond to the user or channel with bot_message($to, $message), where $to is either a channel name ("#drupal") or user ("Morbus Iff"). Other IRC actions are demonstrated in the modules shipped with this package. In a worse case scenario (ie., there's no helper function in bot.module that will accomplish your desired tasks), you can use "global $irc;" to get the actual Net_SmartIRC object that represents the IRC connection. Under the most ideal conditions, you'd contribute back a patch to bot.module that'd let you accomplish your needs without using the $irc global. Generally speaking, try not to use the $irc global.

There is another hook available called irc_bot_reply_message (such that, in our above example, it'd be bot_example_irc_bot_reply_message()). This function allows you to act whenever the bot sends a message. Primarily, this was added to allow us to log bot responses in bot_log.module. If you use this, be sure NOT to use bot_message() within your implementation, else you'll cause an infinite loop. Another hook, irc_bot_reply_action, does the same for actions.

The final hook of interest is irc_bot_cron, which is run every five minutes. This is very similar to Drupal's own hook_cron, but is intended only for bot-related operations (though, naturally, any hook_cron you add to your own bot plugins will function as expected). irc_bot_cron_faster (one minute) and irc_bot_cron_fastest (15 seconds) are also available.

In addition to the actual utility of your module, you also should add a few lines describing how to use your module. This is done via Drupal's hook_help(), and the use of two special strings:

irc:features Returns an array of feature names your modules provides.

irc:features#FEATURE_NAME Returns an explanation of a specific feature of your module.

FEATURE_NAME will be lowercased, trimmed of whitespace, and anything not a letter or number will be turned into an underscore. For an example in code, take a look at the shipped bot_project.module. This information is provided by the bot under the following conditions: