1MetaCPAN::Client(3)   User Contributed Perl Documentation  MetaCPAN::Client(3)
2
3
4

NAME

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

VERSION

10       version 2.026000
11

SYNOPSIS

13           # simple usage
14           my $mcpan  = MetaCPAN::Client->new();
15           my $author = $mcpan->author('XSAWYERX');
16           my $dist   = $mcpan->distribution('MetaCPAN-Client');
17
18           # advanced usage with cache (contributed by Kent Fredric)
19           use CHI;
20           use WWW::Mechanize::Cached;
21           use HTTP::Tiny::Mech;
22           use MetaCPAN::Client;
23
24           my $mcpan = MetaCPAN::Client->new(
25             ua => HTTP::Tiny::Mech->new(
26               mechua => WWW::Mechanize::Cached->new(
27                 cache => CHI->new(
28                   driver   => 'File',
29                   root_dir => '/tmp/metacpan-cache',
30                 ),
31               ),
32             ),
33           );
34
35           # now $mcpan caches results
36

DESCRIPTION

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

ATTRIBUTES

43   request
44       Internal attribute representing the request object making the request
45       to MetaCPAN and analyzing the results. You probably don't want to set
46       this, nor should you have any usage of it.
47
48   ua
49       If provided, MetaCPAN::Client::Request will use the user agent object
50       instead of the default, which is HTTP::Tiny.
51
52       Then it can be used to fetch the user agent object used by
53       MetaCPAN::Client::Request.
54
55   domain
56       If given, will be used to alter the API domain.
57
58   debug
59       If given, errors will include some low-level detailed message.
60

METHODS

62   author
63           my $author = $mcpan->author('XSAWYERX');
64           my $author = $mcpan->author($search_spec);
65
66       Finds an author by either its PAUSE ID or by a search spec defined by a
67       hash reference. Since it is common to many other searches, it is
68       explained below under "SEARCH SPEC".
69
70       Returns a MetaCPAN::Client::Author object on a simple search (PAUSE
71       ID), or a MetaCPAN::Client::ResultSet object propagated with
72       MetaCPAN::Client::Author objects on a complex (search spec based)
73       search.
74
75   cover
76           my $cover = $mcpan->cover('Moose-2.2007');
77
78       Returns a MetaCPAN::Client::Cover object.
79
80   distribution
81           my $dist = $mcpan->distribution('MetaCPAN-Client');
82           my $dist = $mcpan->distribution($search_spec);
83
84       Finds a distribution by either its distribution name or by a search
85       spec defined by a hash reference. Since it is common to many other
86       searches, it is explained below under "SEARCH SPEC".
87
88       Returns a MetaCPAN::Client::Distribution object on a simple search
89       (distribution name), or a MetaCPAN::Client::ResultSet object propagated
90       with MetaCPAN::Client::Distribution objects on a complex (search spec
91       based) search.
92
93   file
94       Returns a MetaCPAN::Client::File object.
95
96   favorite
97           my $favorite = $mcpan->favorite({ distribution => 'Moose' });
98
99       Returns a MetaCPAN::Client::ResultSet object containing
100       MetaCPAN::Client::Favorite results.
101
102   rating
103           my $rating = $mcpan->rating({ distribution => 'Moose' });
104
105       Returns a MetaCPAN::Client::ResultSet object containing
106       MetaCPAN::Client::Rating results.
107
108   release
109           my $release = $mcpan->release('MetaCPAN-Client');
110           my $release = $mcpan->release($search_spec);
111
112       Finds a release by either its distribution name or by a search spec
113       defined by a hash reference. Since it is common to many other searches,
114       it is explained below under "SEARCH SPEC".
115
116       Returns a MetaCPAN::Client::Release object on a simple search (release
117       name), or a MetaCPAN::Client::ResultSet object propagated with
118       MetaCPAN::Client::Release objects on a complex (search spec based)
119       search.
120
121   mirror
122           my $mirror = $mcpan->mirror('kr.freebsd.org');
123
124       Returns a MetaCPAN::Client::Mirror object.
125
126   module
127           my $module = $mcpan->module('MetaCPAN::Client');
128           my $module = $mcpan->module($search_spec);
129
130       Finds a module by either its module name or by a search spec defined by
131       a hash reference. Since it is common to many other searches, it is
132       explained below under "SEARCH SPEC".
133
134       Returns a MetaCPAN::Client::Module object on a simple search (module
135       name), or a MetaCPAN::Client::ResultSet object propagated with
136       MetaCPAN::Client::Module objects on a complex (search spec based)
137       search.
138
139   package
140           my $package = $mcpan->package('MooseX::Types');
141
142       Returns a MetaCPAN::Client::Package object.
143
144   permission
145           my $permission = $mcpan->permission('MooseX::Types');
146
147       Returns a MetaCPAN::Client::Permission object.
148
149   reverse_dependencies
150           my $deps = $mcpan->reverse_dependencies('Search::Elasticsearch');
151
152       all MetaCPAN::Client::Release objects of releases that are directly
153       dependent on a given module, returned as MetaCPAN::Client::ResultSet.
154
155   rev_deps
156       Alias to "reverse_dependencies" described above.
157
158   autocomplete
159           my $ac = $mcpan->autocomplete('Danc');
160
161       Call the search/autocomplete endpoint with a query string.
162
163       Returns an array reference.
164
165   autocomplete_suggest
166           my $ac = $mcpan->autocomplete_suggest('Moo');
167
168       Call the search/autocomplete/suggest endpoint with a query string.
169
170       Returns an array reference.
171
172   recent
173           my $recent = $mcpan->recent(10);
174           my $recent = $mcpan->recent('today');
175
176       return the latest N releases, or all releases from today.
177
178       returns a MetaCPAN::Client::ResultSet of MetaCPAN::Client::Release.
179
180   pod
181       Get POD for given file/module name.  returns a MetaCPAN::Client::Pod
182       object, which supports various output formats (html, plain, x_pod &
183       x_markdown).
184
185           my $pod = $mcpan->pod('Moo')->html;
186           my $pod = $mcpan->pod('Moo', { url_prefix => $prefix })->html;
187
188   download_url
189       Retrieve information from the 'download_url' endpoint
190
191           my $download_url = $mcpan->download_url('Moose')
192
193       Returns a MetaCPAN::Client::DownloadURL object
194
195   all
196       Retrieve all matches for authors/modules/distributions/favorites or
197       releases.
198
199           my $all_releases = $mcpan->all('releases')
200
201       When called with a second parameter containing a hash ref, will support
202       the following keys:
203
204       fields
205
206       See SEARCH PARAMS.
207
208          my $all_releases = $mcpan->all('releases', { fields => [...] })
209
210       _source
211
212       See SEARCH PARAMS.
213
214          my $all_releases = $mcpan->all('releases', { _source => [...] })
215
216       es_filter
217
218       Pass a raw Elasticsearch filter structure to reduce the number of
219       elements returned by the query.
220
221           my $some_releases = $mcpan->all('releases', { es_filter => {...} })
222
223   BUILDARGS
224       Internal construction wrapper. Do not use.
225

