NAME
    Bot::CPAN - provides CPAN services via IRC

SYNOPSIS
      use Bot::CPAN;

      my $bot = Bot::CPAN->new(
          channels => ['#cpan'],
          server => 'grou.ch',
          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,
      );
      $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 channel of new uploads to the CPAN.

METHODS
    * new
        This constructor returns a Bot::CPAN object, and is inherited from
        Bot::BasicBot. It will accept named parameters for: channels,
        server, port, nick, alt_nicks, username, name, ignore_list, store,
        and log. Bot::CPAN extends the Bot::BasicBot constructor to accept
        the following named parameters: news_server, group,
        reload_indices_interval, and inform_channel_of_new_uploads.

    * run
        Fires up the bot.

COMMANDS
        * author
            retrieves the author of a module

        * botsnack
            gives the bot a snack

        * description
            retrieves the description of a module

        * details
            retrieves full details of a module

        * distributions
            retrieves all of the distributions by an author

        * help
            provides instruction on how to use this bot

        * language
            retrieves the language of a module

        * 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

        * recent
            shows last ten distributions uploaded to the CPAN

        * 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

ATTRIBUTES
        * :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.

        * :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.

        * :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.

        * :Help
            Defines the help message for this command, which will be
            available via: /msg bot help <command>.

        * :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.

CAVEATS
            At the moment you'll need to patch BasicBot.pm if you expect
            Bot::CPAN to operate normally. The patch corrects a few minor
            errors in BasicBot.pm.

            Additionally, you'll also need to patch POE::Component::IRC in
            order to get the prioritized messaging (which is required to
            prevent blocking during sending back lots of data to users).

            The patches have been sent to the upstream authors. The patches
            can be found in etc/.

            Also, 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::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 respond to via proxy.

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(). It's first argument should be the
            event hashref and the other argument is whatever you want to
            return to the user.

BUGS
            If you happen to find one please email me at afoxson@pobox.com.
            Thank you.

TODO
              - Write actual tests.
              - Add support for 'fetch', 'readme', 'bugs', 'lastupdate', and 'whois'.
              - Prepare for non-developer release

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
            * perl
            * CPANPLUS
            * POE
            * POE::Component::IRC
            * Bot::BasicBot
            * Net::NNTP
            * Mail::Internet
            * Attribute::Handlers

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

            Many thanks to gilc@#perl@magnet for spending time on
            #cpan@magnet beta testing.

