metacpan-client

Return a LMetaCPAN::Client::Release object on a simple search (release name),
or a LMetaCPAN::Client::ResultSet object propagated with
LMetaCPAN::Client::Release objects on a complex (L<search spec based|/“SEARCH SPEC”>) search.

=head2 mirror

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

Returns a LMetaCPAN::Client::Mirror object.

=head2 reverse_dependencies

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

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

=head2 rev_deps

Alias to C<reverse_dependencies> described above.

=head2 recent

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

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

returns a LMetaCPAN::Client::ResultSet of LMetaCPAN::Client::Release.

=head2 pod

Get POD for given file/module name.
returns a LMetaCPAN::Client::Pod object, which supports various output
formats (html, plain, x_pod & x_markdown).

my $pod = $mcpan->pod('Moo')->html;

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

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

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

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 xsawyerx@cpan.org

=item *

Mickey Nasriachi mickey@cpan.org

=back

=head1 COPYRIGHT AND LICENSE

This software is copyright © 2015 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