|
NAMEMetaCPAN::Client - A comprehensive, DWIM-featured client to the MetaCPAN APIVERSIONversion 2.029000SYNOPSIS# simple usage my $mcpan = MetaCPAN::Client->new(); my $author = $mcpan->author('XSAWYERX'); my $dist = $mcpan->distribution('MetaCPAN-Client'); # 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 => 'File', root_dir => '/tmp/metacpan-cache', ), ), ), ); # now $mcpan caches results DESCRIPTIONThis is a hopefully-complete API-compliant client to MetaCPAN (<https://metacpan.org>) with DWIM capabilities, to make your life easier.ATTRIBUTESrequestInternal 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.uaIf provided, MetaCPAN::Client::Request will use the user agent object instead of the default, which is HTTP::Tiny.Then it can be used to fetch the user agent object used by MetaCPAN::Client::Request. domainIf given, will be used to alter the API domain.debugIf given, errors will include some low-level detailed message.METHODSauthormy $author = $mcpan->author('XSAWYERX'); my $author = $mcpan->author($search_spec); Finds an author by either its PAUSE ID or by a search spec defined by a hash reference. Since it is common to many other searches, it is explained below under "SEARCH SPEC". Returns a MetaCPAN::Client::Author object on a simple search (PAUSE ID), or a MetaCPAN::Client::ResultSet object propagated with MetaCPAN::Client::Author objects on a complex (search spec based) search. covermy $cover = $mcpan->cover('Moose-2.2007'); Returns a MetaCPAN::Client::Cover object. distributionmy $dist = $mcpan->distribution('MetaCPAN-Client'); my $dist = $mcpan->distribution($search_spec); 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 "SEARCH SPEC". Returns a MetaCPAN::Client::Distribution object on a simple search (distribution name), or a MetaCPAN::Client::ResultSet object propagated with MetaCPAN::Client::Distribution objects on a complex (search spec based) search. fileReturns a MetaCPAN::Client::File object.favoritemy $favorite = $mcpan->favorite({ distribution => 'Moose' }); Returns a MetaCPAN::Client::ResultSet object containing MetaCPAN::Client::Favorite results. ratingmy $rating = $mcpan->rating({ distribution => 'Moose' }); Returns a MetaCPAN::Client::ResultSet object containing MetaCPAN::Client::Rating results. releasemy $release = $mcpan->release('MetaCPAN-Client'); my $release = $mcpan->release($search_spec); 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 "SEARCH SPEC". Returns a MetaCPAN::Client::Release object on a simple search (release name), or a MetaCPAN::Client::ResultSet object propagated with MetaCPAN::Client::Release objects on a complex (search spec based) search. mirrormy $mirror = $mcpan->mirror('kr.freebsd.org'); Returns a MetaCPAN::Client::Mirror object. modulemy $module = $mcpan->module('MetaCPAN::Client'); my $module = $mcpan->module($search_spec); 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 "SEARCH SPEC". Returns a MetaCPAN::Client::Module object on a simple search (module name), or a MetaCPAN::Client::ResultSet object propagated with MetaCPAN::Client::Module objects on a complex (search spec based) search. packagemy $package = $mcpan->package('MooseX::Types'); Returns a MetaCPAN::Client::Package object. permissionmy $permission = $mcpan->permission('MooseX::Types'); Returns a MetaCPAN::Client::Permission object. reverse_dependenciesmy $deps = $mcpan->reverse_dependencies('Search::Elasticsearch'); all MetaCPAN::Client::Release objects of releases that are directly dependent on a given module, returned as MetaCPAN::Client::ResultSet. rev_depsAlias to "reverse_dependencies" described above.autocompletemy $ac = $mcpan->autocomplete('Danc'); Call the search/autocomplete endpoint with a query string. Returns an array reference. autocomplete_suggestmy $ac = $mcpan->autocomplete_suggest('Moo'); Call the search/autocomplete/suggest endpoint with a query string. Returns an array reference. recentmy $recent = $mcpan->recent(10); my $recent = $mcpan->recent('today'); return the latest N releases, or all releases from today. returns a MetaCPAN::Client::ResultSet of MetaCPAN::Client::Release. podGet POD for given file/module name. returns a MetaCPAN::Client::Pod object, which supports various output formats (html, plain, x_pod & x_markdown).my $pod = $mcpan->pod('Moo')->html; my $pod = $mcpan->pod('Moo', { url_prefix => $prefix })->html; download_urlRetrieve information from the 'download_url' endpointmy $download_url = $mcpan->download_url($distro, [$version_or_range, $dev]); # request the last available version my $download_url = $mcpan->download_url('Moose'); # request an older version my $download_url = $mcpan->download_url('Moose', '1.01'); # using a range my $download_url = $mcpan->download_url('Moose', '<=1.01'); my $download_url = $mcpan->download_url('Moose', '>1.01,<=2.00'); Range operators are '== != <= >= < > !'. You can use a comma ',' to add multiple rules. # requesting dev release my $download_url = $mcpan->download_url('Moose', '>1.01', 1); Returns a MetaCPAN::Client::DownloadURL object allRetrieve all matches for authors/modules/distributions/favorites or releases.my $all_releases = $mcpan->all('releases') When called with a second parameter containing a hash ref, will support the following keys: fields See SEARCH PARAMS. my $all_releases = $mcpan->all('releases', { fields => [...] }) _source See SEARCH PARAMS. my $all_releases = $mcpan->all('releases', { _source => [...] }) es_filter Pass a raw Elasticsearch filter structure to reduce the number of elements returned by the query. my $some_releases = $mcpan->all('releases', { es_filter => {...} }) BUILDARGSInternal construction wrapper. Do not use.SEARCH PARAMSMost searches take params as an optional hash-ref argument. these params will be passed to the search action.In non-scrolled searches, 'fields' filter is the only supported parameter ATM. fieldsFilter the fields to reduce the amount of data pulled from MetaCPAN. can be passed as a csv list or an array ref.my $module = $mcpan->module('Moose', { fields => "version,author" }); my $module = $mcpan->module('Moose', { fields => [qw/version author/] }); _sourceNote: 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.Some fields are not indexed in Elasticsearch but stored as part of the entire document. These fields can still be read, but without the internal Elasticsearch optimizations and the server will internally read the whole document. 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) my $module = $mcpan->all('releases', { _source => "stat" }); scroller_timeNote: please use with caution.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). my $module = $mcpan->all('releases', { scroller_time => '3m' }); scroller_sizeNote: please use with caution.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. my $module = $mcpan->all('releases', { scroller_size => 500 }); sort Pass a raw Elasticsearch sort specification for the query. my $some_releases = $mcpan->all('releases', { sort => [{ date => { order => 'desc' } }] }) Note: this param and is a bit too specific to Elasticsearch. Just like "es_filter", only use this if you know what you're dealing with. SEARCH SPECThe hash-based search spec is common to many searches. It is quite feature-rich and allows you to disambiguate different types of searches.Basic search specs just contain a hash of keys and values: my $author = $mcpan->author( { name => 'Micha Nasriachi' } ); # the following is the same as ->author('MICKEY') my $author = $mcpan->author( { pauseid => 'MICKEY' } ); # find all people named Dave, not covering Davids # will return a resultset my $daves = $mcpan->author( { name => 'Dave *' } ); ORIf you want to do a more complicated query that has an OR condition, such as "this or that", you can use the following syntax with the "either" key:# any author named "Dave" or "David" my $daves = $mcpan->author( { either => [ { name => 'Dave *' }, { name => 'David *' }, ] } ); ANDIf you want to do a more complicated query that has an AND condition, such as "this and that", you can use the following syntax with the "all" key:# any users named 'John' with a Gmail account my $johns = $mcpan->author( { all => [ { name => 'John *' }, { email => '*gmail.com' }, ] } ); Or, to get either the given version of a release, or the latest: my $releases = $mcpan->release( { all => [ { distribution => 'GraphViz2' }, ($version ? { version => $version } : { status => 'latest' }), ], } ); If you want to do something even more complicated, You can also nest your queries, e.g.: my $gmail_daves_or_cpan_sams = $mcpan->author( { either => [ { all => [ { name => 'Dave *' }, { email => '*gmail.com' } ] }, { all => [ { name => 'Sam *' }, { email => '*cpan.org' } ] }, ], } ); NOTIf you want to filter out some of the results of an either/all query adding a NOT filter condition, such as "not these", you can use the following syntax with the "not" key:# any author named "Dave" or "David" my $daves = $mcpan->author( { either => [ { name => 'Dave *' }, { name => 'David *' }, ], not => [ { email => '*gmail.com' }, ], } ); DESIGNThis module has three purposes:
AUTHORS
COPYRIGHT AND LICENSEThis software is copyright (c) 2016 by Sawyer X.This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
Visit the GSP FreeBSD Man Page Interface. |