NAME

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

VERSION

version 1.001000

SYNOPSIS

    # simple usage
    my $mcpan  = MetaCPAN::Client->new();
    my $author = $mcpan->author('XSAWYERX');
    my $dist   = $mcpan->distribuion('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

DESCRIPTION

This is a hopefully-complete API-compliant client to MetaCPAN (https://metacpan.org) with DWIM capabilities, to make your life easier.

ATTRIBUTES

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.

METHODS

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 SEARCH SPEC.

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

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 SEARCH SPEC.

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

distribution

    my $dist = $mcpan->dist('MetaCPAN-Client');
    my $dist = $mcpan->dist($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.

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

file

Return a MetaCPAN::Client::File object.

favorite

Return a MetaCPAN::Client::Favorite object.

rating

Return a MetaCPAN::Client::Rating object.

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 SEARCH SPEC.

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

pod

Not implemented yet.

SEARCH SPEC

The hash-based search spec is common to many searches. It is quite feature-rich and allows to disambiguate different types of searches.

Simple

Simple searches just contain 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 *' } );

OR

If 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 *' },
        ]
    } );

AND

If 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' },
        ]
    } );

DESIGN

This module has three purposes:

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

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

  • 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 "Dave", you want to find both Dave Cross and Dave Rolsky (and any other Dave), but you also want to search for a PAUSE ID of DAVE, 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.

AUTHORS

  • Sawyer X <xsawyerx@cpan.org>

  • Mickey Nasriachi <mickey@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 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.