Package::Locator(3pm)

💖 Package::Locator 💖

okay so bestie, welcome to Package::Locator — the Perl module that answers the eternal question: "where tf do I find a package among CPAN-like repositories?" 🦋 It lives in the User Contributed Perl Documentation section of your man pages, and it is version 0.010. yes. that's the version. slay.

---

✨ SYNOPSIS ✨

here's the vibe, straight up:

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');

(yes those are exactly the examples, typos and all, and no we are not "fixing" them, they are iconic 💅)

---

🌸 DESCRIPTION 🌸

so Package::Locator is out here trying to answer the big question: "Where can I find a distribution that will provide this package?" and the way it divines the answer is by searching the indexes for one or more CPAN-like repositories. that's the whole bit. 🔮

if you also hand it a specific version number, it will attempt to find a distribution with that version of the package, or higher. and if you're feeling extra, you can ask it to find the latest version of a package across all the indexes. obsessed.

⚠️ okay important caveat, bestie: Package::Locator only looks at the index files for each repository, and those indexes only contain info about the latest versions of the packages within that repository. so this is not BackPAN magic — you cannot use it to find precisely which distribution a particular package (or file) came from. no cap. for that stuff, see "/See Also" below. 💀

---

🎀 CONSTRUCTOR 🎀

new( %attributes )

all the attributes listed below can be passed to the constructor, and retrieved via accessor methods with the same name. and the way that they're all read-only... they cannot be changed once the object is constructed. periodt. 🔒

---

⭐ ATTRIBUTES ⭐

• repository_urls => [ qw(http://somewhere http://somewhere.else) ] — an array reference containing the base URLs of the repositories you wanna search. these are usually CPAN mirrors, but honestly they can be any website or local directory that's 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 the index files. if you don't provide a user agent, then a default one will be constructed for you. she's self-sufficient like that 🫶
• 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 don't specify a cache directory, then a temporary directory will be used, and that temporary directory gets deleted when your application terminates. bye girl 👋
• 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. ngl, the indexes are only populated on-demand when the locate method is called. and the order of the indexes is the same as the order of the repositories defined by the repository_urls attribute. consistent queen 👑

locate(...)

here's all the ways you can call her:

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, it 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. first come first served bestie.

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.

and if neither the package nor the distribution path can be found in any of the indexes, it returns undef. 😭 it happens to the best of us.

clear_cache()

deletes the cached index files. any subsequent calls to the locate method will cause the index files to be fetched anew. fresh start energy 🌈

---

🧚 MOTIVATION 🧚

so 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. mid behaviour, honestly.

and here's the tea: the author's secret ambition is to fill the world with lots of DarkPAN repositories — each with its own set of distributions. for that scenario, you need to search multiple repositories at the same time. and that's exactly what this module does. main character energy fr fr 👑

---

🔥 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

found a bug? want a feature? spill 🗣️

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

---

and that's the whole page bestie, no notes 💖 this lil legend came to you from perl v5.34.0, dated 2022-06-16, filed under Package::Locator(3pm) — go locate something, you got this 🦋✨