NAME

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

VERSION

    version 2.028000

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

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.

 domain

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

 debug

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

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.

    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.

 cover

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

    Returns a MetaCPAN::Client::Cover object.

 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.

    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.

 file

    Returns a MetaCPAN::Client::File object.

 favorite

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

    Returns a MetaCPAN::Client::ResultSet object containing
    MetaCPAN::Client::Favorite results.

 rating

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

    Returns a MetaCPAN::Client::ResultSet object containing
    MetaCPAN::Client::Rating results.

 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.

    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.

 mirror

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

    Returns a MetaCPAN::Client::Mirror object.

 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.

    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.

 package

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

    Returns a MetaCPAN::Client::Package object.

 permission

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

    Returns a MetaCPAN::Client::Permission object.

 reverse_dependencies

        my $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_deps

    Alias to reverse_dependencies described above.

 autocomplete

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

    Call the search/autocomplete endpoint with a query string.

    Returns an array reference.

 autocomplete_suggest

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

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

    Returns an array reference.

 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;

 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 MetaCPAN::Client::DownloadURL object

 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:

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

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

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

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

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

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

 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.