SEARCH PARAMS

227       Most searches take params as an optional hash-ref argument.  these
228       params will be passed to the search action.
229
230       In non-scrolled searches, 'fields' filter is the only supported
231       parameter ATM.
232
233   fields
234       Filter the fields to reduce the amount of data pulled from MetaCPAN.
235       can be passed as a csv list or an array ref.
236
237           my $module = $mcpan->module('Moose', { fields => "version,author" });
238           my $module = $mcpan->module('Moose', { fields => [qw/version author/] });
239
240   _source
241       Note: this param and its description are a bit too Elasticsearch
242       specific.  just like 'es_filter' - use only if you know what you're
243       dealing with.
244
245       Some fields are not indexed in Elasticsearch but stored as part of the
246       entire document.
247
248       These fields can still be read, but without the internal Elasticsearch
249       optimizations and the server will internally read the whole document.
250
251       Why do we even need those? because we don't index everything and some
252       things we can't to begin with (like non-leaf fields that hold a
253       structure)
254
255           my $module = $mcpan->all('releases', { _source => "stat" });
256
257   scroller_time
258       Note: please use with caution.
259
260       This parameter will set the maximum lifetime of the Elasticsearch
261       scroller on the server (default = '5m').  Normally you do not need to
262       set this value (as tweaking this value can affect resources on the
263       server).  In case you do, you probably need to check the efficiency of
264       your code/queries.  (Feel free to reach out to us for assistance).
265
266           my $module = $mcpan->all('releases', { scroller_time => '3m' });
267
268   scroller_size
269       Note: please use with caution.
270
271       This parameter will set the buffer size to be pulled from Elasticsearch
272       when scrolling (default = 1000).  This will affect query performance
273       and memory usage, but you will still get an iterator back to fetch one
274       object at a time.
275
276           my $module = $mcpan->all('releases', { scroller_size => 500 });
277
278       sort
279
280       Pass a raw Elasticsearch sort specification for the query.
281
282           my $some_releases = $mcpan->all('releases', { sort => [{ date => { order => 'desc' } }] })
283
284       Note: this param and is a bit too specific to Elasticsearch.  Just like
285       "es_filter", only use this if you know what you're dealing with.
286

