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

VERSION
    version 1.028003

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(
          version => 'v1',

          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.

  ua
    If 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.

  version
    API version (supported: 'v0', 'v1')

    This will also set default value to your 'domain' (unless given)

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

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

    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
        my $favorite = $mcpan->favorite({ distribution => 'Moose' });

    Return a MetaCPAN::Client::Favorite object.

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

    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.

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

    Returns a MetaCPAN::Client::Mirror object.

  reverse_dependencies
        my $deps = $mcpan->reverse_dependencies('ElasticSearch');

    all MetaCPAN::Client::Release objects of releases that are dependent on
    a given module, returned as MetaCPAN::Client::ResultSet.

  rev_deps
    Alias to "reverse_dependencies" described above.

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

  pod
    Get 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;

  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:

  download_url
    Retrieve information from the 'download_url' endpoint (v1 only)

        my $download_url = $mcpan->download_url('Moose')

    Returns a MetaCPAN::Client::DownloadURL object

   fields
    See SEARCH PARAMS.

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

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

  BUILDARGS
    Internal construction wrapper. Do not use.

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.

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

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.

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

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

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

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

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