MetaCPAN::Client(3pm)

📦

version 2.044000 · 10 versions

2.044000 · ubuntu stonking (latest)
2.029000 · epel 9
2.043000 · alpine 3.24
2.033000 · fedora 43
2.029000 · ubuntu jammy
2.040000 · fedora 44
2.031000 · ubuntu noble
2.030000 · debian bookworm
2.038000 · ubuntu resolute
2.033000 · debian trixie, ubuntu questing

💖 MetaCPAN::Client 💖

okay so bestie, welcome to MetaCPAN::Client — a comprehensive, DWIM-featured client to the MetaCPAN API. yes that's the actual name. it's giving iconic and it's about to make your whole Perl life easier. 🦋

✨ VERSION ✨

version 2.044000

🌸 SYNOPSIS 🌸

fr fr, here's the simple vibe:

# simple usage
my $mcpan  = MetaCPAN::Client->new();
my $author = $mcpan->author('XSAWYERX');
my $dist   = $mcpan->distribution('MetaCPAN-Client');

and now the advanced look — caching edition (contributed by Kent Fredric, king behavior honestly 👑):

# advanced usage with cache (contributed by Kent Fredric)
use CHI;
use WWW::Mechanize::Cached;
use HTTP::Tiny::Mech;
use MetaCPAN::Client;

my $mcpan = MetaCPAN::Client->new(
  ua => HTTP::Tiny::Mech->new(
    mechua => WWW::Mechanize::Cached->new(
      cache => CHI->new(
        driver   => 'File',
        root_dir => '/tmp/metacpan-cache',
      ),
    ),
  ),
);

# now $mcpan caches results

🌈 DESCRIPTION 🌈

