NAME¶
Package::Locator - Find a package among CPAN-like repositories
VERSION¶
version 0.010
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 <jeff@imaginative-software.com>
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.