NAME
    Bot::CPAN - provides CPAN services via IRC

SYNOPSIS
      use Bot::CPAN;

      my $bot = Bot::CPAN->new(
          channels => ['#cpan'],
          servers => ['irc.perl.org', 'irc.freenode.net'],
          port => 6667,
          nick => 'cpantest',
          alt_nicks => ['cpantest2', 'cpantest3'],
          username => 'cpantest',
          name => 'cpantest',
          nickserv_password => 'top_secret_password',
          ignore_list => [qw(purl)],
          news_server => 'nntp.perl.org',
          group => 'perl.cpan.testers',
          reload_indices_interval => 300,
          inform_channel_of_new_uploads => 60,
          inform_channel_of_new_ratings => 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, and new ratings of CPAN distributions.

IRC EXAMPLES
      cpan: recent
      cpan: top10
      cpan: id_name for FOX
      cpan: mod_desc for Test::Reporter
      cpan: dist_version for Bot-CPAN

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,
        inform_channel_of_new_ratings, debug, search_max_results,
        nickserv_password, 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.

    * inform_channel_of_new_ratings
        Number of seconds between checks for new CPAN ratings.

    * name
        The name that the bot will identify itself as.

    * nickserv_password
        Password for IRC networks that use NICKSERV.

    * 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.
        (semi-deprecated)

    * 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
    * botsnack
        gives the bot a snack

    * config
        Shows the bot's configuration (admin only)

    * help
        provides instruction on how to use this bot

    * proxy
        proxies an emote (admin only)

    * recent
        shows last ten distributions uploaded to the CPAN

    * status
        retrieves the status of the bot

    * top10
        top 10 contributors to CPAN

    * id_dists
        shows all distributions of an author

    * id_email
        retrieves an email from a PAUSE ID

    * id_name
        retrieves a name from a PAUSE ID

    * mod_chapter
        retrieves the chapter of a module

    * mod_desc
        retrieves the description of a module

    * mod_dist
        retrieves the distribution of a module

    * mod_docurl
        retrieves the documentation URL of a module

    * mod_dslip
        retrieves the DSLIP of a module

    * mod_id
        retrieves the PAUSE ID of a module

    * mod_language
        retrieves the language of a module

    * mod_license
        retrieves the license of a module

    * mod_rturl
        retrieves the RT URL of a module

    * mod_stage
        retrieves the stage of a module

    * mod_search
        search for a module

    * mod_support
        retrieves the support level of a module

    * mod_style
        retrieves the style of a module

    * mod_version
        retrieves the version of a module

    * dist_chapter
        lists the chapter of a distribution

    * dist_date
        retrieves the release date of a distribution

    * dist_desc
        retrieves description of a distribution

    * dist_dlurl
        retrieves the download URL of a distribution

    * dist_filename
        retrieves the filename of a distribution

    * dist_id
        retrieves PAUSE ID of a distribution

    * dist_mods
        lists all modules in a distribution

    * dist_path
        retrieves the path to a distribution

    * dist_ratings
        retrives ratings of a distribution

    * dist_search
        earch for a distribution

    * dist_size
        retrieves the size of a distribution

    * dist_tests
        shows tests results for a distribution

    * dist_url
        retrieves URL of a distribution

    * dist_version
        retrieves the version of a distribution

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
    reindexing is set to get indexes directly from ftp.funet.fi. Even then,
    those indices are only updated on the funet end about once an hour or
    so.

    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. Or, better yet, report it on RT.

TODO
      - Add support for "throttling" (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
      - Consider re-adding 'modulelist'
      - Consider re-adding 'details'
      - Consider re-supporting search_max_results
      - Improve 'recent' so it has a full recent list on connect
      - Improve memory profile
      - Investigate forking reindexing and checking for new uploads/ratings

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
    * HTTP::Request
    * XML::Parser
    * URI
    * LWP::UserAgent
    * Mail::Internet
    * Math::Round
    * Net::NNTP
    * POE
    * Statistics::Descriptive
    * XML::RSS::Parser
    * POE::Component::IRC
    * Text::Wrap
    * Error
    * Class::Phrasebook
    * Attribute::Handlers
    * Storable
    * CPAN::DistnameInfo
    * Compress::Zlib
    * File::Listing
    * Sort::Versions
    * Encode
    * Config::Auto
    * Getopt::Long

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.