This is a hopefully-complete API-compliant client to MetaCPAN (<https://metacpan.org>). it's got DWIM capabilities and it's literally here to make your life easier. no cap. 💅

🎀 ATTRIBUTES 🎀

`request`

Internal attribute representing the request object making the request to MetaCPAN and analyzing the results. ngl bestie, you probably don't want to set this, nor should you have any usage of it. just... leave it alone. 🙈

`ua`

If provided, MetaCPAN::Client::Request will use the user agent object instead of the default, which is HTTP::Tiny.

Then it can be used to fetch the user agent object used by MetaCPAN::Client::Request.

`domain`

If given, will be used to alter the API domain. 🌐

`debug`

If given, errors will include some low-level detailed message. (chaos mode activated, but informative chaos 💀)

💅 METHODS 💅

`author`

my $author = $mcpan->author('XSAWYERX');
my $author_resultset = $mcpan->author($search_spec);

Finds an author by either its PAUSE ID or by a search spec defined by a hash reference. since this pattern is common to so many other searches, it gets its own lil explainer down below under "SEARCH SPEC".

Returns a MetaCPAN::Client::Author object on a simple search (PAUSE ID), or a MetaCPAN::Client::ResultSet object populated with MetaCPAN::Client::Author objects on a complex (search spec based) search. she's versatile like that. ✨

`cover`

my $cover = $mcpan->cover('Moose-2.2007');

Returns a MetaCPAN::Client::Cover object. 📚

`cve`

my $cve = $mcpan->cve('CPANSA-DBD-SQLite-2019-5018');

Returns a MetaCPAN::Client::Cve object. (security girlies stay winning 🔥)

`distribution`

my $dist = $mcpan->distribution('MetaCPAN-Client');
my $dist_resultset = $mcpan->distribution($search_spec);

Finds a distribution by either its distribution name or by a search spec defined by a hash reference. and yes, since it's common to many other searches, it's explained below under "SEARCH SPEC".

Returns a MetaCPAN::Client::Distribution object on a simple search (distribution name), or a MetaCPAN::Client::ResultSet object populated with MetaCPAN::Client::Distribution objects on a complex (search spec based) search.

`file`

Returns a MetaCPAN::Client::File object. 🗂️

`favorite`

my $favorite_resultset = $mcpan->favorite({ distribution => 'Moose' });

Returns a MetaCPAN::Client::ResultSet object containing MetaCPAN::Client::Favorite results.

`release`

my $release = $mcpan->release('MetaCPAN-Client');
my $release_resultset = $mcpan->release($search_spec);

Finds a release by either its distribution name or by a search spec defined by a hash reference. yep — common to many other searches, so it's explained below under "SEARCH SPEC".

Returns a MetaCPAN::Client::Release object on a simple search (release name), or a MetaCPAN::Client::ResultSet object populated with MetaCPAN::Client::Release objects on a complex (search spec based) search.

`mirror`

my $mirror = $mcpan->mirror('kr.freebsd.org');

Returns a MetaCPAN::Client::Mirror object. 🪞

`module`

my $module = $mcpan->module('MetaCPAN::Client');
my $module_resultset = $mcpan->module($search_spec);

Finds a module by either its module name or by a search spec defined by a hash reference. you know the drill — common to many other searches, explained below under "SEARCH SPEC".

Returns a MetaCPAN::Client::Module object on a simple search (module name), or a MetaCPAN::Client::ResultSet object populated with MetaCPAN::Client::Module objects on a complex (search spec based) search.

`package`

my $package = $mcpan->package('MooseX::Types');

Returns a MetaCPAN::Client::Package object. 📦

`permission`

my $permission = $mcpan->permission('MooseX::Types');

Returns a MetaCPAN::Client::Permission object. (asking for permission?? in THIS economy?? 💀)

`reverse_dependencies`

my $deps_resultset = $mcpan->reverse_dependencies('Search::Elasticsearch');

all MetaCPAN::Client::Release objects of releases that are directly dependent on a given module, returned as MetaCPAN::Client::ResultSet. the "who needs you" report, if you will. 🫶

`rev_deps`

Alias to reverse_dependencies described above. (same energy, shorter name ✨)

`autocomplete`

my $ac = $mcpan->autocomplete('Danc');

Call the search/autocomplete endpoint with a query string.

Returns an array reference.

`autocomplete_suggest`

my $ac = $mcpan->autocomplete_suggest('Moo');

Call the search/autocomplete/suggest endpoint with a query string.

Returns an array reference. 🔮

`recent`

my $recent_resultset = $mcpan->recent(10);
my $recent_resultset = $mcpan->recent('today');

return the latest N releases, or all releases from today.

returns a MetaCPAN::Client::ResultSet of MetaCPAN::Client::Release. it's giving "what's hot right now" 🔥

`pod`

Get POD for given file/module name. returns a MetaCPAN::Client::Pod object, which supports various output formats (html, plain, x_pod & x_markdown).

my $pod = $mcpan->pod('Moo')->html;
my $pod = $mcpan->pod('Moo', { url_prefix => $prefix })->html;

`download_url`

Retrieve information from the download_url endpoint 📥

my $download_url = $mcpan->download_url($distro, [$version_or_range, $dev]);

# request the last available version
my $download_url = $mcpan->download_url('Moose');

# request an older version
my $download_url = $mcpan->download_url('Moose', '1.01');

# using a range
my $download_url = $mcpan->download_url('Moose', '<=1.01');
my $download_url = $mcpan->download_url('Moose', '>1.01,<=2.00');

Range operators are == != <= >= < > !. You can use a comma , to add multiple rules.

# requesting dev release
my $download_url = $mcpan->download_url('Moose', '>1.01', 1);

Returns a MetaCPAN::Client::DownloadURL object

`count`

Returns the count of records in a given index.

my $count = $mcpan->count('release');

`all`

Retrieve all matches for authors/modules/distributions/favorites/files/permissions/packages/covers/cves or releases.

my $all_releases = $mcpan->all('releases')

When called with a second parameter containing a hash ref, will support the following keys:

fields

See SEARCH PARAMS.

my $all_releases_resultset = $mcpan->all('releases', { fields => [...] })

_source

See SEARCH PARAMS.

my $all_releases_resultset = $mcpan->all('releases', { _source => [...] })

es_filter

Pass a raw Elasticsearch filter structure to reduce the number of elements returned by the query.

my $some_releases_resultset = $mcpan->all('releases', { es_filter => {...} })

`BUILDARGS`

Internal construction wrapper. Do not use. 🚫 (bestie I'm serious, hands off)

💜 SEARCH PARAMS 💜

Most searches take params as an optional hash-ref argument. these params will be passed to the search action.

In non-scrolled searches, 'fields' filter is the only supported parameter ATM.

`fields`

Filter the fields to reduce the amount of data pulled from MetaCPAN. can be passed as a csv list or an array ref.

my $module = $mcpan->module('Moose', { fields => "version,author" });
my $module = $mcpan->module('Moose', { fields => [qw/version author/] });

`_source`

Note: this param and its description are a bit too Elasticsearch specific. just like 'es_filter' — use only if you know what you're dealing with. ⚠️

Some fields are not indexed in Elasticsearch but stored as part of the entire document.

These fields can still be read, but without the internal Elasticsearch optimizations and the server will internally read the whole document.

Why do we even need those? because we don't index everything and some things we can't to begin with (like non-leaf fields that hold a structure)

my $module_resultset = $mcpan->all('releases', { _source => "stat" });

`scroller_time`

Note: please use with caution. 🚨

This parameter will set the maximum lifetime of the Elasticsearch scroller on the server (default = '5m'). Normally you do not need to set this value (as tweaking this value can affect resources on the server). In case you do, you probably need to check the efficiency of your code/queries. (Feel free to reach out to us for assistance).

my $module = $mcpan->all('releases', { scroller_time => '3m' });

`scroller_size`

Note: please use with caution. 🚨

This parameter will set the buffer size to be pulled from Elasticsearch when scrolling (default = 1000). This will affect query performance and memory usage, but you will still get an iterator back to fetch one object at a time.

my $module = $mcpan->all('releases', { scroller_size => 500 });

`sort`

Pass a raw Elasticsearch sort specification for the query.

my $some_releases = $mcpan->all('releases', { sort => [{ date => { order => 'desc' } }] })

Note: this param and is a bit too specific to Elasticsearch. Just like "es_filter", only use this if you know what you're dealing with. ⚠️

💖 SEARCH SPEC 💖

okay so the hash-based search spec? it's the shared bestie that lots of searches use. it's super feature-rich and it lets you disambiguate different types of searches. periodt.

Basic search specs are literally just a hash of keys and values:

my $author = $mcpan->author( { name => 'Micha Nasriachi' } );

# the following is the same as ->author('MICKEY')
my $author = $mcpan->author( { pauseid => 'MICKEY' } );

# find all people named Dave, not covering Davids
# will return a resultset
my $daves = $mcpan->author( { name => 'Dave *' } );

💫 OR 💫

if you want a more complicated query that has an OR condition, like "this or that", you can use the following syntax with the either key:

# any author named "Dave" or "David"
my $daves = $mcpan->author( {
    either => [
        { name => 'Dave *'  },
        { name => 'David *' },
    ]
} );

🌸 AND 🌸

if you want a more complicated query that has an AND condition, like "this and that", you can use the following syntax with the all key:

# any users named 'John' with a Gmail account
my $johns = $mcpan->author( {
    all => [
        { name  => 'John *'     },
        { email => '*gmail.com' },
    ]
} );

or, to get either the given version of a release, or the latest:

my $releases = $mcpan->release( {
    all => [
      { distribution => 'GraphViz2' },
      ($version ? { version => $version } : { status => 'latest' }),
    ],
} );

if you want to do something even more complicated, you can also nest your queries, e.g.:

my $gmail_daves_or_cpan_sams = $mcpan->author( {
    either => [
        { all => [ { name => 'Dave *'  },
                   { email => '*gmail.com' } ]
        },
        { all => [ { name => 'Sam *' },
                   { email => '*cpan.org' } ]
        },
    ],
} );

🚫 NOT 🚫

if you want to filter out some of the results of an either/all query by adding a NOT filter condition, like "not these", you can use the following syntax with the not key:

# any author named "Dave" or "David"
my $daves = $mcpan->author( {
    either => [
        { name => 'Dave *'  },
        { name => 'David *' },
    ],
    not => [
        { email => '*gmail.com' },
    ],
} );

🌈 DESIGN 🌈

this module has three purposes:

Provide 100% of the MetaCPAN API

this module will be updated regularly on every MetaCPAN API change, and intends to provide the user with as much of the API as possible, no shortcuts. if it's documented in the API, you should be able to do it.

because of this design decision, this module has an official MetaCPAN namespace with the blessing of the MetaCPAN developers.

notice this module currently only provides the beta API, not the old soon-to-be-deprecated API.

Be lightweight, to allow flexible usage

while many modules would help make writing easier, it's important to take into account how they affect your compile-time, run-time, overall memory consumption, and CPU usage.

by providing a slim interface implementation, more users are able to use this module, such as long-running processes (like daemons), CLI or GUI applications, cron jobs, and more.

DWIM

while it's possible to access the methods defined by the API spec, there's still a matter of what you're really trying to achieve. for example, when searching for "Dave", you want to find both Dave Cross and Dave Rolsky (and any other Dave), but you also want to search for a PAUSE ID of DAVE, if one exists.

this is where DWIM comes in. this module provides you with additional generic methods which will try to do what they think you want.

of course, this does not prevent you from manually using the API methods. you still have full control over that, if that's what you wish.

you can (and should) read up on the general methods, which will explain how their DWIMish nature works, and what searches they run.

👑 AUTHORS 👑

Sawyer X <xsawyerx@cpan.org>
Mickey Nasriachi <mickey@cpan.org>

📜 COPYRIGHT AND LICENSE 📜

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 vibe, bestie 💅 this page is from MetaCPAN::Client(3pm), generated with perl v5.40.1 on 2026-07-05. go forth and search iconically ✨💖🦋

📦 where this page comes from

ubuntu stonking: libmetacpan-client-perl 2.044000-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms