NAME
   Package::Locator - Find a package among CPAN-like repositories

VERSION
   version 0.009

SYNOPSIS
     use Package::Locator;

     # Basic search...
     my $locator = Package::Locator->new();
     my $url = locator->locate( package => 'Test::More' );

     # Search for first within multiple repositories:
     my $repos = [ qw(http://cpan.pair.com http://my.company.com/DPAN) ];
     my $locator = Package::Locator->new( repository_urls => $repos );
     my $url = locator->locate( package => 'Test::More' );

     # Search for first where version >= 0.34:
     my $repos = [ qw(http://cpan.pair.com http://my.company.com/DPAN) ];
     my $locator = Package::Locator->new( repository_urls => $repos );
     my $url = locator->locate( package => 'Test::More' version => 0.34);

     # Search for latest where version  >= 0.34:
     my $repos = [ qw(http://cpan.pair.com http://my.company.com/DPAN) ];
     my $locator = Package::Locator->new( repository_urls => $repos );
     my $url = locator->locate( package => 'Test::More' version => 0.34, latest => 1);

     # Search for specific dist on multiple repositories...:
     my $repos = [ qw(http://cpan.pair.com http://my.company.com/DPAN) ];
     my $locator = Package::Locator->new( repository_urls => $repos );
     my $url = locator->locate( distribution => 'A/AU/AUTHOR/Foo-1.0.tar.gz');

DESCRIPTION
   Package::Locator attempts to answer the question: "Where can I find a
   distribution that will provide this package?" The answer is divined by
   searching the indexes for one or more CPAN-like repositories. If you
   also provide a specific version number, Package::Locator will attempt to
   find a distribution with that version of the package, or higher. You can
   also ask to find the latest version of a package across all the indexes.

   Package::Locator only looks at the index files for each repository, and
   those indexes only contain information about the latest versions of the
   packages within that repository. So Package::Locator is not BackPAN
   magic -- you cannot use it to find precisely which distribution a
   particular package (or file) came from. For that stuff, see "/See Also".

CONSTRUCTOR
 new( %attributes )
   All the attributes listed below can be passed to the constructor, and
   retrieved via accessor methods with the same name. All attributes are
   read-only, and cannot be changed once the object is constructed.

ATTRIBUTES
 repository_urls => [ qw(http://somewhere http://somewhere.else) ]
   An array reference containing the base URLs of the repositories you want
   to search. These are usually CPAN mirrors, but can be any website or
   local directory that is organized in a CPAN-like structure. For each
   request, repositories are searched in the order you specified them here.
   This defaults to http://cpan.perl.org.

 user_agent => $user_agent_obj
   The LWP::UserAgent object that will fetch index files. If you do not
   provide a user agent, then a default one will be constructed for you.

 cache_dir => '/some/directory/path'
   The path (as a string or Path::Class::Dir object) to a directory where
   the index file will be cached. If the directory does not exist, it will
   be created for you. If you do not specify a cache directory, then a
   temporary directory will be used. The temporary directory will be
   deleted when your application terminates.

 force => $boolean
   Causes any cached index files to be removed, thus forcing a new one to
   be downloaded when the object is constructed. This only has effect if
   you specified the "cache_dir" attribute. The default is false.

METHODS
 indexes()
   Returns a list of Package::Locator::Index objects representing the
   indexes of each of the repositories. The indexes are only populated
   on-demand when the "locate" method is called. The order of the indexes
   is the same as the order of the repositories defined by the
   "repository_urls" attribute.

 locate( package => 'Foo::Bar' )
 locate( package => 'Foo::Bar', latest => 1 )
 locate( package => 'Foo::Bar', version => '1.2')
 locate( package => 'Foo::Bar', version => '1.2', latest => 1 )
 locate ( distribution => 'A/AU/AUTHOR/Foo-Bar-1.0.tar.gz' )
   Given the name of a package, searches all the repository indexes and
   returns the URL to a distribution containing that requested package, or
   the distribution you requested.

   If you also specify a "version", then you'll always get a distribution
   that contains that version of the package or higher. If you also specify
   "latest" then you'll always get the distribution that contains the
   latest version of the package that can be found in all the indexes.
   Otherwise you'll just get the first distribution we can find that
   satisfies your request.

   If you give a distribution path instead, then you'll just get back the
   URL to the first distribution we find at that path in any of the
   repository indexes.

   If neither the package nor the distribution path can be found in any of
   the indexes, returns undef.

 clear_cache()
   Deletes the cached index files. Any subsequent calls to the "locate"
   method will cause the index files to be fetched anew.

MOTIVATION
   The CPAN module also provides a mechanism for locating packages or
   distributions, much like Package::Locator does. However, CPAN assumes
   that all repositories are CPAN mirrors, so it only searches the first
   repository that it can contact.

   My secret ambition is to fill the world with lots of DarkPAN
   repositories -- each with its own set of distributions. For that
   scenario, I need to search multiple repositories at the same time.

SEE ALSO
   If you need to locate a distribution that contains a precise version of
   a file rather than just a version that is "new enough", then look at
   some of these:

   Dist::Surveyor

   BackPAN::Index

   BackPAN::Version::Discover

SUPPORT
 Perldoc
   You can find documentation for this module with the perldoc command.

     perldoc Package::Locator

 Websites
   The following websites have more information about this module, and may
   be of help to you. As always, in addition to those websites please use
   your favorite search engine to discover more resources.

   *   Search CPAN

       The default CPAN search engine, useful to view POD in HTML format.

       <http://search.cpan.org/dist/Package-Locator>

   *   CPAN Ratings

       The CPAN Ratings is a website that allows community ratings and
       reviews of Perl modules.

       <http://cpanratings.perl.org/d/Package-Locator>

   *   CPAN Testers

       The CPAN Testers is a network of smokers who run automated tests on
       uploaded CPAN distributions.

       <http://www.cpantesters.org/distro/P/Package-Locator>

   *   CPAN Testers Matrix

       The CPAN Testers Matrix is a website that provides a visual overview
       of the test results for a distribution on various Perls/platforms.

       <http://matrix.cpantesters.org/?dist=Package-Locator>

   *   CPAN Testers Dependencies

       The CPAN Testers Dependencies is a website that shows a chart of the
       test results of all dependencies for a distribution.

       <http://deps.cpantesters.org/?module=Package::Locator>

 Bugs / Feature Requests
   <https://github.com/thaljef/Package-Locator/issues>

 Source Code
   <https://github.com/thaljef/Package-Locator>

     git clone git://github.com/thaljef/Package-Locator.git

AUTHOR
   Jeffrey Ryan Thalhammer <[email protected]>

COPYRIGHT AND LICENSE
   This software is copyright (c) 2011 by Imaginative Software Systems.

   This is free software; you can redistribute it and/or modify it under
   the same terms as the Perl 5 programming language system itself.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.