Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/metacpan/metacpan-client

Home of the official MetaCPAN Perl API client.
https://github.com/metacpan/metacpan-client

cpan metacpan perl

Last synced: 2 months ago
JSON representation

Home of the official MetaCPAN Perl API client.

Awesome Lists containing this project

README 

        
=pod



=encoding UTF-8



=head1 NAME



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



=head1 VERSION



version 2.032000



=head1 SYNOPSIS



    # 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



=head1 DESCRIPTION



This is a hopefully-complete API-compliant client to MetaCPAN

(L) with DWIM capabilities, to make your life easier.



=head1 ATTRIBUTES



=head2 request



Internal 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.



=head2 ua



If provided, L will use the user agent object

instead of the default, which is L.



Then it can be used to fetch the user agent object used by

L.



=head2 domain



If given, will be used to alter the API domain.



=head2 debug



If given, errors will include some low-level detailed message.



=head1 METHODS



=head2 author



    my $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 C.



Returns a L object on a simple search (PAUSE ID), or

a L object populated with

L objects on a complex (L) search.



=head2 cover



    my $cover = $mcpan->cover('Moose-2.2007');



Returns a L object.



=head2 distribution



    my $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 C.



Returns a L object on a simple search

(distribution name), or a L object populated with

L objects on a complex (L)

search.



=head2 file



Returns a L object.



=head2 favorite



    my $favorite = $mcpan->favorite({ distribution => 'Moose' });



Returns a L object containing

L results.



=head2 rating



    my $rating = $mcpan->rating({ distribution => 'Moose' });



Returns a L object containing

L results.



=head2 release



    my $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 C.



Returns a L object on a simple search (release name),

or a L object populated with

L objects on a complex (L) search.



=head2 mirror



    my $mirror = $mcpan->mirror('kr.freebsd.org');



Returns a L object.



=head2 module



    my $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 C.



Returns a L object on a simple search (module name), or

a L object populated with

L objects on a complex (L) search.



=head2 package



    my $package = $mcpan->package('MooseX::Types');



Returns a L object.



=head2 permission



    my $permission = $mcpan->permission('MooseX::Types');



Returns a L object.



=head2 reverse_dependencies



    my $deps = $mcpan->reverse_dependencies('Search::Elasticsearch');



all L objects of releases that are directly

dependent on a given module, returned as L.



=head2 rev_deps



Alias to C described above.



=head2 autocomplete



    my $ac = $mcpan->autocomplete('Danc');



Call the search/autocomplete endpoint with a query string.



Returns an array reference.



=head2 autocomplete_suggest



    my $ac = $mcpan->autocomplete_suggest('Moo');



Call the search/autocomplete/suggest endpoint with a query string.



Returns an array reference.



=head2 recent



    my $recent = $mcpan->recent(10);

    my $recent = $mcpan->recent('today');



return the latest N releases, or all releases from today.



returns a L of L.



=head2 pod



Get POD for given file/module name.

returns a L 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;



=head2 download_url



Retrieve information from the 'download_url' endpoint



    my $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 L object



=head2 all



Retrieve 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:



=head3 fields



See SEARCH PARAMS.



   my $all_releases = $mcpan->all('releases', { fields => [...] })



=head3 _source



See SEARCH PARAMS.



   my $all_releases = $mcpan->all('releases', { _source => [...] })



=head3 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 => {...} })



=head2 BUILDARGS



Internal construction wrapper. Do not use.



=head1 SEARCH PARAMS



Most 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.



=head2 fields



Filter 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/] });



=head2 _source



Note: 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" });



=head2 scroller_time



Note: 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' });



=head2 scroller_size



Note: 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 });



=head3 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

L, only use this if you know what you're dealing with.



=head1 SEARCH SPEC



The 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 *' } );



=head2 OR



If you want to do a more complicated query that has an I condition,

such as "this or that", you can use the following syntax with the C

key:



    # any author named "Dave" or "David"

    my $daves = $mcpan->author( {

        either => [

            { name => 'Dave *'  },

            { name => 'David *' },

        ]

    } );



=head2 AND



If you want to do a more complicated query that has an I condition,

such as "this and that", you can use the following syntax with the C

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' } ]

            },

        ],

    } );



=head2 NOT



If you want to filter out some of the results of an either/all query

adding a I filter condition, such as "not these", you can use the

following syntax with the C key:



    # any author named "Dave" or "David"

    my $daves = $mcpan->author( {

        either => [

            { name => 'Dave *'  },

            { name => 'David *' },

        ],

        not => [

            { email => '*gmail.com' },

        ],

    } );



=head1 DESIGN



This module has three purposes:



=over 4



=item * Provide 100% of the MetaCPAN API



This module will be updated regularly on every MetaCPAN API change, and intends

to provide the user with as much of the API as possible, no shortcuts. If it's

documented in the API, you should be able to do it.



Because of this design decision, this module has an official MetaCPAN namespace

with the blessing of the MetaCPAN developers.



Notice this module currently only provides the beta API, not the old

soon-to-be-deprecated API.



=item * Be lightweight, to allow flexible usage



While many modules would help make writing easier, it's important to take into

account how they affect your compile-time, run-time, overall memory

consumption, and CPU usage.



By providing a slim interface implementation, more users are able to use this

module, such as long-running processes (like daemons), CLI or GUI applications,

cron jobs, and more.



=item * DWIM



While it's possible to access the methods defined by the API spec, there's still

a matter of what you're really trying to achieve. For example, when searching

for I<"Dave">, you want to find both I and I (and any

other I), but you also want to search for a PAUSE ID of I, if one

exists.



This is where DWIM comes in. This module provides you with additional generic

methods which will try to do what they think you want.



Of course, this does not prevent you from manually using the API methods. You

still have full control over that, if that's what you wish.



You can (and should) read up on the general methods, which will explain how

their DWIMish nature works, and what searches they run.



=back



=head1 AUTHORS



=over 4



=item *



Sawyer X 



=item *



Mickey Nasriachi 



=back



=head1 COPYRIGHT AND LICENSE



This 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.



=cut