FANDOM


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.

Ad blocker interference detected!


Wikia is a free-to-use site that makes money from advertising. We have a modified experience for viewers using ad blockers

Wikia is not accessible if you’ve made further modifications. Remove the custom ad blocker rule(s) and the page will load as expected.