SEARCH SPEC

288       The hash-based search spec is common to many searches. It is quite
289       feature-rich and allows you to disambiguate different types of
290       searches.
291
292       Basic search specs just contain a hash of keys and values:
293
294           my $author = $mcpan->author( { name => 'Micha Nasriachi' } );
295
296           # the following is the same as ->author('MICKEY')
297           my $author = $mcpan->author( { pauseid => 'MICKEY' } );
298
299           # find all people named Dave, not covering Davids
300           # will return a resultset
301           my $daves = $mcpan->author( { name => 'Dave *' } );
302
303   OR
304       If you want to do a more complicated query that has an OR condition,
305       such as "this or that", you can use the following syntax with the
306       "either" key:
307
308           # any author named "Dave" or "David"
309           my $daves = $mcpan->author( {
310               either => [
311                   { name => 'Dave *'  },
312                   { name => 'David *' },
313               ]
314           } );
315
316   AND
317       If you want to do a more complicated query that has an AND condition,
318       such as "this and that", you can use the following syntax with the
319       "all" key:
320
321           # any users named 'John' with a Gmail account
322           my $johns = $mcpan->author( {
323               all => [
324                   { name  => 'John *'     },
325                   { email => '*gmail.com' },
326               ]
327           } );
328
329       If you want to do something even more complicated, You can also nest
330       your queries, e.g.:
331
332           my $gmail_daves_or_cpan_sams = $mcpan->author( {
333               either => [
334                   { all => [ { name => 'Dave *'  },
335                              { email => '*gmail.com' } ]
336                   },
337                   { all => [ { name => 'Sam *' },
338                              { email => '*cpan.org' } ]
339                   },
340               ],
341           } );
342
343   NOT
344       If you want to filter out some of the results of an either/all query
345       adding a NOT filter condition, such as "not these", you can use the
346       following syntax with the "not" key:
347
348           # any author named "Dave" or "David"
349           my $daves = $mcpan->author( {
350               either => [
351                   { name => 'Dave *'  },
352                   { name => 'David *' },
353               ],
354               not => [
355                   { email => '*gmail.com' },
356               ],
357           } );
358

DESIGN

360       This module has three purposes:
361
362       ·   Provide 100% of the MetaCPAN API
363
364           This module will be updated regularly on every MetaCPAN API change,
365           and intends to provide the user with as much of the API as
366           possible, no shortcuts. If it's documented in the API, you should
367           be able to do it.
368
369           Because of this design decision, this module has an official
370           MetaCPAN namespace with the blessing of the MetaCPAN developers.
371
372           Notice this module currently only provides the beta API, not the
373           old soon-to-be-deprecated API.
374
375       ·   Be lightweight, to allow flexible usage
376
377           While many modules would help make writing easier, it's important
378           to take into account how they affect your compile-time, run-time,
379           overall memory consumption, and CPU usage.
380
381           By providing a slim interface implementation, more users are able
382           to use this module, such as long-running processes (like daemons),
383           CLI or GUI applications, cron jobs, and more.
384
385       ·   DWIM
386
387           While it's possible to access the methods defined by the API spec,
388           there's still a matter of what you're really trying to achieve. For
389           example, when searching for "Dave", you want to find both Dave
390           Cross and Dave Rolsky (and any other Dave), but you also want to
391           search for a PAUSE ID of DAVE, if one exists.
392
393           This is where DWIM comes in. This module provides you with
394           additional generic methods which will try to do what they think you
395           want.
396
397           Of course, this does not prevent you from manually using the API
398           methods. You still have full control over that, if that's what you
399           wish.
400
401           You can (and should) read up on the general methods, which will
402           explain how their DWIMish nature works, and what searches they run.
403

AUTHORS

405       ·   Sawyer X <xsawyerx@cpan.org>
406
407       ·   Mickey Nasriachi <mickey@cpan.org>
408

410       This software is copyright (c) 2016 by Sawyer X.
411
412       This is free software; you can redistribute it and/or modify it under
413       the same terms as the Perl 5 programming language system itself.
414
415
416
417perl v5.30.1                      2020-01-30               MetaCPAN::Client(3)
Impressum