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 <command>.

    * :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 <afoxson@pobox.com>, with patches from Casey West
    <cwest@cpan.org> to support the latest POE versions, Randal Schwartz
    <merlyn@stonehenge.com> to support NNTP retrieval of CPAN uploads (as
    opposed to the old way of doing it via mailbox polling), and Rocco
    Caputo <troc+cpan@pobox.com> 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.

