snufkin / bot Goto Github PK

// $Id: README.txt,v 1.6.2.5.2.1.2.6 2011/01/04 03:53:48 morbus Exp $

CONTENTS OF THIS FILE
---------------------

 * Introduction
 * Installation
 * Starting the Bot
  * Starting the Bot with Drush
  * Starting the Bot with bot_start.php
 * Using the Bot
 * IRC Message Hooks
 * Other IRC 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/config/bot.


STARTING THE BOT
----------------

If you have Drush installed, the following commands are available:

  drush bot-start
  drush bot-status
  drush bot-status-reset
  drush bot-stop

Note, however, that bot.module does use your site's URL in some commands, but
Drush doesn't ever know your URL by default. To ensure proper reporting by the
bot, you'll need to either set your $base_url in settings.php, or tell Drush
your URL with "--uri=http://example.com/". If you don't, the bot will report
all URLs as "http://default/". I prefer setting the URL in settings.php.

To start the bot as a background process, use:

  nohup drush bot-start &

Stopping the bot is accomplished with:

  drush bot-stop

If the bot crashes, is killed, Ctrl-C'd, or otherwise improperly interrupted,
the internal connection status will be stuck in a "connected" state, and
Drush will refuse to "bot-start". You can force a status reset with "drush
bot-status-reset".

IF YOU DO NOT HAVE DRUSH INSTALLED, scripts/bot_start.php is a simple wrapper
around Drupal and the IRC network libraries. To run the bot, move to the
scripts directory and issue the following command:

  php bot_start.php --root /path/to/drupal --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 all
the required Drupal environment variables.

If you want to run the bot as a background process, try:

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


USING THE BOT
-------------

Your bot is now started and is trying to connect.

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

   <Morbus> YOUR_BOTNAME: help

   <YOUR_BOTNAME>: Detailed information is available by asking for
     "help <feature>" where <feature> is one of: Botagotchi, Drupal URLs,
     Factoids, Seen.

   <Morbus> YOUR_BOTNAME: help Seen

   <YOUR_BOTNAME> 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 MESSAGE 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"). 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. This was added primarily
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.


OTHER IRC HOOKS
---------------

Another 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:

  <Morbus> bot_module: help

  <bot_module> Detailed information is available by asking for
    "help <feature>" where <feature> is one of:
    Project URLs, dns, karma.

  <Morbus> bot_module: help Project URLs

  <bot_module> Displays the title of project URLs ...

hook_irc_bot_access() allows you to control whether a particular message
should be delivered to the other bot hooks at all: it receives $irc and $data
for analysis and, should it return FALSE, the incoming message is not sent
to the normal list of IRC Message Hooks as defined above.


DESIGN DECISIONS
----------------

 * We do not enforce command prefixes such as !.

 * We do not enforce direct addressing like "botname: <command>".

Since the entire raw IRC message is passed off to each module, you are more
than welcome to enforce either of the above in your own code. Note that you
WILL have to insure that "botname: <command>" and simply "<command>" both do
as you'd expect - we do not remove "botname:" from the start of messages (and
thus a simple test of "^command$" will fail if the bot is addressed). Most
of our shipped modules cater to these two possibilities.

This is an IRC bot... in PHP. PHP is not especially awesome with regards to
memory management, and it certainly wasn't intended to run a script for any
respectable period of time (like, say, longer than the default 30 seconds).
Likewise, there's no way to uninclude a file, so any change to the loaded
modules (either codewise or enabled/disabled) will require the bot to be
restarted entirely.

Love the limitations, and craziness, of this project.