NAME Bot::CPAN - provides CPAN services via IRC SYNOPSIS use Bot::CPAN; my $bot = Bot::CPAN->new( channels => ['#cpan'], servers => ['grou.ch', 'bullfrog.rhizomatic.net'], port => 6667, nick => 'cpantest', alt_nicks => ['cpantest2', 'cpantest3'], username => 'cpantest', name => 'cpantest', ignore_list => [qw(purl)], news_server => 'nntp.perl.org', group => 'perl.cpan.testers', reload_indices_interval => 300, inform_channel_of_new_uploads => 60, debug => 0, search_max_results => 30, adminhost => qr/Fox!afoxson\@pool-141-158-116-119\.pitt\.east\.verizon\.net/, policy => { # See 'POLICY CONTROL MECHANISM', in the POD, below '#cpan' => { # allow channel 'cpan upload' informs, allow => qr/^POE-/i, # for #cpan, only if it matches ^POE-, deny => qr/.+/, # and deny everything else }, }, ); $bot->run(); # OR, see the 'cpanbot' script for an alternative DESCRIPTION Bot::CPAN is a POE based distribution that allows individuals on IRC to query the CPAN and other perl resources in a great number of different ways. Bot::CPAN will also automatically inform the channels of new uploads to the CPAN. IRC EXAMPLES cpan: version of Test::Reporter cpan: modulelist contains Test::Reporter cpan: tests for Test::Reporter cpan: details on Test::Reporter cpan: path to Test::Reporter cpan: readme from Test::Reporter METHODS * new This constructor returns a Bot::CPAN object, and is inherited from Bot::CPAN::BasicBot. It will accept named parameters for: channels, servers, port, nick, alt_nicks, username, name, ignore_list, store, and log. Bot::CPAN extends the Bot::CPAN::BasicBot constructor to accept the following named parameters: news_server, group, reload_indices_interval, inform_channel_of_new_uploads, debug, search_max_results, policy and adminhost. * run Fires up the bot. CONSTRUCTOR OPTIONS * adminhost Specifies a regular expression that will be matched against userhosts for commands that require administrative access. * alt_nicks Alternate nicks that this bot will be known by. These are not nicks that the bot will try if its main nick is taken, but rather other nicks that the bot will recognize if it is addressed in a public channel as the nick. This is useful for bots that are replacements for other bots...e.g, your bot can answer to the name "infobot: " even though it isn't really. * channels The channels we're going to connect to. * ignore_list The list of irc nicks to ignore public messages from (normally other bots.) Useful for stopping bot cascades. * debug Enable or disable bugging. 1 or 0. * group NNTP group to retrieve articles from. This group should be where the cpan upload emails are sent. * inform_channel_of_new_uploads Number of seconds between checks for new CPAN uploads. * name The name that the bot will identify itself as. * news_server The NNTP server to retrieve articles from. * nick The nick we're going to use. * policy Defines the policy control mechanism. * port The port we're going to use. * reload_indices_interval Number of seconds between reloading of CPAN indices. * search_max_results Maximum numer of results to return via the 'search' command. * servers The servers that the bot should attempt to connect to. One will be chosen at random for every connect, or reconnect. * username The username we'll claim to have at our ip/domain. COMMANDS * author retrieves the author of a module * botsnack gives the bot a snack * config shows the bots configuration details * description retrieves the description of a module * details retrieves full details of a module * distributions retrieves all of the distributions by an author * dlurl retrieves the download url of a module * docurl retrieves the url of a module's documentation * help provides instruction on how to use this bot * language retrieves the language of a module * modulelist determines if a given module is in the Module List * modules retrieves the modules created by a given author * package retrieves the package of a module * path retrieves the full CPAN path of a module * readme sends README for module via DCC CHAT * recent shows last ten distributions uploaded to the CPAN * ratings retrives ratings of a distribution * reviews retrives reviews of a distribution * rt retrieves the RT www path to a module * search returns modules that match a regex * stage retrieves the stage of a module * status retrieves the status of the bot * style retrieves the style of a module * support retrieves the support level of a module * tests retrieves the test results of a module * url retrieves the www path to a module * version retrieves the latest version of a module * whois gets an author's name and email from a CPAN ID * wikiurl retrieves the url of a module's wiki page ATTRIBUTES * :Admin Indicates that this command is an admin command. A user will not be able to execute commands marked with this attribute unless their usermask matches the adminhost regex specified in the constructor. * :Args Indicates the nature of the arguments sent to this command. This attribute takes an argument of either 'required', 'optional', or 'refuse'. The user will then get an error message if they attempt to use a command in a manner inconsistent with its intended use. * :Fork Indicates that this command should be forked off. This should be used only for commands that take a long time to execute (like 'tests'). Essentially, forking off a long running command will prevent the execution from blocking the bot. * :Help Defines the help message for this command, which will be available via: /msg bot help . * :LowPrio Indicates that this command's data should be returned to the user with a low priority. This should be used only for commands that return a lot of discrete chunks of data back to the user (like 'tests'). This will prevent the returning of a lot of data from blocking the bot. * :Private Indicates that this command can be executed via a /msg. This attribute takes an argument of either 'notice', or 'privmsg', indicating that manner in which the data should be returned to the user. * :Public Indicates that this command can be executed publically from within a channel. This attribute takes an argument of either 'notice', or 'privmsg', indicating that manner in which the data should be returned to the user. HOW TO WRITE A NEW COMMAND Simple really. Define a subroutine, in CPAN.pm, and add whatever attributes you'd like to it's signature (see above). You will be passed three arguments, the referrent object, the event hashref, and the command's actual argument. To get data back to the user, simply use $self->print(). Its first argument should be the event hashref and the other argument is whatever you want to return to the user. POLICY CONTROL MECHANISM The policy control mechanism consults the policy hashref specified in the constructor. The policy hashref should contain channel hashrefs. The channel hashref may contain both 'allow', and 'deny' key/value pairs. The values of the keys are regex's which specify which channel 'cpan upload' informs are to be allowed or denied. The search stops at the first match. This is a simplistic and minimal policy control mechanism that is directly based on HOSTS_ACCESS(5) (/etc/hosts.(allow|deny)). A channel 'cpan upload' inform will be allowed when the text of an inform matches the allow regex. Otherwise, a channel 'cpan upload' inform will be denied when the text of an inform matches the deny regex. Otherwise, a channel 'cpan upload' inform will be allowed. If a channel doesn't have a specified policy, all channel 'cpan upload' informs will be allowed. You will be matching against strings that look like the below. Bear this firmly in mind when you create regex's to match them (see 'RATINGS'): Test-Reporter-1.19 (+++++) by AFOXSON POE-0.25 (+++++) by RCAPUTO Games-Cryptoquote-1.30 (++++ ) by BOBO RATINGS An upload inform will look something like: Test-Reporter-1.19 (+++++) by AFOXSON What is up with all of the +'s? The plus signs within the parens represent the distributions average rounded rating from cpanratings.perl.org (aka karma). Possible ratings are 1 through 5. The area between the parens is fixed-width which means if a distribution has an average rounded ratinging of '2' if will be padded with 3 spaces. It used to be that (unknown) would be displayed if the bot cannot connect to the data source, (unrated) would be displayed if the module has yet to receieve any ratings, and (error) would be displayed if something went wrong. However, after some discussion on #perl@MagNET, the karma representation will be omitted unless there is an actual karma rating to display. There were competing "karma represetations" floated on #perl@MagNET, such as "letter-grades", and "descriptive words" but in the end, the incremement style got the popular vote. CAVEATS If you expect the bot to have very recent CPAN data, be sure that CPANPLUS is set to get indexes directly from ftp.funet.fi. Bot::CPAN::BasicBot's alt_nicks doesn't do what you think. It's NOT for specifying alternate nicks to use for connecting to IRC if the one you chose is taken. It's used for specifying nicks that you'd like the bot to also respond for, as if the real nick was addressed. This is a relic from the bundling of Bot::BasicBot. BUGS If you happen to find one please email me at afoxson@pobox.com. Thank you. TODO - Defer adding 'bugs' command until CPANPLUS::Backend supports RT's API - Add support for "pacing" (suggested by Spoon) i.e., if several uploads occur at the same time, pace the reporting of such to a pre-determined number of upload notification per minute COPYRIGHT Copyright (c) 2003 Adam J. Foxson. All rights reserved. Copyright (c) 2003 Casey West. All rights reserved. LICENSE 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. SEE ALSO * perl * Attribute::Handlers * Bot::BasicBot * Config::Auto * CPANPLUS * Encode * Getopt::Long * HTTP::Request * LWP::UserAgent * Module::CPANTS * Module::Signature * POE * POE::Component::IRC * Mail::Internet * Math::Round * Net::NNTP * Statistics::Descriptive * URI * XML::Parser * XML::RSS::Parser AUTHORS Adam J. Foxson , with patches from Casey West to support the latest POE versions, Randal Schwartz to support NNTP retrieval of CPAN uploads (as opposed to the old way of doing it via mailbox polling), and Rocco Caputo that solved early-on blocking issues, and got the prioritized events patch into the P::C::I core. Special thanks goes out to Iain Truskett for diligent testing and the suggestion of many spiffy features.