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.028000
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($distro, [$version_or_range, $dev]);
192
193           # request the last available version
194           my $download_url = $mcpan->download_url('Moose');
195
196           # request an older version
197           my $download_url = $mcpan->download_url('Moose', '1.01');
198
199           # using a range
200           my $download_url = $mcpan->download_url('Moose', '<=1.01');
201           my $download_url = $mcpan->download_url('Moose', '>1.01,<=2.00');
202
203       Range operators are '== != <= >= < > !'.  You can use a comma ',' to
204       add multiple rules.
205
206           # requesting dev release
207           my $download_url = $mcpan->download_url('Moose', '>1.01', 1);
208
209       Returns a MetaCPAN::Client::DownloadURL object
210
211   all
212       Retrieve all matches for authors/modules/distributions/favorites or
213       releases.
214
215           my $all_releases = $mcpan->all('releases')
216
217       When called with a second parameter containing a hash ref, will support
218       the following keys:
219
220       fields
221
222       See SEARCH PARAMS.
223
224          my $all_releases = $mcpan->all('releases', { fields => [...] })
225
226       _source
227
228       See SEARCH PARAMS.
229
230          my $all_releases = $mcpan->all('releases', { _source => [...] })
231
232       es_filter
233
234       Pass a raw Elasticsearch filter structure to reduce the number of
235       elements returned by the query.
236
237           my $some_releases = $mcpan->all('releases', { es_filter => {...} })
238
239   BUILDARGS
240       Internal construction wrapper. Do not use.
241

SEARCH PARAMS

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

SEARCH SPEC

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

DESIGN

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

AUTHORS

421       ·   Sawyer X <xsawyerx@cpan.org>
422
423       ·   Mickey Nasriachi <mickey@cpan.org>
424
426       This software is copyright (c) 2016 by Sawyer X.
427
428       This is free software; you can redistribute it and/or modify it under
429       the same terms as the Perl 5 programming language system itself.
430
431
432
433perl v5.32.0                      2020-08-24               MetaCPAN::Client(3)
Impressum