.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "MetaCPAN::Client 3pm"
.TH MetaCPAN::Client 3pm "2022-09-29" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MetaCPAN::Client \- A comprehensive, DWIM\-featured client to the MetaCPAN API
.SH "VERSION"
.IX Header "VERSION"
version 2.030000
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&    # simple usage
\&    my $mcpan  = MetaCPAN::Client\->new();
\&    my $author = $mcpan\->author(\*(AqXSAWYERX\*(Aq);
\&    my $dist   = $mcpan\->distribution(\*(AqMetaCPAN\-Client\*(Aq);
\&
\&    # 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   => \*(AqFile\*(Aq,
\&            root_dir => \*(Aq/tmp/metacpan\-cache\*(Aq,
\&          ),
\&        ),
\&      ),
\&    );
\&
\&    # now $mcpan caches results
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a hopefully-complete API-compliant client to MetaCPAN
(<https://metacpan.org>) with \s-1DWIM\s0 capabilities, to make your life easier.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "request"
.IX Subsection "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.
.SS "ua"
.IX Subsection "ua"
If provided, MetaCPAN::Client::Request will use the user agent object
instead of the default, which is HTTP::Tiny.
.PP
Then it can be used to fetch the user agent object used by
MetaCPAN::Client::Request.
.SS "domain"
.IX Subsection "domain"
If given, will be used to alter the \s-1API\s0 domain.
.SS "debug"
.IX Subsection "debug"
If given, errors will include some low-level detailed message.
.SH "METHODS"
.IX Header "METHODS"
.SS "author"
.IX Subsection "author"
.Vb 2
\&    my $author = $mcpan\->author(\*(AqXSAWYERX\*(Aq);
\&    my $author = $mcpan\->author($search_spec);
.Ve
.PP
Finds an author by either its \s-1PAUSE ID\s0 or by a search spec defined by a hash
reference. Since it is common to many other searches, it is explained below
under \f(CW\*(C`SEARCH SPEC\*(C'\fR.
.PP
Returns a MetaCPAN::Client::Author object on a simple search (\s-1PAUSE ID\s0), or
a MetaCPAN::Client::ResultSet object populated with
MetaCPAN::Client::Author objects on a complex (search spec based) search.
.SS "cover"
.IX Subsection "cover"
.Vb 1
\&    my $cover = $mcpan\->cover(\*(AqMoose\-2.2007\*(Aq);
.Ve
.PP
Returns a MetaCPAN::Client::Cover object.
.SS "distribution"
.IX Subsection "distribution"
.Vb 2
\&    my $dist = $mcpan\->distribution(\*(AqMetaCPAN\-Client\*(Aq);
\&    my $dist = $mcpan\->distribution($search_spec);
.Ve
.PP
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 \f(CW\*(C`SEARCH SPEC\*(C'\fR.
.PP
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.
.SS "file"
.IX Subsection "file"
Returns a MetaCPAN::Client::File object.
.SS "favorite"
.IX Subsection "favorite"
.Vb 1
\&    my $favorite = $mcpan\->favorite({ distribution => \*(AqMoose\*(Aq });
.Ve
.PP
Returns a MetaCPAN::Client::ResultSet object containing
MetaCPAN::Client::Favorite results.
.SS "rating"
.IX Subsection "rating"
.Vb 1
\&    my $rating = $mcpan\->rating({ distribution => \*(AqMoose\*(Aq });
.Ve
.PP
Returns a MetaCPAN::Client::ResultSet object containing
MetaCPAN::Client::Rating results.
.SS "release"
.IX Subsection "release"
.Vb 2
\&    my $release = $mcpan\->release(\*(AqMetaCPAN\-Client\*(Aq);
\&    my $release = $mcpan\->release($search_spec);
.Ve
.PP
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 \f(CW\*(C`SEARCH SPEC\*(C'\fR.
.PP
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.
.SS "mirror"
.IX Subsection "mirror"
.Vb 1
\&    my $mirror = $mcpan\->mirror(\*(Aqkr.freebsd.org\*(Aq);
.Ve
.PP
Returns a MetaCPAN::Client::Mirror object.
.SS "module"
.IX Subsection "module"
.Vb 2
\&    my $module = $mcpan\->module(\*(AqMetaCPAN::Client\*(Aq);
\&    my $module = $mcpan\->module($search_spec);
.Ve
.PP
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 \f(CW\*(C`SEARCH SPEC\*(C'\fR.
.PP
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.
.SS "package"
.IX Subsection "package"
.Vb 1
\&    my $package = $mcpan\->package(\*(AqMooseX::Types\*(Aq);
.Ve
.PP
Returns a MetaCPAN::Client::Package object.
.SS "permission"
.IX Subsection "permission"
.Vb 1
\&    my $permission = $mcpan\->permission(\*(AqMooseX::Types\*(Aq);
.Ve
.PP
Returns a MetaCPAN::Client::Permission object.
.SS "reverse_dependencies"
.IX Subsection "reverse_dependencies"
.Vb 1
\&    my $deps = $mcpan\->reverse_dependencies(\*(AqSearch::Elasticsearch\*(Aq);
.Ve
.PP
all MetaCPAN::Client::Release objects of releases that are directly
dependent on a given module, returned as MetaCPAN::Client::ResultSet.
.SS "rev_deps"
.IX Subsection "rev_deps"
Alias to \f(CW\*(C`reverse_dependencies\*(C'\fR described above.
.SS "autocomplete"
.IX Subsection "autocomplete"
.Vb 1
\&    my $ac = $mcpan\->autocomplete(\*(AqDanc\*(Aq);
.Ve
.PP
Call the search/autocomplete endpoint with a query string.
.PP
Returns an array reference.
.SS "autocomplete_suggest"
.IX Subsection "autocomplete_suggest"
.Vb 1
\&    my $ac = $mcpan\->autocomplete_suggest(\*(AqMoo\*(Aq);
.Ve
.PP
Call the search/autocomplete/suggest endpoint with a query string.
.PP
Returns an array reference.
.SS "recent"
.IX Subsection "recent"
.Vb 2
\&    my $recent = $mcpan\->recent(10);
\&    my $recent = $mcpan\->recent(\*(Aqtoday\*(Aq);
.Ve
.PP
return the latest N releases, or all releases from today.
.PP
returns a MetaCPAN::Client::ResultSet of MetaCPAN::Client::Release.
.SS "pod"
.IX Subsection "pod"
Get \s-1POD\s0 for given file/module name.
returns a MetaCPAN::Client::Pod object, which supports various output
formats (html, plain, x_pod & x_markdown).
.PP
.Vb 2
\&    my $pod = $mcpan\->pod(\*(AqMoo\*(Aq)\->html;
\&    my $pod = $mcpan\->pod(\*(AqMoo\*(Aq, { url_prefix => $prefix })\->html;
.Ve
.SS "download_url"
.IX Subsection "download_url"
Retrieve information from the 'download_url' endpoint
.PP
.Vb 1
\&    my $download_url = $mcpan\->download_url($distro, [$version_or_range, $dev]);
\&
\&    # request the last available version
\&    my $download_url = $mcpan\->download_url(\*(AqMoose\*(Aq);
\&
\&    # request an older version
\&    my $download_url = $mcpan\->download_url(\*(AqMoose\*(Aq, \*(Aq1.01\*(Aq);
\&
\&    # using a range
\&    my $download_url = $mcpan\->download_url(\*(AqMoose\*(Aq, \*(Aq<=1.01\*(Aq);
\&    my $download_url = $mcpan\->download_url(\*(AqMoose\*(Aq, \*(Aq>1.01,<=2.00\*(Aq);
.Ve
.PP
Range operators are '== != <= >= < > !'.
You can use a comma ',' to add multiple rules.
.PP
.Vb 2
\&    # requesting dev release
\&    my $download_url = $mcpan\->download_url(\*(AqMoose\*(Aq, \*(Aq>1.01\*(Aq, 1);
.Ve
.PP
Returns a MetaCPAN::Client::DownloadURL object
.SS "all"
.IX Subsection "all"
Retrieve all matches for authors/modules/distributions/favorites or releases.
.PP
.Vb 1
\&    my $all_releases = $mcpan\->all(\*(Aqreleases\*(Aq)
.Ve
.PP
When called with a second parameter containing a hash ref,
will support the following keys:
.PP
\fIfields\fR
.IX Subsection "fields"
.PP
See \s-1SEARCH PARAMS.\s0
.PP
.Vb 1
\&   my $all_releases = $mcpan\->all(\*(Aqreleases\*(Aq, { fields => [...] })
.Ve
.PP
\fI_source\fR
.IX Subsection "_source"
.PP
See \s-1SEARCH PARAMS.\s0
.PP
.Vb 1
\&   my $all_releases = $mcpan\->all(\*(Aqreleases\*(Aq, { _source => [...] })
.Ve
.PP
\fIes_filter\fR
.IX Subsection "es_filter"
.PP
Pass a raw Elasticsearch filter structure to reduce the number
of elements returned by the query.
.PP
.Vb 1
\&    my $some_releases = $mcpan\->all(\*(Aqreleases\*(Aq, { es_filter => {...} })
.Ve
.SS "\s-1BUILDARGS\s0"
.IX Subsection "BUILDARGS"
Internal construction wrapper. Do not use.
.SH "SEARCH PARAMS"
.IX Header "SEARCH PARAMS"
Most searches take params as an optional hash-ref argument.
these params will be passed to the search action.
.PP
In non-scrolled searches, 'fields' filter is the only supported
parameter \s-1ATM.\s0
.SS "fields"
.IX Subsection "fields"
Filter the fields to reduce the amount of data pulled from MetaCPAN.
can be passed as a csv list or an array ref.
.PP
.Vb 2
\&    my $module = $mcpan\->module(\*(AqMoose\*(Aq, { fields => "version,author" });
\&    my $module = $mcpan\->module(\*(AqMoose\*(Aq, { fields => [qw/version author/] });
.Ve
.SS "_source"
.IX Subsection "_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.
.PP
Some fields are not indexed in Elasticsearch but stored as part of
the entire document.
.PP
These fields can still be read, but without the internal Elasticsearch
optimizations and the server will internally read the whole document.
.PP
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)
.PP
.Vb 1
\&    my $module = $mcpan\->all(\*(Aqreleases\*(Aq, { _source => "stat" });
.Ve
.SS "scroller_time"
.IX Subsection "scroller_time"
Note: please use with caution.
.PP
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).
.PP
.Vb 1
\&    my $module = $mcpan\->all(\*(Aqreleases\*(Aq, { scroller_time => \*(Aq3m\*(Aq });
.Ve
.SS "scroller_size"
.IX Subsection "scroller_size"
Note: please use with caution.
.PP
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.
.PP
.Vb 1
\&    my $module = $mcpan\->all(\*(Aqreleases\*(Aq, { scroller_size => 500 });
.Ve
.PP
\fIsort\fR
.IX Subsection "sort"
.PP
Pass a raw Elasticsearch sort specification for the query.
.PP
.Vb 1
\&    my $some_releases = $mcpan\->all(\*(Aqreleases\*(Aq, { sort => [{ date => { order => \*(Aqdesc\*(Aq } }] })
.Ve
.PP
Note: this param and is a bit too specific to Elasticsearch.  Just like
\&\*(L"es_filter\*(R", only use this if you know what you're dealing with.
.SH "SEARCH SPEC"
.IX Header "SEARCH SPEC"
The hash-based search spec is common to many searches. It is quite
feature-rich and allows you to disambiguate different types of searches.
.PP
Basic search specs just contain a hash of keys and values:
.PP
.Vb 1
\&    my $author = $mcpan\->author( { name => \*(AqMicha Nasriachi\*(Aq } );
\&
\&    # the following is the same as \->author(\*(AqMICKEY\*(Aq)
\&    my $author = $mcpan\->author( { pauseid => \*(AqMICKEY\*(Aq } );
\&
\&    # find all people named Dave, not covering Davids
\&    # will return a resultset
\&    my $daves = $mcpan\->author( { name => \*(AqDave *\*(Aq } );
.Ve
.SS "\s-1OR\s0"
.IX Subsection "OR"
If you want to do a more complicated query that has an \fI\s-1OR\s0\fR condition,
such as \*(L"this or that\*(R", you can use the following syntax with the \f(CW\*(C`either\*(C'\fR
key:
.PP
.Vb 7
\&    # any author named "Dave" or "David"
\&    my $daves = $mcpan\->author( {
\&        either => [
\&            { name => \*(AqDave *\*(Aq  },
\&            { name => \*(AqDavid *\*(Aq },
\&        ]
\&    } );
.Ve
.SS "\s-1AND\s0"
.IX Subsection "AND"
If you want to do a more complicated query that has an \fI\s-1AND\s0\fR condition,
such as \*(L"this and that\*(R", you can use the following syntax with the \f(CW\*(C`all\*(C'\fR
key:
.PP
.Vb 7
\&    # any users named \*(AqJohn\*(Aq with a Gmail account
\&    my $johns = $mcpan\->author( {
\&        all => [
\&            { name  => \*(AqJohn *\*(Aq     },
\&            { email => \*(Aq*gmail.com\*(Aq },
\&        ]
\&    } );
.Ve
.PP
Or, to get either the given version of a release, or the latest:
.PP
.Vb 6
\&    my $releases = $mcpan\->release( {
\&        all => [
\&          { distribution => \*(AqGraphViz2\*(Aq },
\&          ($version ? { version => $version } : { status => \*(Aqlatest\*(Aq }),
\&        ],
\&    } );
.Ve
.PP
If you want to do something even more complicated,
You can also nest your queries, e.g.:
.PP
.Vb 10
\&    my $gmail_daves_or_cpan_sams = $mcpan\->author( {
\&        either => [
\&            { all => [ { name => \*(AqDave *\*(Aq  },
\&                       { email => \*(Aq*gmail.com\*(Aq } ]
\&            },
\&            { all => [ { name => \*(AqSam *\*(Aq },
\&                       { email => \*(Aq*cpan.org\*(Aq } ]
\&            },
\&        ],
\&    } );
.Ve
.SS "\s-1NOT\s0"
.IX Subsection "NOT"
If you want to filter out some of the results of an either/all query
adding a \fI\s-1NOT\s0\fR filter condition, such as \*(L"not these\*(R", you can use the
following syntax with the \f(CW\*(C`not\*(C'\fR key:
.PP
.Vb 10
\&    # any author named "Dave" or "David"
\&    my $daves = $mcpan\->author( {
\&        either => [
\&            { name => \*(AqDave *\*(Aq  },
\&            { name => \*(AqDavid *\*(Aq },
\&        ],
\&        not => [
\&            { email => \*(Aq*gmail.com\*(Aq },
\&        ],
\&    } );
.Ve
.SH "DESIGN"
.IX Header "DESIGN"
This module has three purposes:
.IP "\(bu" 4
Provide 100% of the MetaCPAN \s-1API\s0
.Sp
This module will be updated regularly on every MetaCPAN \s-1API\s0 change, and intends
to provide the user with as much of the \s-1API\s0 as possible, no shortcuts. If it's
documented in the \s-1API,\s0 you should be able to do it.
.Sp
Because of this design decision, this module has an official MetaCPAN namespace
with the blessing of the MetaCPAN developers.
.Sp
Notice this module currently only provides the beta \s-1API,\s0 not the old
soon-to-be-deprecated \s-1API.\s0
.IP "\(bu" 4
Be lightweight, to allow flexible usage
.Sp
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 \s-1CPU\s0 usage.
.Sp
By providing a slim interface implementation, more users are able to use this
module, such as long-running processes (like daemons), \s-1CLI\s0 or \s-1GUI\s0 applications,
cron jobs, and more.
.IP "\(bu" 4
\&\s-1DWIM\s0
.Sp
While it's possible to access the methods defined by the \s-1API\s0 spec, there's still
a matter of what you're really trying to achieve. For example, when searching
for \fI\*(L"Dave\*(R"\fR, you want to find both \fIDave Cross\fR and \fIDave Rolsky\fR (and any
other \fIDave\fR), but you also want to search for a \s-1PAUSE ID\s0 of \fI\s-1DAVE\s0\fR, if one
exists.
.Sp
This is where \s-1DWIM\s0 comes in. This module provides you with additional generic
methods which will try to do what they think you want.
.Sp
Of course, this does not prevent you from manually using the \s-1API\s0 methods. You
still have full control over that, if that's what you wish.
.Sp
You can (and should) read up on the general methods, which will explain how
their DWIMish nature works, and what searches they run.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Sawyer X <xsawyerx@cpan.org>
.IP "\(bu" 4
Mickey Nasriachi <mickey@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2016 by Sawyer X.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.