MetaCPAN::Client - A comprehensive, DWIM-featured client to the MetaCPAN API

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

   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.

       •   Sawyer X <xsawyerx@cpan.org>

       •   Mickey Nasriachi <mickey@cpan.org>

       This software is copyright (c) 2016 by Sawyer X.

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

perl v5.40.0                                       2024-12-07                              MetaCPAN::Client(3pm)

       This is a hopefully-complete API-compliant client to MetaCPAN (<https://metacpan.org>) with DWIM
       capabilities, to make your life easier.

       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 DaveCross and DaveRolsky (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.

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

       Finds an author by either its PAUSE ID or by a search spec defined by a hash reference. Since it is
       common to many other searches, it is explained 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.

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

       Returns a MetaCPAN::Client::Cover object.

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

       Finds a distribution by either its distribution name or by a search spec defined by a hash reference.
       Since it is common to many other searches, it is 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 = $mcpan->favorite({ distribution => 'Moose' });

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

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

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

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

       Finds a release by either its distribution name or by a search spec defined by a hash reference. Since it
       is common to many other searches, it is 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 = $mcpan->module($search_spec);

       Finds a module by either its module name or by a search spec defined by a hash reference. Since it is
       common to many other searches, it is 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.

   reverse_dependencies
           my $deps = $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.

   rev_deps
       Alias to "reverse_dependencies" described above.

   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 = $mcpan->recent(10);
           my $recent = $mcpan->recent('today');

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

       returns a MetaCPAN::Client::ResultSet of MetaCPAN::Client::Release.

   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

   all
       Retrieve all matches for authors/modules/distributions/favorites 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 = $mcpan->all('releases', { fields => [...] })

       _source

       See SEARCH PARAMS.

          my $all_releases = $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 = $mcpan->all('releases', { es_filter => {...} })

   BUILDARGS
       Internal construction wrapper. Do not use.

       MetaCPAN::Client - A comprehensive, DWIM-featured client to the MetaCPAN API

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

       The hash-based search spec is common to many searches. It is quite feature-rich and allows you to
       disambiguate different types of searches.

       Basic search specs just contain 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 to do a more complicated query that has an OR condition, such as "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 to do a more complicated query that has an AND condition, such as "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 adding a NOT filter condition, such
       as "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' },
               ],
           } );

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

           # 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

       version 2.033000