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.030000
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 populated 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 populated
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 populated 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 populated 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       Or, to get either the given version of a release, or the latest:
346
347           my $releases = $mcpan->release( {
348               all => [
349                 { distribution => 'GraphViz2' },
350                 ($version ? { version => $version } : { status => 'latest' }),
351               ],
352           } );
353
354       If you want to do something even more complicated, You can also nest
355       your queries, e.g.:
356
357           my $gmail_daves_or_cpan_sams = $mcpan->author( {
358               either => [
359                   { all => [ { name => 'Dave *'  },
360                              { email => '*gmail.com' } ]
361                   },
362                   { all => [ { name => 'Sam *' },
363                              { email => '*cpan.org' } ]
364                   },
365               ],
366           } );
367
368   NOT
369       If you want to filter out some of the results of an either/all query
370       adding a NOT filter condition, such as "not these", you can use the
371       following syntax with the "not" key:
372
373           # any author named "Dave" or "David"
374           my $daves = $mcpan->author( {
375               either => [
376                   { name => 'Dave *'  },
377                   { name => 'David *' },
378               ],
379               not => [
380                   { email => '*gmail.com' },
381               ],
382           } );
383

DESIGN

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

AUTHORS

430       •   Sawyer X <xsawyerx@cpan.org>
431
432       •   Mickey Nasriachi <mickey@cpan.org>
433
435       This software is copyright (c) 2016 by Sawyer X.
436
437       This is free software; you can redistribute it and/or modify it under
438       the same terms as the Perl 5 programming language system itself.
439
440
441
442perl v5.38.0                      2023-07-20               MetaCPAN::Client(3)
Impressum