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

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.

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.

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.

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.

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.

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.

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.