1MetaCPAN::Client(3) User Contributed Perl Documentation MetaCPAN::Client(3)
2
6 MetaCPAN::Client - A comprehensive, DWIM-featured client to the
7 MetaCPAN API
8
10 version 2.030000
11
13 # simple usage
14 my $mcpan = MetaCPAN::Client->new();
15 my $author = $mcpan->author('XSAWYERX');
16 my $dist = $mcpan->distribution('MetaCPAN-Client');
17 # 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 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 # now $mcpan caches results
36
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
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 ua
49 If provided, MetaCPAN::Client::Request will use the user agent object
50 instead of the default, which is HTTP::Tiny.
51 Then it can be used to fetch the user agent object used by
53 MetaCPAN::Client::Request.
54 domain
56 If given, will be used to alter the API domain.
57 debug
59 If given, errors will include some low-level detailed message.
60
62 author
63 my $author = $mcpan->author('XSAWYERX');
64 my $author = $mcpan->author($search_spec);
65 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 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 cover
76 my $cover = $mcpan->cover('Moose-2.2007');
77 Returns a MetaCPAN::Client::Cover object.
79 distribution
81 my $dist = $mcpan->distribution('MetaCPAN-Client');
82 my $dist = $mcpan->distribution($search_spec);
83 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 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 file
94 Returns a MetaCPAN::Client::File object.
95 favorite
97 my $favorite = $mcpan->favorite({ distribution => 'Moose' });
98 Returns a MetaCPAN::Client::ResultSet object containing
100 MetaCPAN::Client::Favorite results.
101 rating
103 my $rating = $mcpan->rating({ distribution => 'Moose' });
104 Returns a MetaCPAN::Client::ResultSet object containing
106 MetaCPAN::Client::Rating results.
107 release
109 my $release = $mcpan->release('MetaCPAN-Client');
110 my $release = $mcpan->release($search_spec);
111 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 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 mirror
122 my $mirror = $mcpan->mirror('kr.freebsd.org');
123 Returns a MetaCPAN::Client::Mirror object.
125 module
127 my $module = $mcpan->module('MetaCPAN::Client');
128 my $module = $mcpan->module($search_spec);
129 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 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 package
140 my $package = $mcpan->package('MooseX::Types');
141 Returns a MetaCPAN::Client::Package object.
143 permission
145 my $permission = $mcpan->permission('MooseX::Types');
146 Returns a MetaCPAN::Client::Permission object.
148 reverse_dependencies
150 my $deps = $mcpan->reverse_dependencies('Search::Elasticsearch');
151 all MetaCPAN::Client::Release objects of releases that are directly
153 dependent on a given module, returned as MetaCPAN::Client::ResultSet.
154 rev_deps
156 Alias to "reverse_dependencies" described above.
157 autocomplete
159 my $ac = $mcpan->autocomplete('Danc');
160 Call the search/autocomplete endpoint with a query string.
162 Returns an array reference.
164 autocomplete_suggest
166 my $ac = $mcpan->autocomplete_suggest('Moo');
167 Call the search/autocomplete/suggest endpoint with a query string.
169 Returns an array reference.
171 recent
173 my $recent = $mcpan->recent(10);
174 my $recent = $mcpan->recent('today');
175 return the latest N releases, or all releases from today.
177 returns a MetaCPAN::Client::ResultSet of MetaCPAN::Client::Release.
179 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 my $pod = $mcpan->pod('Moo')->html;
186 my $pod = $mcpan->pod('Moo', { url_prefix => $prefix })->html;
187 download_url
189 Retrieve information from the 'download_url' endpoint
190 my $download_url = $mcpan->download_url($distro, [$version_or_range, $dev]);
192 # request the last available version
194 my $download_url = $mcpan->download_url('Moose');
195 # request an older version
197 my $download_url = $mcpan->download_url('Moose', '1.01');
198 # 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 Range operators are '== != <= >= < > !'. You can use a comma ',' to
204 add multiple rules.
205 # requesting dev release
207 my $download_url = $mcpan->download_url('Moose', '>1.01', 1);
208 Returns a MetaCPAN::Client::DownloadURL object
210 all
212 Retrieve all matches for authors/modules/distributions/favorites or
213 releases.
214 my $all_releases = $mcpan->all('releases')
216 When called with a second parameter containing a hash ref, will support
218 the following keys:
219 fields
221 See SEARCH PARAMS.
223 my $all_releases = $mcpan->all('releases', { fields => [...] })
225 _source
227 See SEARCH PARAMS.
229 my $all_releases = $mcpan->all('releases', { _source => [...] })
231 es_filter
233 Pass a raw Elasticsearch filter structure to reduce the number of
235 elements returned by the query.
236 my $some_releases = $mcpan->all('releases', { es_filter => {...} })
238 BUILDARGS
240 Internal construction wrapper. Do not use.
241
243 Most searches take params as an optional hash-ref argument. these
244 params will be passed to the search action.
245 In non-scrolled searches, 'fields' filter is the only supported
247 parameter ATM.
248 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 my $module = $mcpan->module('Moose', { fields => "version,author" });
254 my $module = $mcpan->module('Moose', { fields => [qw/version author/] });
255 _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 Some fields are not indexed in Elasticsearch but stored as part of the
262 entire document.
263 These fields can still be read, but without the internal Elasticsearch
265 optimizations and the server will internally read the whole document.
266 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 my $module = $mcpan->all('releases', { _source => "stat" });
272 scroller_time
274 Note: please use with caution.
275 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 my $module = $mcpan->all('releases', { scroller_time => '3m' });
283 scroller_size
285 Note: please use with caution.
286 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 my $module = $mcpan->all('releases', { scroller_size => 500 });
293 sort
295 Pass a raw Elasticsearch sort specification for the query.
297 my $some_releases = $mcpan->all('releases', { sort => [{ date => { order => 'desc' } }] })
299 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
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 Basic search specs just contain a hash of keys and values:
309 my $author = $mcpan->author( { name => 'Micha Nasriachi' } );
311 # the following is the same as ->author('MICKEY')
313 my $author = $mcpan->author( { pauseid => 'MICKEY' } );
314 # find all people named Dave, not covering Davids
316 # will return a resultset
317 my $daves = $mcpan->author( { name => 'Dave *' } );
318 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 # any author named "Dave" or "David"
325 my $daves = $mcpan->author( {
326 either => [
327 { name => 'Dave *' },
328 { name => 'David *' },
329 ]
330 } );
331 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 # 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 Or, to get either the given version of a release, or the latest:
346 my $releases = $mcpan->release( {
348 all => [
349 { distribution => 'GraphViz2' },
350 ($version ? { version => $version } : { status => 'latest' }),
351 ],
352 } );
353 If you want to do something even more complicated, You can also nest
355 your queries, e.g.:
356 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 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 # 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
385 This module has three purposes:
386 • Provide 100% of the MetaCPAN API
388 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 Because of this design decision, this module has an official
395 MetaCPAN namespace with the blessing of the MetaCPAN developers.
396 Notice this module currently only provides the beta API, not the
398 old soon-to-be-deprecated API.
399 • Be lightweight, to allow flexible usage
401 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 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 • DWIM
411 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 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 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 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
430 • Sawyer X <xsawyerx@cpan.org>
431 • Mickey Nasriachi <mickey@cpan.org>
433
435 This software is copyright (c) 2016 by Sawyer X.
436 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.
439perl v5.38.0 2023-07-20 MetaCPAN::Client(3)