modules/bot/README.txt

// $Id: README.txt,v 1.5 2006/11/13 03:25:57 morbus Exp $

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

 * Introduction
 * Installation
 * IRC API Hooks
 * Cache Warning
 * Design Decisions


INTRODUCTION
------------

Current Maintainer: Morbus Iff <morbus@disobey.com>

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 and configure 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.


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.

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_drupal.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:
               Drupal URLs, dns, karma.

  <Morbus>     bot_module: help Drupal URLs

  <bot_module> Displays the title of drupal.org URLs ...


CACHE WARNING
-------------

Since the IRC bot runs forever, some of Drupal's internal caching mechanisms
(such as variable_get) actually flummox regular operation. We are still working
on workarounds for these (normally desired) features.


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.
1	// $Id: README.txt,v 1.5 2006/11/13 03:25:57 morbus Exp $
2
3	CONTENTS OF THIS FILE
4	---------------------
5
6	* Introduction
7	* Installation
8	* IRC API Hooks
9	* Cache Warning
10	* Design Decisions
11
12
13	INTRODUCTION
14	------------
15
16	Current Maintainer: Morbus Iff <morbus@disobey.com>
17
18	Druplicon is an IRC bot that has been servicing #drupal, #drupal-support,
19	and many other IRC channels since 2005, proving itself an invaluable resource.
20	Originally a Perl Bot::BasicBot::Pluggable application coded by Morbus Iff,
21	he always wanted to make the official #drupal bot an actual Drupal module.
22
23	This is the fruit of these labors. Whilst the needs of Druplicon are driving
24	the future and design of the module, this is intended as a generic framework
25	for IRC bots within Drupal, and usage outside of Druplicon is encouraged.
26
27
28	INSTALLATION
29	------------
30
31	The bot.module is not like other Drupal modules and requires a bit more
32	effort than normal to get going. Unlike a regular Drupal page load, an
33	IRC bot has to run forever and, for reasons best explained elsewhere, this
34	entails running the bot through a shell NOT through web browser access.
35
36	1. This module REQUIRES Net_SmartIRC, a PHP class available from PEAR.
37	In most cases, you can simply run "pear install Net_SmartIRC".
38
39	2. Copy this bot/ directory to your sites/SITENAME/modules directory.
40
41	3. Enable the module and configure admin/settings/bot.
42
43	4. Inside the bot/ directory is a bot_start.php script which is a wrapper
44	around Drupal and the IRC network libraries. To run this script, you'll
45	need to open up a shell to that directory and use the following command:
46
47	php bot_start.php --root /path/to/drupal/root --url http://www.example.com
48
49	--root refers to the full path to your Drupal installation directory
50	and allows you to execute bot_start.php without moving it to the root
51	directory. --url is required (and is equivalent to Drupal's base URL)
52	to trick Drupal into thinking that it is being run as through a web
53	browser. It sets HTTP_HOST and PHP_SELF, as required by Drupal.
54
55	5. Your bot is now started and is trying to connect.
56
57
58	IRC API HOOKS
59	-------------
60
61	The following message types are supported by Net_SmartIRC:
62
63	UNKNOWN CHANNEL QUERY CTCP NOTICE WHO
64	JOIN INVITE ACTION TOPICCHANGE NICKCHANGE KICK
65	QUIT LOGIN INFO LIST NAME MOTD
66	MODECHANGE PART ERROR BANLIST TOPIC NONRELEVANT
67	WHOIS WHOWAS USERMODE CHANNELMODE CTCP_REQUEST CTCP_REPLY
68
69	A module may create a function in the form of:
70
71	MODULENAME_irc_msg_MESSAGETYPE
72
73	such that a module named "bot_example" could respond or act upon all channel
74	messages with a function called bot_example_irc_msg_channel(). Passed to
75	this function is $data, an object reference that contains the message, who
76	said it, in what channel, and more.
77
78	Modules can respond to the user or channel with bot_message($to, $message),
79	where $to is either a channel name ("#drupal") or user ("Morbus Iff"). Other
80	IRC actions are demonstrated in the modules shipped with this package. In a
81	worse case scenario (ie., there's no helper function in bot.module that will
82	accomplish your desired tasks), you can use "global $irc;" to get the actual
83	Net_SmartIRC object that represents the IRC connection. Under the most ideal
84	conditions, you'd contribute back a patch to bot.module that'd let you
85	accomplish your needs without using the $irc global.
86
87	In addition to the actual utility of your module, you also should add a
88	few lines describing how to use your module. This is done via Drupal's
89	hook_help(), and the use of two special strings:
90
91	irc:features
92	Returns an array of feature names your modules provides.
93
94	irc:features#FEATURE_NAME
95	Returns an explanation of a specific feature of your module.
96
97	FEATURE_NAME will be lowercased, trimmed of whitespace, and anything not a
98	letter or number will be turned into an underscore. For an example in code,
99	take a look at the shipped bot_drupal.module. This information is provided
100	by the bot under the following conditions:
101
102	<Morbus> bot_module: help
103
104	<bot_module> Detailed information is available by asking for
105	"help <feature>" where <feature> is one of:
106	Drupal URLs, dns, karma.
107
108	<Morbus> bot_module: help Drupal URLs
109
110	<bot_module> Displays the title of drupal.org URLs ...
111
112
113	CACHE WARNING
114	-------------
115
116	Since the IRC bot runs forever, some of Drupal's internal caching mechanisms
117	(such as variable_get) actually flummox regular operation. We are still working
118	on workarounds for these (normally desired) features.
119
120
121	DESIGN DECISIONS
122	----------------
123
124	* We do not enforce command prefixes such as !.
125
126	* We do not enforce direct addressing like "botname: <command>".
127
128	Since the entire raw IRC message is passed off to each module, you are more
129	than welcome to enforce either of the above in your own code. Note that you
130	WILL have to insure that "botname: <command>" and simply "<command>" both do
131	as you'd expect - we do not remove "botname:" from the start of messages (and
132	thus a simple test of "^command$" will fail if the bot is addressed). Most
133	of our shipped modules cater to these two possibilities.
134
135	This is an IRC bot... in PHP. PHP is not especially awesome with regards to
136	memory management, and it certainly wasn't intended to run a script for any
137	respectable period of time (like, say, longer than the default 30 seconds).
138	Likewise, there's no way to uninclude a file, so any change to the loaded
139	modules (either codewise or enabled/disabled) will require the bot to be
140	restarted entirely.
141
142	Love the limitations, and craziness, of this project.