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(); DESCRIPTION This is a developer release of Bot::CPAN. You should not expect that the API will remain stable, as this is currently a work in progress. Bot::CPAN is a POE based distribution that allows individuals on IRC to query the CPAN in a great number of different ways. Bot::CPAN will also automatically inform the channels of new uploads to the CPAN (by default). 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: Test-Reporter-1.19 by AFOXSON POE-0.25 by RCAPUTO Games-Cryptoquote-1.30 by BOBO 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 - Write more tests. - Defer adding 'bugs' command until CPANPLUS::Backend supports RT's API - I.e., http://rt.cpan.org/NoAuth/last10.txt?Queue=dist - 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 may redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO * the perl manpage * the Attribute::Handlers manpage * the Bot::BasicBot manpage * the CPANPLUS manpage * the Encode manpage * the HTTP::Request manpage * the LWP::UserAgent manpage * the Module::Signature manpage * the POE manpage * the POE::Component::IRC manpage * the Mail::Internet manpage * the Net::NNTP manpage * the URI manpage * the XML::Parser manpage * the XML::RSS::Parser manpage AUTHOR 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..