NAME
Net::API::CPAN - Meta CPAN API
SYNOPSIS
use Net::API::CPAN;
my $cpan = Net::API::CPAN->new(
api_version => 1,
ua => HTTP::Promise->new( %options ),
debug => 4,
) || die( Net::API::CPAN->error, "\n" );
$cpan->api_uri( 'https://api.example.org' );
my $uri = $cpan->api_uri;
$cpan->api_version(1);
my $version = $cpan->api_version;
VERSION
v0.1.0
DESCRIPTION
"Net::API::CPAN" is a client to issue queries to the MetaCPAN REST API.
Make sure to check out the "TERMINOLOGY" section for the exact meaning
of key words used in this documentation.
CONSTRUCTOR
new
This instantiates a new Net::API::CPAN object. This accepts the
following options, which can later also be set using their associated
method.
* "api_version"
Integer. This is the "CPAN" API version, and defaults to 1.
* "debug"
Integer. This sets the debugging level. Defaults to 0. The higher
and the more verbose will be the debugging output on STDERR.
* "ua"
An optional HTTP::Promise object. If not provided, one will be
instantiated automatically.
METHODS
api_uri
Sets or gets the "CPAN" API "URI" to use. This defaults to the
"Net::API::CPAN" constant "API_URI" followed by the API version, such
as:
https://fastapi.metacpan.org/v1
This returns an URI object.
api_version
Sets or gets the "CPAN" API version. As of 2023-09-01, this can only 1
This returns a scalar object
cache_file
Sets or gets a cache file path to use instead of issuing the "HTTP"
request. This affects how "fetch" works since it does not issue an
actual "HTTP" request, but does not change the rest of the workflow.
Returns a file object or "undef" if nothing was set.
fetch
This takes an object type, such as "author", "release", "file", etc, and
the following options and performs an "HttP" request to the remote
MetaCPAN REST API and return the appropriate data or object.
If an error occurs, this set an error object and return "undef" in
scalar context, and an empty list in list context.
* "class"
One of "Net::API::CPAN" classes, such as Net::API::CPAN::Author
* "endpoint"
The endpoint to access, such as "/author"
* "headers"
An array reference of headers with their corresponding values.
* "method"
The "HTTP" method to use. This defaults to "GET". This is case
insensitive.
* "payload"
The "POST" payload to send to the remote MetaCPAN API. It must be
already encoded in "UTF-8".
* "postprocess"
A subroutine reference or an anonymous subroutine that will be call
backed, taking the data received as the sole argument and returning
the modified data.
* "query"
An hash reference of key-value pairs representing the query string
elements. This will be passed to "query_form" in URI, so make sure
to check what data structure is acceptable by URI
* "request"
An HTTP::Promise::Request object.
http_request
The latest HTTP::Promise::Request issued to the remote MetaCPAN API
server.
http_response
The latest HTTP::Promise::Response received from the remote MetaCPAN API
server.
json
Returns a new JSON object.
new_filter
This instantiates a new Net::API::CPAN::Filter, passing whatever
arguments were received, and setting the debugging mode too.
API METHODS
activity
# Get all the release activity for author OALDERS in the last 24 months
my $activity_obj = $cpan->activity(
author => 'OALDERS',
# distribution => 'HTTP-Message',
# module => 'HTTP::Message',
interval => '1M',
) || die( "Error with code: ", $cpan->error->code, " and message: ", $cpan->error->message );
# Get all the release activity that depend on HTTP::Message in the last 24 months
my $activity_obj = $cpan->activity(
# author => 'OALDERS',
# distribution => 'HTTP-Message',
module => 'HTTP::Message',
interval => '1M',
) || die( "Error with code: ", $cpan->error->code, " and message: ", $cpan->error->message );
This method is used to query the CPAN REST API for the release activity
for all, or for a given "author", or a given "distribution", or a given
"module" dependency. An optional aggregation interval can be stipulated
with "res" and it defaults to "1w" (set by the API).
* "author" -> "/activity"
If a string is provided representing a specific "author", this will
issue a query to the API endpoint "/activity" to retrieve the
release activity for that "author" for the past 24 months for the
specified author, such as:
/activity?author=OALDERS
For example:
my $activity_obj = $cpan->activity(
author => 'OALDERS',
interval => '1M',
) || die( "Error with code: ", $cpan->error->code, " and message: ", $cpan->error->message );
This would return, upon success, a Net::API::CPAN::Activity object
containing release activity for the "author" "OALDERS" for the past
24 months.
Note that the value of the "author" is case insensitive and will
automatically be transformed in upper case, so you could also do:
Possible options are:
* "interval"
Specifies an interval for the aggregate value. Defaults to
"1w", which is 1 week. See ElasticSearch document
<https://www.elastic.co/guide/en/elasticsearch/reference/2.4
/query-dsl-range-query.html#_date_format_in_range_queries>
for the proper value to use as interval.
* "new"
Limit the result to newly issued distributions.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Factivity%3Fauthor%3DOALDERS>
to see the data returned by the CPAN REST API.
* "distribution" -> "/activity"
If a string is provided representing a specific "distribution", this
will issue a query to the API endpoint "/activity" to retrieve the
release activity for that "distribution" for the past 24 months for
the specified "distribution", such as:
/activity?distribution=HTTP-Message
For example:
my $activity_obj = $cpan->activity(
distribution => 'HTTP-Message',
interval => '1M',
) || die( "Error with code: ", $cpan->error->code, " and message: ", $cpan->error->message );
This would return, upon success, a Net::API::CPAN::Activity object
containing release activity for the "distribution" "HTTP-Message"
for the past 24 months.
Possible options are:
* "interval"
Specifies an interval for the aggregate value. Defaults to
"1w", which is 1 week. See ElasticSearch document
<https://www.elastic.co/guide/en/elasticsearch/reference/2.4
/query-dsl-range-query.html#_date_format_in_range_queries>
for the proper value to use as interval.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Factivity%3Fdistribution%3DHTT
P-Message> to see the data returned by the CPAN REST API.
* "module" -> "/activity"
If a string is provided representing a specific "module", this will
issue a query to the API endpoint "/activity" to retrieve the
release activity that have a dependency on that "module" for the
past 24 months, such as:
/activity?res=1M&module=HTTP::Message
For example:
my $activity_obj = $cpan->activity(
module => 'HTTP::Message',
interval => '1M',
) || die( "Error with code: ", $cpan->error->code, " and message: ", $cpan->error->message );
This would return, upon success, a Net::API::CPAN::Activity object
containing release activity for all the distributions depending on
the "module" "HTTP::Message" for the past 24 months.
Possible options are:
* "interval"
Specifies an interval for the aggregate value. Defaults to
"1w", which is 1 week. See ElasticSearch document
<https://www.elastic.co/guide/en/elasticsearch/reference/2.4
/query-dsl-range-query.html#_date_format_in_range_queries>
for the proper value to use as interval.
* "new"
Limit the result to newly issued distributions.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Factivity%3Fres%3D1M%26module%
3DHTTP%3A%3AMessage> to see the data returned by the CPAN REST API.
* "new" -> "/activity"
If "new" is provided with any value (true or not does not matter),
this will issue a query to the API endpoint "/activity" to retrieve
the new release activity in the past 24 months, such as:
/activity?res=1M&new_dists=n
For example:
my $activity_obj = $cpan->activity(
new => 1,
interval => '1M',
) || die( "Error with code: ", $cpan->error->code, " and message: ", $cpan->error->message );
This would return, upon success, a Net::API::CPAN::Activity object
containing all new distributions release activity for the past 24
months.
Possible options are:
* "interval"
Specifies an interval for the aggregate value. Defaults to
"1w", which is 1 week. See ElasticSearch document
<https://www.elastic.co/guide/en/elasticsearch/reference/2.4
/query-dsl-range-query.html#_date_format_in_range_queries>
for the proper value to use as interval.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Factivity%3Fres%3D1M%26new_dis
ts%3Dn> to see the data returned by the CPAN REST API.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
author
# Retrieves the information details for the specified author
my $author_obj = $cpan->author( 'OALDERS' ) ||
die( "Error with code: ", $cpan->error->code, " and message: ", $cpan->error->message );
# Retrieves author information details for the specified pause IDs
my $list_obj = $cpan->author( [qw( OALDERS NEILB )] ) ||
die( "Error with code: ", $cpan->error->code, " and message: ", $cpan->error->message );
# Queries authors information details
my $list_obj = $cpan->author(
query => 'Olaf',
from => 10,
size => 20,
) || die( $cpan->error );
# Queries authors information details using ElasticSearch format
my $list_obj = $cpan->author( $filter_object ) ||
die( $cpan->error );
# Queries authors information using a prefix
my $list_obj = $cpan->author( prefix => 'O' ) ||
die( $cpan->error );
# Retrieves authors information using their specified IDs
my $list_obj = $cpan->author( user => [qw( FepgBJBZQ8u92eG_TcyIGQ 6ZuVfdMpQzy75_Mazx2_nw )] ) ||
die( $cpan->error );
This method is used to query the CPAN REST API for a specific "author",
a list of "authors", or search an "author" using a query. It takes a
string, an array reference, an hash or alternatively an hash reference
as possible parameters.
* "author" -> "/author/{author}"
If a string is provided representing a specific "author", this will
issue a query to the API endpoint "/author/{author}" to retrieve the
information details for the specified author, such as:
/author/OALDERS
For example:
my $author_obj = $cpan->author( 'OALDERS' ) ||
die( $cpan->error );
This would return, upon success, a Net::API::CPAN::Author object.
Note that the value of the "author" is case insensitive and will
automatically be transformed in upper case, so you could also do:
my $author_obj = $cpan->author( 'OAlders' ) ||
die( $cpan->error );
The following options are also supported:
* "from"
An integer representing the offset starting from 0 within
the total data.
* "size"
An integer representing the size of each page, i.e. how many
results are returned per page. This usually defaults to 10.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fauthor%2FOALDERS> to see the
data returned by the CPAN REST API.
* ["author"] -> "/author/by_ids"
And providing an array reference of "authors" will trigger a query
to the API endpoint "/author/by_ids", such as:
/author/by_ids?id=OALDERS&id=NEILB
For example:
my $list_obj = $cpan->author( [qw( OALDERS NEILB )] ) ||
die( $cpan->error );
This would, upon success, return a Net::API::CPAN::List object of
Net::API::CPAN::Author objects.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fauthor%2Fby_ids%3Fid%3DOALDER
S%26id%3DNEILB> to see the data returned by the CPAN REST API.
* "query" -> "/author"
If the property "query" is provided, this will trigger a simple
search query to the endpoint "/author", such as:
/author?q=Tokyo
For example:
my $list_obj = $cpan->author(
query => 'Tokyo',
from => 10,
size => 10,
) || die( $cpan->error );
will find all "authors" related to Tokyo.
This would, upon success, return a Net::API::CPAN::List object of
Net::API::CPAN::Author objects.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fauthor%3Fq%3DTokyo> to see
the data returned by the CPAN REST API.
* "prefix" -> "/author/by_prefix/{prefix}"
However, if the property "prefix" is provided, this will issue a
query to the endpoint "/author/by_prefix/{prefix}", such as:
/author/by_prefix/O
which will find all "authors" whose Pause ID starts with the
specified prefix; in this example, the letter "O"
For example:
my $list_obj = $cpan->author( prefix => 'O' ) ||
die( $cpan->error );
This would, upon success, return a Net::API::CPAN::List object of
Net::API::CPAN::Author objects.
The following options are also supported:
* "from"
An integer representing the offset starting from 0 within
the total data.
* "size"
An integer representing the size of each page, i.e. how many
results are returned per page. This usually defaults to 10.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fauthor%2Fby_prefix%2FO> to
see the data returned by the CPAN REST API.
* "user" -> "/author/by_user"
And if the property "user" is provided, this will issue a query to
the endpoint "/author/by_user", such as:
/author/by_user?user=FepgBJBZQ8u92eG_TcyIGQ&user=6ZuVfdMpQzy75_Mazx2_nw
which will fetch the information for the authors whose user ID are
"FepgBJBZQ8u92eG_TcyIGQ" and "6ZuVfdMpQzy75_Mazx2_nw" (here
respectively corresponding to the "authors" "OALDERS" and "HAARG")
For example:
my $list_obj = $cpan->author( user => [qw( FepgBJBZQ8u92eG_TcyIGQ 6ZuVfdMpQzy75_Mazx2_nw )] ) ||
die( $cpan->error );
This would, upon success, return a Net::API::CPAN::List object of
Net::API::CPAN::Author objects.
However, note that not all "CPAN" account have a user ID,
surprisingly enough.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fauthor%2Fby_user%3Fuser%3DFep
gBJBZQ8u92eG_TcyIGQ%26user%3D6ZuVfdMpQzy75_Mazx2_nw> to see the data
returned by the CPAN REST API.
* search filter -> "/author/_search"
And if a search filter is passed, this will trigger a more advanced
ElasticSearch query to the endpoint "/author/_search" using the
"HTTP" "POST" method. See the Net::API::CPAN::Filter module on more
details on what granular queries you can execute.
This would, upon success, return a Net::API::CPAN::List object of
Net::API::CPAN::Author objects.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
autocomplete
This takes a string and will issue a query to the endpoint
"/search/autocomplete" to retrieve the result set based on the
autocomplete search query specified, such as:
/search/autocomplete?q=HTTP
For example:
my $list_obj = $cpan->autocomplete( 'HTTP' ) || die( $cpan->error );
This would, upon success, return a Net::API::CPAN::List object of
Net::API::CPAN::File objects.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fsearch%2Fautocomplete%3Fq%3DHTTP>
to see the data returned by the CPAN REST API.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
changes
# Retrieves the specified distribution Changes file content
my $change_obj = $cpan->changes( distribution => 'HTTP-Message' ) ||
die( $cpan->error );
# Retrieves one or more distribution Changes file details using author and release information
my $change_obj = $cpan->changes(
author => 'OALDERS',
release => 'HTTP-Message-6.36'
) || die( $cpan->error );
# Same:
my $change_obj = $cpan->changes( release => 'OALDERS/HTTP-Message-6.36' ) ||
die( $cpan->error );
# With multiple author and releases
my $list_obj = $cpan->changes(
author => [qw( OALDERS NEILB )],
release => [qw( HTTP-Message-6.36 Data-HexDump-0.04 )]
) || die( $cpan->error );
# Same:
my $list_obj = $cpan->changes( release => [qw( OALDERS/HTTP-Message-6.36 NEILB/Data-HexDump-0.04 )] ) ||
die( $cpan->error );
This method is used to query the CPAN REST API for one or more
particular "release"'s "Changes" (or "CHANGES" depending on the release)
file content.
* "distribution" -> "/changes/{distribution}"
If the property "distribution" is provided, this will issue a query
to the endpoint "/changes/{distribution}" to retrieve a distribution
Changes file details, such as:
/changes/HTTP-Message
For example:
my $change_obj = $cpan->changes( distribution => 'HTTP-Message' ) ||
die( $cpan->error );
which will retrieve the "Changes" file information for the latest
"release" of the specified "distribution", and return a
Net::API::CPAN::Changes object upon success.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fchanges%2FHTTP-Message> to
see the data returned by the CPAN REST API.
* "release" -> "/changes/"
* "author" and "release" -> "/changes/{author}/{release}"
If the properties "author" and "release" have been provided or that
the value of the property "release" has the form "author"/"release",
this will issue a query to the endpoint
"/changes/{author}/{release}" to retrieve an author distribution
Changes file details:
/changes/OALDERS/HTTP-Message-6.36
For example:
my $change_obj = $cpan->changes(
author => 'OALDERS',
release => 'HTTP-Message-6.36'
) || die( $cpan->error );
# or
my $change_obj = $cpan->changes( release => 'OALDERS/HTTP-Message-6.36' ) ||
die( $cpan->error );
which will retrieve the "Changes" file information for the specified
"release", and return, upon success, a Net::API::CPAN::Changes
object.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fchanges%2FOALDERS%2FHTTP-Mess
age-6.36> to see the data returned by the CPAN REST API.
* ["author"] and ["release"] -> "/author/by_releases"
And, if both properties "author" and "release" have been provided
and are both an array reference of equal size, this will issue a
query to the endpoint "/author/by_releases" to retrieve one or more
distribution Changes file details using the specified author and
release information, such as:
/changes/by_releases?release=OALDERS%2FHTTP-Message-6.37&release=NEILB%2FData-HexDump-0.04
For example:
my $list_obj = $cpan->changes(
author => [qw( OALDERS NEILB )],
release => [qw( HTTP-Message-6.36 Data-HexDump-0.04 )]
) || die( $cpan->error );
Alternatively, you can provide the property "release" having, as
value, an array reference of "author"/"release", such as:
my $list_obj = $cpan->changes(
release => [qw(
OALDERS/HTTP-Message-6.36
NEILB/Data-HexDump-0.04
)]
) || die( $cpan->error );
which will retrieve the "Changes" file information for the specified
"releases", and return, upon success, a Net::API::CPAN::List object
of Net::API::CPAN::Changes objects.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fchanges%2Fby_releases%3Frelea
se%3DOALDERS%252FHTTP-Message-6.37%26release%3DNEILB%252FData-HexDum
p-0.04> to see the data returned by the CPAN REST API.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
clientinfo
This issue a query to the endpoint "https://clientinfo.metacpan.org" and
retrieves the information of the various base URL.
It returns an hash reference with the following structure:
{
future => {
domain => "https://fastapi.metacpan.org/",
url => "https://fastapi.metacpan.org/v1/",
version => "v1",
},
production => {
domain => "https://fastapi.metacpan.org/",
url => "https://fastapi.metacpan.org/v1/",
version => "v1",
},
testing => {
domain => "https://fastapi.metacpan.org/",
url => "https://fastapi.metacpan.org/v1/",
version => "v1",
},
}
Each of the URL is an URL object.
contributor
# Retrieves a list of module contributed to by the specified PauseID
my $list_obj = $cpan->contributor( author => 'OALDERS' ) ||
die( $cpan->error );
# Retrieves a list of module contributors details
my $list_obj = $cpan->contributor(
author => 'OALDERS'
release => 'HTTP-Message-6.37'
) || die( $cpan->error );
This method is used to query the CPAN REST API for either the list of
"releases" a CPAN account has contributed to, or to get the list of
"contributors" for a specified "release".
* "author" -> "/contributor/by_pauseid/{author}"
If the property "author" is provided, this will issue a query to the
endpoint "/contributor/by_pauseid/{author}" to retrieve a list of
module contributed to by the specified PauseID, such as:
/contributor/by_pauseid/OALDERS
For example:
my $list_obj = $cpan->contributor( author => 'OALDERS' ) ||
die( $cpan->error );
This will, upon success, return a Net::API::CPAN::List object of
Net::API::CPAN::Contributor objects containing the details of the
release to which the specified "author" has contributed.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fcontributor%2Fby_pauseid%2FOA
LDERS> to see the data returned by the CPAN REST API.
* "author" and "release" -> "/contributor/{author}/{release}"
And if the properties "author" and "release" are provided, this will
issue a query to the endpoint "/contributor/{author}/{release}" to
retrieve a list of release contributors details, such as:
/contributor/OALDERS/HTTP-Message-6.36
For example:
my $list_obj = $cpan->contributor(
author => 'OALDERS'
release => 'HTTP-Message-6.37'
) || die( $cpan->error );
This will, upon success, return a Net::API::CPAN::List object of
Net::API::CPAN::Contributor objects containing the specified
"release" information and the "pauseid" of all the "authors" who
have contributed to the specified "release".
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fcontributor%2FOALDERS%2FHTTP-
Message-6.36> to see the data returned by the CPAN REST API.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
cover
This method is used to query the CPAN REST API to the endpoint
"/v1/cover/{release}" to get the "cover" information including
"distribution" name, "release" name, "version" and download "URL", such
as:
/cover/HTTP-Message-6.37
For example:
my $cover_obj = $cpan->cover(
release => 'HTTP-Message-6.37',
) || die( $cpan->error );
It returns, upon success, a Net::API::CPAN::Cover object.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
diff
# Retrieves a diff of two files with output as JSON
my $diff_obj = $cpan->diff(
file1 => 'AcREzFgg3ExIrFTURa0QJfn8nto',
file2 => 'Ies7Ysw0GjCxUU6Wj_WzI9s8ysU',
# Default
accept => 'application/json',
) || die( $cpan->error );
# Retrieves a diff of two files with output as plain text
my $diff_text = $cpan->diff(
file1 => 'AcREzFgg3ExIrFTURa0QJfn8nto',
file2 => 'Ies7Ysw0GjCxUU6Wj_WzI9s8ysU',
# Default
accept => 'text/plain',
) || die( $cpan->error );
# Retrieves a diff of two releases with output as JSON
my $diff_obj = $cpan->diff(
author1 => 'OALDERS',
# This is optional if it is the same
author2 => 'OALDERS',
release1 => 'HTTP-Message-6.35'
release2 => 'HTTP-Message-6.36'
# Default
accept => 'application/json',
) || die( $cpan->error );
# Retrieves a diff of two releases with output as plain text
my $diff_text = $cpan->diff(
author1 => 'OALDERS',
# This is optional if it is the same
author2 => 'OALDERS',
release1 => 'HTTP-Message-6.35'
release2 => 'HTTP-Message-6.36'
# Default
accept => 'text/plain',
) || die( $cpan->error );
# Retrieves a diff of the latest release and its previous version with output as JSON
my $diff_obj = $cpan->diff(
distribution => 'HTTP-Message',
# Default
accept => 'application/json',
) || die( $cpan->error );
# Retrieves a diff of the latest release and its previous version with output as plain text
my $diff_text = $cpan->diff(
distribution => 'HTTP-Message',
# Default
accept => 'text/plain',
) || die( $cpan->error );
This method is used to query the CPAN REST API to get the "diff" output
between 2 files, or 2 releases.
* "file1" and "file2" -> "/diff/file/{file1}/{file2}"
If the properties "file1" and "file2" are provided, this will issue
a query to the endpoint "/diff/file/{file1}/{file2}", such as:
/diff/file/AcREzFgg3ExIrFTURa0QJfn8nto/Ies7Ysw0GjCxUU6Wj_WzI9s8ysU
The result returned will depend on the optional "accept" property,
which is, by default "application/json", but can also be set to
"text/plain".
When set to "application/json", this will retrieve the result as
"JSON" data and return a Net::API::CPAN::Diff object. If this is set
to "text/plain", then this will return a raw "diff" output as a
string encoded in Perl internal utf-8 encoding.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fdiff%2Ffile%2FAcREzFgg3ExIrFT
URa0QJfn8nto%2FIes7Ysw0GjCxUU6Wj_WzI9s8ysU> to see the data returned
by the CPAN REST API.
* "author1", "author2", "release1", and "release2" ->
"/diff/release/{author1}/{release1}/{author2}/{release2}"
If the properties "author1", "author2", "release1", and "release2"
are provided, this will issue a query to the endpoint
"/diff/release/{author1}/{release1}/{author2}/{release2}", such as:
/diff/release/OALDERS/HTTP-Message-6.35/OALDERS/HTTP-Message-6.36
For example:
my $diff_obj = $cpan->diff(
author1 => 'OALDERS',
# This is optional if it is the same
author2 => 'OALDERS',
release1 => 'HTTP-Message-6.35'
release2 => 'HTTP-Message-6.36'
# Default
accept => 'application/json',
) || die( $cpan->error );
Note that, if "author1" and "author2" are the same, "author2" is
optional.
It is important, however, that the "release" specified with
"release1" belongs to "author1" and the "release" specified with
"release2" belongs to "author2"
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fdiff%2Frelease%2FOALDERS%2FHT
TP-Message-6.35%2FOALDERS%2FHTTP-Message-6.36> to see the data
returned by the CPAN REST API.
* "distribution" -> "/diff/release/{distribution}"
You can also specify the property "distribution", and this will
issue a query to the endpoint "/diff/release/{distribution}", such
as:
/diff/release/HTTP-Message
For example:
my $diff_obj = $cpan->diff(
distribution => 'HTTP-Message',
# Default
accept => 'application/json',
) || die( $cpan->error );
If "accept" is set to "application/json", which is the default
value, this will return a Net::API::CPAN::Diff object representing
the difference between the previous version and current version for
the "release" of the "distribution" specified. If, however, "accept"
is set to "text/plain", a string of the diff output will be returned
encoded in Perl internal utf-8 encoding.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fdiff%2Frelease%2FHTTP-Message
> to see the data returned by the CPAN REST API.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
distribution
# Retrieves a distribution information details
my $dist_obj = $cpan->distribution( 'HTTP-Message' ) ||
die( $cpan->error );
# Queries distribution information details using simple search
my $list_obj = $cpan->distribution(
query => 'HTTP',
from => 10,
size => 10,
) || die( $cpan->error );
# Queries distribution information details using advanced search with ElasticSearch
my $list_obj = $cpan->distribution( $filter_object ) ||
die( $cpan->error );
This method is used to query the CPAN REST API to retrieve
"distribution" information.
* "distribution" -> "/distribution/{distribution}"
If a string representing a "distribution" is provided, it will issue
a query to the endpoint "/distribution/{distribution}" to retrieve a
distribution information details, such as:
/distribution/HTTP-Message
For example:
my $dist_obj = $cpan->distribution( 'HTTP-Message' ) ||
die( $cpan->error );
This will return, upon success, a Net::API::CPAN::Distribution
object.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fdistribution%2FHTTP-Message>
to see the data returned by the CPAN REST API.
* "query" -> "/distribution"
If the property "query" is provided, this will trigger a simple
search query to the endpoint "/distribution", such as:
/distribution?q=HTTP
For example:
my $list_obj = $cpan->distribution(
query => 'HTTP',
from => 10,
size => 10,
) || die( $cpan->error );
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Distribution objects.
The following options are also supported:
* "from"
An integer representing the offset starting from 0 within
the total data.
* "size"
An integer representing the size of each page, i.e. how many
results are returned per page. This usually defaults to 10.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fdistribution%3Fq%3DHT
TP> to see the data returned by the CPAN REST API.
* search filter -> "/distribution"
And if a search filter is passed, this will trigger a more
advanced ElasticSearch query to the endpoint "/distribution"
using the "HTTP" "POST" method. See the
Net::API::CPAN::Filter module on more details on what
granular queries you can execute.
This would return, upon success, a Net::API::CPAN::List
object of Net::API::CPAN::Distribution objects.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
download_url
# Retrieve the latest release download URL information details
my $dl_obj = $cpan->download_url( 'HTTP::Message' ) ||
die( $cpan->error );
This method is used to query the CPAN REST API to retrieve the specified
"module" latest "release" "download_url" information.
* "module" -> "/download_url/{module}"
If a string representing a "module" is provided, it will issue a
query to the endpoint "/download_url/{module}" to retrieve the
download URL information details of the specified module, such as:
/download_url/HTTP::Message
This will return, upon success, a Net::API::CPAN::DownloadUrl
object.
The following options are also supported:
* "dev"
# Retrieves a development release
my $dl_obj = $cpan->download_url( 'HTTP::Message',
{
dev => 1,
version => '>1.01',
}) || die( $cpan->error );
Specifies if the "release" is a development version.
* "version"
# Retrieve the download URL of a specific release version
my $dl_obj = $cpan->download_url( 'HTTP::Message',
{
version => '1.01',
}) || die( $cpan->error );
# or, using a range
my $dl_obj = $cpan->download_url( 'HTTP::Message',
{
version => '<=1.01',
}) || die( $cpan->error );
my $dl_obj = $cpan->download_url( 'HTTP::Message',
{
version => '>1.01,<=2.00',
}) || die( $cpan->error );
Specifies the version requirement or version range
requirement.
Supported range operators are "==" "!=" "<=" ">=" "<" ">"
"!"
Separate the ranges with a comma when specifying multiple
ranges.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fdownload_url%2FHTTP%3A%3AMess
age> to see the data returned by the CPAN REST API.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
favorite
# Queries favorites using a simple search
my $list_obj = $cpan->favorite(
query => 'HTTP',
from => 10,
size => 10,
) || die( $cpan->error );
# Queries favorites using a advanced search with ElasticSearch format
my $list_obj = $cpan->favorite( $filter_object ) ||
die( $cpan->error );
# Retrieves favorites agregate by distributions as an hash reference
# e.g.: HTTP-Message => 63
my $hash_ref = $cpan->favorite( aggregate => 'HTTP-Message' ) ||
die( $cpan->error );
# Same
my $hash_ref = $cpan->favorite( agg => 'HTTP-Message' ) ||
die( $cpan->error );
# Same with multiple distributions
my $hash_ref = $cpan->favorite( aggregate => [qw( HTTP-Message Data-HexDump)] ) ||
die( $cpan->error );
# Same
my $hash_ref = $cpan->favorite( agg => [qw( HTTP-Message Data-HexDump)] ) ||
die( $cpan->error );
# Retrieves list of users who favorited a distribution as an array reference
# e.g. [ '9nGbVdZ4QhO4Ia5ZhNpjtg', 'c4QLX0YORN6-quL15MGwqg', ... ]
my $array_ref = $cpan->favorite( distribution => 'HTTP-Message' ) ||
die( $cpan->error );
# Retrieves user favorites information details
my $list_obj = $cpan->favorite( user => 'q_15sjOkRminDY93g9DuZQ' ) ||
die( $cpan->error );
# Retrieves top favorite distributions a.k.a. leaderboard as an array reference
my $array_ref = $cpan->favorite( leaderboard => 1 ) ||
die( $cpan->error );
# Retrieves list of recent favorite distribution
my $list_obj = $cpan->favorite( recent => 1 ) ||
die( $cpan->error );
This method is used to query the CPAN REST API to retrieve "favorite"
information.
* "query" -> "/favorite"
If the property "query" is provided, this will trigger a simple
search query to the endpoint "/favorite", such as:
/favorite?q=HTTP
For example:
my $list_obj = $cpan->favorite( query => 'HTTP' ) ||
die( $cpan->error );
which will find all "favorite" related to the query term "HTTP".
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Favorite objects.
The following options are also supported:
* "from"
An integer representing the offset starting from 0 within
the total data.
* "size"
An integer representing the size of each page, i.e. how many
results are returned per page. This usually defaults to 10.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Ffavorite%3Fq%3DHTTP> to see
the data returned by the CPAN REST API.
* search filter -> "/favorite"
And if a search filter is passed, this will trigger a more advanced
ElasticSearch query to the endpoint "/favorite" using the "HTTP"
"POST" method. See the Net::API::CPAN::Filter module on more details
on what granular queries you can execute.
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Favorite objects.
* "aggregate" or "agg" -> "/favorite/agg_by_distributions"
If the property "aggregate" or "agg", for short, is provided, this
will issue a query to the endpoint "/favorite/agg_by_distributions"
to retrieve favorites agregate by distributions, such as:
/favorite/agg_by_distributions?distribution=HTTP-Message&distribution=Data-HexDump
For example:
my $hash_ref = $cpan->favorite( aggregate => 'HTTP-Message' ) ||
die( $cpan->error );
my $hash_ref = $cpan->favorite( aggregate => [qw( HTTP-Message Data-HexDump)] ) ||
die( $cpan->error );
The "aggregate" value can be either a string representing a
"distribution", or an array reference of "distributions"
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Favorite objects.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Ffavorite%2Fagg_by_distributio
ns%3Fdistribution%3DHTTP-Message%26distribution%3DData-HexDump> to
see the data returned by the CPAN REST API.
* "distribution" -> "/favorite/users_by_distribution/{distribution}"
If the property "distribution" is provided, will issue a query to
the endpoint "/favorite/users_by_distribution/{distribution}" to
retrieves the list of users who favorited the specified
distribution, such as:
/favorite/users_by_distribution/HTTP-Message
For example:
my $array_ref = $cpan->favorite( distribution => 'HTTP-Message' ) ||
die( $cpan->error );
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Favorite objects.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Ffavorite%2Fusers_by_distribut
ion%2FHTTP-Message> to see the data returned by the CPAN REST API.
* "user" -> "/favorite/by_user/{user}"
If the property "user" is provided, this will issue a query to the
endpoint "/favorite/by_user/{user}" to retrieve the specified user
favorites information details, such as:
/favorite/by_user/q_15sjOkRminDY93g9DuZQ
For example:
my $list_obj = $cpan->favorite( user => 'q_15sjOkRminDY93g9DuZQ' ) ||
die( $cpan->error );
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Favorite objects.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Ffavorite%2Fby_user%2Fq_15sjOk
RminDY93g9DuZQ> to see the data returned by the CPAN REST API.
* "leaderboard" -> "/favorite/leaderboard"
If the property "leaderboard" is provided with any value true or
false does not matter, this will issue a query to the endpoint
"/favorite/leaderboard" to retrieve the top favorite distributions
a.k.a. leaderboard, such as:
/favorite/leaderboard
For example:
my $array_ref = $cpan->favorite( leaderboard => 1 ) ||
die( $cpan->error );
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Favorite objects.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Ffavorite%2Fleaderboard> to
see the data returned by the CPAN REST API.
* "recent" -> "/favorite/recent"
Finally, if the property "recent" is provided with any value true or
false does not matter, this will issue a query to the endpoint
"/favorite/recent" to retrieve the list of recent favorite
distributions, such as:
/favorite/recent
For example:
my $list_obj = $cpan->favorite( recent => 1 ) ||
die( $cpan->error );
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Favorite objects.
The following options are also supported:
* "page"
An integer representing the page offset starting from 1.
* "size"
An integer representing the size of each page, i.e. how many
results are returned per page. This usually defaults to 10.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Ffavorite%2Frecent> to see the
data returned by the CPAN REST API.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
file
# Queries files using simple search
my $list_obj = $cpan->file(
query => 'HTTP',
from => 10,
size => 10,
) || die( $cpan->error );
# Queries files with advanced search using ElasticSearch
my $list_obj = $cpan->file( $filter_object ) ||
die( $cpan->error );
# Retrieves a directory content
my $list_obj = $cpan->file(
author => 'OALDERS',
release => 'HTTP-Message-6.36',
dir => 'lib/HTTP',
) || die( $cpan->error );
# Retrieves a file information details
my $file_obj = $cpan->file(
author => 'OALDERS',
release => 'HTTP-Message-6.36',
path => 'lib/HTTP/Message.pm',
) || die( $cpan->error );
This method is used to query the CPAN REST API to retrieve "file"
information.
* "query" -> "/file"
If the property "query" is provided, this will trigger a simple
search query to the endpoint "/file", such as:
/file?q=HTTP
For example:
my $list_obj = $cpan->file(
query => 'HTTP',
from => 10,
size => 10,
) || die( $cpan->error );
will find all "files" related to "HTTP".
This would return a Net::API::CPAN::List object upon success.
The following options are also supported:
* "from"
An integer representing the offset starting from 0 within
the total data.
* "size"
An integer representing the size of each page, i.e. how many
results are returned per page. This usually defaults to 10.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Ffile%3Fq%3DHTTP> to see the
data returned by the CPAN REST API.
* search filter -> "/file"
And if a search filter is passed, this will trigger a more advanced
ElasticSearch query to the endpoint "/file" using the "HTTP" "POST"
method. See the Net::API::CPAN::Filter module on more details on
what granular queries you can execute.
my $list_obj = $cpan->file( $filter_object ) ||
die( $cpan->error );
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::File objects.
* "author", "release" and "dir" ->
"/file/dir/{author}/{release}/{dir}"
If the properties, "author", "release" and "dir" are provided, this
will issue a query to the endpoint
"/file/dir/{author}/{release}/{dir}" to retrieve the specified
directory content, such as:
/file/dir/OALDERS/HTTP-Message-6.36/lib/HTTP
For example:
my $list_obj = $cpan->file(
author => 'OALDERS',
release => 'HTTP-Message-6.36',
dir => 'lib/HTTP',
) || die( $cpan->error );
For this to yield correct results, the "dir" specified must be a
directory.
This would return, upon success, a Net::API::CPAN::List object of
all the files and directories contained within the specified
directory.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Ffile%2Fdir%2FOALDERS%2FHTTP-M
essage-6.36%2Flib%2FHTTP> to see the data returned by the CPAN REST
API.
* "author", "release" and "path" -> "/file/{author}/{release}/{path}"
If the properties, "author", "release" and "path" are provided, this
will issue a query to the endpoint "/file/{author}/{release}/{path}"
to retrieve the specified file (or directory) information details,
such as:
/file/OALDERS/HTTP-Message-6.36/lib/HTTP/Message.pm
For example:
my $file_obj = $cpan->file(
author => 'OALDERS',
release => 'HTTP-Message-6.36',
path => 'lib/HTTP/Message.pm',
) || die( $cpan->error );
This would return, upon success, a Net::API::CPAN::File object of
the information retrieved.
Note that the path can point to either a file or a directory within
the given release.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Ffile%2FOALDERS%2FHTTP-Message
-6.36%2Flib%2FHTTP%2FMessage.pm> to see the data returned by the
CPAN REST API.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
first
This takes a string and will issue a query to the endpoint
"/search/first" to retrieve the first result found based on the search
query specified, such as:
/search/first?q=HTTP
For example:
my $list_obj = $cpan->first( 'HTTP' ) || die( $cpan->error );
This would, upon success, return a Net::API::CPAN::Module object.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fsearch%2Fautocomplete%2Fsuggest%3
Fq%3DHTTP> to see the data returned by the CPAN REST API.
history
# Retrieves the history of a given module
my $list_obj = $cpan->history(
type => 'module',
module => 'HTTP::Message',
path => 'lib/HTTP/Message.pm',
) || die( $cpan->error );
# Retrieves the history of a given distribution file
my $list_obj = $cpan->history(
type => 'file',
distribution => 'HTTP-Message',
path => 'lib/HTTP/Message.pm',
) || die( $cpan->error );
# Retrieves the history of a given module documentation
my $list_obj = $cpan->history(
type => 'documentation',
module => 'HTTP::Message',
path => 'lib/HTTP/Message.pm',
) || die( $cpan->error );
This method is used to query the CPAN REST API to retrieve "file"
history information.
* "module" -> "/search/history/module"
If the property "module" is provided, this will trigger a query to
the endpoint "/search/history/module" to retrieve the history of a
given module, such as:
/search/history/module/HTTP::Message/lib/HTTP/Message.pm
For example:
my $list_obj = $cpan->history(
type => 'module',
module => 'HTTP::Message',
path => 'lib/HTTP/Message.pm',
) || die( $cpan->error );
will find all "module" history related to the module
"HTTP::Message".
This would return a Net::API::CPAN::List object upon success.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fsearch%2Fhistory%2Fmodule%2FH
TTP%3A%3AMessage%2Flib%2FHTTP%2FMessage.pm> to see the data returned
by the CPAN REST API.
* "file" -> "/search/history/file"
If the property "file" is provided, this will trigger a query to the
endpoint "/search/history/file" to retrieve the history of a given
distribution file, such as:
/search/history/file/HTTP-Message/lib/HTTP/Message.pm
For example:
my $list_obj = $cpan->history(
type => 'file',
distribution => 'HTTP-Message',
path => 'lib/HTTP/Message.pm',
) || die( $cpan->error );
will find all "files" history related to the distribution
"HTTP-Message".
This would return a Net::API::CPAN::List object upon success.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fsearch%2Fhistory%2Ffile%2FHTT
P-Message%2Flib%2FHTTP%2FMessage.pm> to see the data returned by the
CPAN REST API.
* "documentation" -> "/search/history/documentation"
If the property "documentation" is provided, this will trigger a
query to the endpoint "/search/history/documentation" to retrieve
the history of a given module documentation, such as:
/search/history/documentation/HTTP::Message/lib/HTTP/Message.pm
For example:
my $list_obj = $cpan->history(
type => 'documentation',
module => 'HTTP::Message',
path => 'lib/HTTP/Message.pm',
) || die( $cpan->error );
will find all "documentation" history related to the module
"HTTP::Message".
This would return a Net::API::CPAN::List object upon success.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fsearch%2Fhistory%2Fdocumentat
ion%2FHTTP%3A%3AMessage%2Flib%2FHTTP%2FMessage.pm> to see the data
returned by the CPAN REST API.
mirror
my $list_obj = $cpan->mirror;
This would return, upon success, a Net::API::CPAN::List object.
Actually there is no mirroring anymore, because for some time now CPAN
runs on a CDN (Content Distributed Network) which performs the same
result, but transparently.
See more on this here <https://www.cpan.org/SITES.html>
This endpoint also has search capability, but given there is now only
one entry, it is completely useless.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fmirror> to see the data returned
by the CPAN REST API.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
module
# Queries modules with a simple search
my $list_obj = $cpan->module(
query => 'HTTP',
from => 10,
size => 10,
) || die( $cpan->error );
# Queries modules with an advanced search using ElasticSearch
my $list_obj = $cpan->module( $filter_object ) ||
die( $cpan->error );
# Retrieves the specified module information details
my $module_obj = $cpan->module(
module => 'HTTP::Message',
) || die( $cpan->error );
# And if you want to join with other object types
my $module_obj = $cpan->module(
module => 'HTTP::Message',
join => [qw( release author )],
) || die( $cpan->error );
This method is used to query the CPAN REST API to retrieve "module"
information.
* "query" -> "/module"
If the property "query" is provided, this will trigger a simple
search query to the endpoint "/module", such as:
/module?q=HTTP
For example:
my $list_obj = $cpan->module( query => 'HTTP' ) ||
die( $cpan->error );
will find all "modules" related to "HTTP".
This would return a Net::API::CPAN::List object upon success.
The following options are also supported:
* "from"
An integer representing the offset starting from 0 within
the total data.
* "size"
An integer representing the size of each page, i.e. how many
results are returned per page. This usually defaults to 10.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fmodule%3Fq%3DHTTP> to see the
data returned by the CPAN REST API.
* search filter -> "/module"
And if a search filter is passed, this will trigger a more advanced
ElasticSearch query to the endpoint "/module" using the "HTTP"
"POST" method. See the Net::API::CPAN::Filter module on more details
on what granular queries you can execute.
This would return a Net::API::CPAN::List object upon success.
* $module -> "/module/{module}"
If a string representing a "module" is provided, this will be used
to issue a query to the endpoint "/module/{module}" to retrieve the
specified module information details, such as:
/module/HTTP::Message
For example:
my $module_obj = $cpan->module(
module => 'HTTP::Message',
join => [qw( release author )],
) || die( $cpan->error );
This would return, upon success, a Net::API::CPAN::Module object.
The following options are also supported:
* "join"
You can join a.k.a. merge other objects data by setting
"join" to that object type, such as "release" or "author".
"join" value can be either a string or an array of object
types.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fmodule%2FHTTP%3A%3AMessage>
to see the data returned by the CPAN REST API.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
package
# Queries packages with a simple search
my $list_obj = $cpan->package(
query => 'HTTP',
from => 10,
size => 10,
) || die( $cpan->error );
# Queries packages with an advanced search using ElasticSearch
my $list_obj = $cpan->package( $filter_object ) ||
die( $cpan->error );
# Retrieves the list of a distribution packages
my $list_obj = $cpan->package( distribution => 'HTTP-Message' ) ||
die( $cpan->error );
# Retrieves the latest release and package information for the specified module
my $package_obj = $cpan->package( 'HTTP::Message' ) ||
die( $cpan->error );
This method is used to query the CPAN REST API to retrieve "package"
information.
* "query" -> "/package"
If the property "query" is provided, this will trigger a simple
search query to the endpoint "/package", such as:
/package?q=HTTP
For example:
my $list_obj = $cpan->package( query => 'HTTP' ) ||
die( $cpan->error );
will find all "packages" related to "HTTP".
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Package
The following options are also supported:
* "from"
An integer representing the offset starting from 0 within
the total data.
* "size"
An integer representing the size of each page, i.e. how many
results are returned per page. This usually defaults to 10.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fpackage%3Fq%3DHTTP> to see
the data returned by the CPAN REST API.
* search filter -> "/package"
And if a search filter is passed, this will trigger a more advanced
ElasticSearch query to the endpoint "/package" using the "HTTP"
"POST" method. See the Net::API::CPAN::Filter module on more details
on what granular queries you can execute.
* "distribution" -> "/package/modules/{distribution}"
If the property "distribution" is provided, this will issue a query
to the endpoint "/package/modules/{distribution}" to retrieve the
list of a distribution packages, such as:
/package/modules/HTTP-Message
For example:
my $list_obj = $cpan->package( distribution => 'HTTP-Message' ) ||
die( $cpan->error );
This would return, upon success, an array object containing all the
modules name provided within the specified "distribution".
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fpackage%2Fmodules%2FHTTP-Mess
age> to see the data returned by the CPAN REST API.
* $package -> "/package/{module}"
If a string representing a package name is directly passed, this
will issue a query to the endpoint "/package/{module}" to retrieve
the latest release and package information for the specified module,
such as:
/package/HTTP::Message
For example:
my $package_obj = $cpan->package( 'HTTP::Message' ) ||
die( $cpan->error );
This would return, upon success, a Net::API::CPAN::Package object.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fpackage%2FHTTP%3A%3AMessage>
to see the data returned by the CPAN REST API.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
permission
# Queries permissions with a simple search
my $list_obj = $cpan->permission(
query => 'HTTP',
from => 10,
size => 10,
) || die( $cpan->error );
# Queries permissions with an advanced search using ElasticSearch
my $list_obj = $cpan->permission( $filter_object ) ||
die( $cpan->error );
# Retrieves permission information details for the specified author
my $list_obj = $cpan->permission(
author => 'OALDERS',
from => 40,
size => 20,
) || die( $cpan->error );
# Retrieves permission information details for the specified module
my $list_obj = $cpan->permission(
module => 'HTTP::Message',
) || die( $cpan->error );
# Retrieves permission information details for the specified modules
my $list_obj = $cpan->permission(
module => [qw( HTTP::Message Data::HexDump )],
) || die( $cpan->error );
This method is used to query the CPAN REST API to retrieve "package"
information.
* "query" -> "/permission"
If the property "query" is provided, this will trigger a simple
search query to the endpoint "/permission", such as:
/permission?q=HTTP
For example:
my $list_obj = $cpan->permission(
query => 'HTTP',
from => 10,
size => 10,
) || die( $cpan->error );
will find all "permissions" related to "HTTP".
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Permission objects.
The following options are also supported:
* "from"
An integer representing the offset starting from 0 within
the total data.
* "size"
An integer representing the size of each page, i.e. how many
results are returned per page. This usually defaults to 10.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fpermission%3Fq%3DHTTP> to see
the data returned by the CPAN REST API.
* search filter -> "/permission"
And if a search filter is passed, this will trigger a more advanced
ElasticSearch query to the endpoint "/permission" using the "HTTP"
"POST" method. See the Net::API::CPAN::Filter module on more details
on what granular queries you can execute.
* "author" -> "/permission/by_author/{author}"
If the property "author" is provided, this will trigger a simple
search query to the endpoint "/permission/by_author/{author}" to
retrieve the permission information details for the specified
author, such as:
/permission/by_author/OALDERS?from=40&q=HTTP&size=20
For example:
my $list_obj = $cpan->permission(
author => 'OALDERS',
from => 40,
size => 20,
) || die( $cpan->error );
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Permission objects.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fpermission%2Fby_author%2FOALD
ERS%3Ffrom%3D40%26q%3DHTTP%26size%3D20> to see the data returned by
the CPAN REST API.
* "module" -> "/permission/{module}"
If the property "module" is provided, and its value is a string,
this will issue a query to the endpoint "/permission/{module}" to
retrieve permission information details for the specified module,
such as:
/permission/HTTP::Message
For example:
my $list_obj = $cpan->permission(
module => 'HTTP::Message',
) || die( $cpan->error );
This would return, upon success, a Net::API::CPAN::Permission
object.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fpermission%2FHTTP%3A%3AMessag
e> to see the data returned by the CPAN REST API.
* ["module"] -> "/permission/by_module"
If the property "module" is provided, and its value is an array
reference, this will issue a query to the endpoint
"/permission/by_module" to retrieve permission information details
for the specified modules, such as:
/permission/by_module?module=HTTP%3A%3AMessage&module=Data%3A%3AHexDump
For example:
my $list_obj = $cpan->permission(
module => [qw( HTTP::Message Data::HexDump )],
) || die( $cpan->error );
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Permission objects.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fpermission%2Fby_module%3Fmodu
le%3DHTTP%253A%253AMessage%26module%3DData%253A%253AHexDump> to see
the data returned by the CPAN REST API.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
pod
# Returns the POD of the given module in the
# specified release in markdown format
my $string = $cpan->pod(
author => 'OALDERS',
release => 'HTTP-Message-6.36',
path => 'lib/HTTP/Message.pm',
accept => 'text/x-markdown',
) || die( $cpan->error );
# Returns the POD of the given module in
# markdown format
my $string = $cpan->pod(
module => 'HTTP::Message',
accept => 'text/x-markdown',
) || die( $cpan->error );
# Renders the specified POD code into HTML
my $html = $cpan->pod(
render => qq{=encoding utf-8\n\n=head1 Hello World\n\nSomething here\n\n=oops\n\n=cut\n}
) || die( $cpan->error );
This method is used to query the CPAN REST API to retrieve "pod"
documentation from specified modules and to render pod into "HTML" data.
* "author", "release" and "path" -> "/pod/{author}/{release}/{path}"
If the properties "author", "release" and "path" are provided, this
will issue a query to the endpoint "/pod/{author}/{release}/{path}"
to retrieve the POD of the given module in the specified release,
such as:
/pod/OALDERS/HTTP-Message-6.36/lib/HTTP/Message.pm
For example:
my $string = $cpan->pod(
author => 'OALDERS',
release => 'HTTP-Message-6.36',
path => 'lib/HTTP/Message.pm',
accept => 'text/x-markdown',
) || die( $cpan->error );
This would return a string of data in the specified format, which
can be one of "text/html", "text/plain", "text/x-markdown" or
"text/x-pod". By default this is "text/html". The preferred data
type is specified with the property "accept"
The following options are also supported:
* "accept"
This value instructs the MetaCPAN API to return the pod data
in the desired format.
Supported formats are: "text/html", "text/plain",
"text/x-markdown", "text/x-pod"
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fpod%2FOALDERS%2FHTTP-Message-
6.36%2Flib%2FHTTP%2FMessage.pm> to see the data returned by the CPAN
REST API.
* "module" -> "/v1/pod/{module}"
If the property "module" is provided, this will issue a query to the
endpoint "/v1/pod/{module}" to retrieve the POD of the specified
module, such as:
/pod/HTTP::Message
For example:
my $string = $cpan->pod(
module => 'HTTP::Message',
accept => 'text/x-markdown',
) || die( $cpan->error );
Just like the previous one, this would return a string of data in
the specified format (in the above example markdown), which can be
one of "text/html", "text/plain", "text/x-markdown" or "text/x-pod".
By default this is "text/html". The preferred data type is specified
with the property "accept".
The following options are also supported:
* "accept"
This value instructs the MetaCPAN API to return the pod data
in the desired format.
Supported formats are: "text/html", "text/plain",
"text/x-markdown", "text/x-pod"
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fpod%2FHTTP%3A%3AMessage> to
see the data returned by the CPAN REST API.
* "render" -> "/pod_render"
If the property "render" is provided with a string of "POD" data,
this will issue a query to the endpoint "/pod_render", such as:
/pod_render?pod=%3Dencoding+utf-8%0A%0A%3Dhead1+Hello+World%0A%0ASomething+here%0A%0A%3Doops%0A%0A%3Dcut%0A
For example:
my $html = $cpan->pod(
render => qq{=encoding utf-8\n\n=head1 Hello World\n\nSomething here\n\n=oops\n\n=cut\n}
) || die( $cpan->error );
This would return a string of "HTML" formatted data.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fpod_render%3Fpod%3D%253Dencod
ing%2Butf-8%250A%250A%253Dhead1%2BHello%2BWorld%250A%250ASomething%2
Bhere%250A%250A%253Doops%250A%250A%253Dcut%250A> to see the data
returned by the CPAN REST API.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
rating
# Queries permissions with a simple search
my $list_obj = $cpan->rating(
query => 'HTTP',
from => 10,
size => 10,
) || die( $cpan->error );
# Queries permissions with an advanced search using ElasticSearch format
my $list_obj = $cpan->rating( $filter_object ) ||
die( $cpan->error );
# Retrieves rating information details of the specified distribution
my $list_obj = $cpan->rating(
distribution => 'HTTP-Tiny',
) || die( $cpan->error );
This method is used to query the CPAN REST API to retrieve "rating"
historical data for the specified search query or "distribution".
It is worth mentioning that although this endpoint still works, CPAN
Ratings has been decommissioned some time ago, and thus its usefulness
is questionable.
* "query" -> "/rating"
If the property "query" is provided, this will trigger a simple
search query to the endpoint "/rating", such as:
/rating?q=HTTP
For example:
my $list_obj = $cpan->rating(
query => 'HTTP',
from => 10,
size => 10,
) || die( $cpan->error );
will find all "ratings" related to "HTTP".
This would return a Net::API::CPAN::List object upon success.
The following options are also supported:
* "from"
An integer representing the offset starting from 0 within
the total data.
* "size"
An integer representing the size of each page, i.e. how many
results are returned per page. This usually defaults to 10.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Frating%3Fq%3DHTTP> to see the
data returned by the CPAN REST API.
* search filter -> "/rating"
And if a search filter is passed, this will trigger a more advanced
ElasticSearch query to the endpoint "/rating" using the "HTTP"
"POST" method. See the Net::API::CPAN::Filter module on more details
on what granular queries you can execute.
* "distribution" -> "/rating/by_distributions"
If a property "distribution" is provided, this will issue a query to
the endpoint "/rating/by_distributions" to retrieve rating
information details of the specified distribution, such as:
/rating/by_distributions?distribution=HTTP-Tiny
For example:
my $list_obj = $cpan->rating(
distribution => 'HTTP-Tiny',
) || die( $cpan->error );
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Rating objects.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Frating%2Fby_distributions%3Fd
istribution%3DHTTP-Tiny> to see the data returned by the CPAN REST
API.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
release
# Perform a simple query
my $list_obj = $cpan->release(
query => 'HTTP',
from => 10,
size => 10,
) || die( $cpan->error );
# Perform an advanced query using ElasticSearch format
my $list_obj = $cpan->release( $filter_object ) ||
die( $cpan->error );
# Retrieves a list of all releases for a given author
my $list_obj = $cpan->release(
all => 'OALDERS',
page => 2,
size => 100,
) || die( $cpan->error );
# Retrieves a shorter list of all releases for a given author
my $list_obj = $cpan->release( author => 'OALDERS' ) ||
die( $cpan->error );
# Retrieve a release information details
my $release_obj = $cpan->release(
author => 'OALDERS',
release => 'HTTP-Message-6.36',
) || die( $cpan->error );
# Retrieves the latest distribution release information details
my $release_obj = $cpan->release(
distribution => 'HTTP-Message',
) || die( $cpan->error );
# Retrieves the list of contributors for the specified distributions
my $list_obj = $cpan->release(
author => 'OALDERS',
release => 'HTTP-Message-6.36',
contributors => 1,
) || die( $cpan->error );
# Retrieves the list of release key files by category
my $hash_ref = $cpan->release(
author => 'OALDERS',
release => 'HTTP-Message-6.36',
files => 1,
) || die( $cpan->error );
# Retrieves the list of interesting files for the given release
my $list_obj = $cpan->release(
author => 'OALDERS',
release => 'HTTP-Message-6.36',
# You can also use just 'interesting'
interesting_files => 1,
) || die( $cpan->error );
# Get latest releases by the specified author
my $list_obj = $cpan->release(
author => 'OALDERS',
latest => 1,
) || die( $cpan->error );
# Get the latest releases for the specified distribution
my $release_obj = $cpan->release(
distribution => 'HTTP-Message',
latest => 1,
) || die( $cpan->error );
# Retrieves the list of modules in the specified release
my $list_obj = $cpan->release(
author => 'OALDERS',
release => 'HTTP-Message-6.36',
modules => 1,
) || die( $cpan->error );
# Get the list of recent releases
my $list_obj = $cpan->release(
recent => 1,
) || die( $cpan->error );
# get all releases by versions for the specified distribution
my $list_obj = $cpan->release(
versions => 'HTTP-Message',
) || die( $cpan->error );
This method is used to query the CPAN REST API to retrieve "release"
information.
* "query" -> "/release"
If the property "query" is provided, this will trigger a simple
search query to the endpoint "/release", such as:
/release?q=HTTP
For example:
my $list_obj = $cpan->release(
query => 'HTTP',
from => 10,
size => 10,
) || die( $cpan->error );
will find all "releases" related to "HTTP".
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Release objects.
The following options are also supported:
* "from"
An integer representing the offset starting from 0 within
the total data.
* "size"
An integer representing the size of each page, i.e. how many
results are returned per page. This usually defaults to 10.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Frelease%3Fq%3DHTTP> to see
the data returned by the CPAN REST API.
* search filter -> "/release"
And if a search filter is passed, this will trigger a more advanced
ElasticSearch query to the endpoint "/release" using the "HTTP"
"POST" method. See the Net::API::CPAN::Filter module on more details
on what granular queries you can execute.
* "all" -> "/release/all_by_author/{author}"
If the property "all" is provided, this will issue a query to the
endpoint "/release/all_by_author/{author}" to get all releases by
the specified author, such as:
/release/all_by_author/OALDERS?page=2&page_size=100
For example:
my $list_obj = $cpan->release(
all => 'OALDERS',
page => 2,
size => 100,
) || die( $cpan->error );
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Release objects.
The following options are also supported:
* "page"
An integer representing the page offset starting from 1.
* "size"
An integer representing the size of each page, i.e. how many
results are returned per page. This usually defaults to 10.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Frelease%2Fall_by_author%2FOAL
DERS%3Fpage%3D1%26page_size%3D100> to see the data returned by the
CPAN REST API.
* "author" -> "/release/by_author/{author}"
If the property "author" alone is provided, this will issue a query
to the endpoint "/release/by_author/{author}" to get releases by
author, such as:
/release/by_author/OALDERS
For example:
my $list_obj = $cpan->release( author => 'OALDERS' ) ||
die( $cpan->error );
This would return a Net::API::CPAN::List object upon success.
Note that this is similar to "all", but returns a subset of all the
author's data.
The following options are also supported:
* "page"
An integer representing the page offset starting from 1.
* "size"
An integer representing the size of each page, i.e. how many
results are returned per page. This usually defaults to 10.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Frelease%2Fby_author%2FOALDERS
> to see the data returned by the CPAN REST API.
* "author" and "release" -> "/v1/release/{author}/{release}"
If the property "author" and "release" are provided, this will issue
a query to the endpoint "/v1/release/{author}/{release}" tp retrieve
a distribution release information, such as:
/release/OALDERS/HTTP-Message-6.36
For example:
my $release_obj = $cpan->release(
author => 'OALDERS',
release => 'HTTP-Message-6.36',
) || die( $cpan->error );
This would return a Net::API::CPAN::Release object upon success.
The following options are also supported:
* "join"
You can join a.k.a. merge other objects data by setting
"join" to that object type, such as "module" or "author".
"join" value can be either a string or an array of object
types.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Frelease%2FOALDERS%2FHTTP-Mess
age-6.36> to see the data returned by the CPAN REST API.
* "distribution" -> "/release/{distribution}"
If the property "distribution" alone is provided, this will issue a
query to the endpoint "/release/{distribution}" to retrieve a
release information details., such as:
/release/HTTP-Message
For example:
my $release_obj = $cpan->release(
distribution => 'HTTP-Message',
) || die( $cpan->error );
This would return a Net::API::CPAN::Release object upon success.
The following options are also supported:
* "join"
You can join a.k.a. merge other objects data by setting
"join" to that object type, such as "module" or "author".
"join" value can be either a string or an array of object
types.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Frelease%2FHTTP-Message> to
see the data returned by the CPAN REST API.
* "contributors", "author" and "release" ->
"/release/contributors/{author}/{release}"
If the property "contributors", "author" and "release" are provided,
this will issue a query to the endpoint
"/release/contributors/{author}/{release}" to retrieve the list of
contributors for the specified release, such as:
/release/contributors/OALDERS/HTTP-Message-6.36
For example:
my $list_obj = $cpan->release(
author => 'OALDERS',
release => 'HTTP-Message-6.36',
contributors => 1,
) || die( $cpan->error );
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Release objects. :List> object upon success.
The following options are also supported:
* "join"
You can join a.k.a. merge other objects data by setting
"join" to that object type, such as "module" or "author".
"join" value can be either a string or an array of object
types.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Frelease%2Fcontributors%2FOALD
ERS%2FHTTP-Message-6.36> to see the data returned by the CPAN REST
API.
* "files", "author" and "release" ->
"/release/files_by_category/{author}/{release}"
If the property "files", "author" and "release" are provided, this
will issue a query to the endpoint
"/release/files_by_category/{author}/{release}" to retrieve the list
of key files by category for the specified release, such as:
/release/files_by_category/OALDERS/HTTP-Message-6.36
For example:
my $hash_ref = $cpan->release(
author => 'OALDERS',
release => 'HTTP-Message-6.36',
files => 1,
) || die( $cpan->error );
This would return an hash object of the following category names,
each having, as their value, an array of the specified "release"
files.
The categories are:
* "changelog"
This is typically the "Changes" or "CHANGES" file.
* "contributing"
This is typically the "CONTRIBUTING.md" file.
* "dist"
This is typically other files that are part of the
"release", such as "cpanfile", "Makefile.PL", "dist.ini",
"META.json", "META.yml", "MANIFEST".
* "install"
This is typically the "INSTALL" file.
* "license"
This is typically the "LICENSE" file.
* "other"
This is typically the "README.md" file.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Frelease%2Ffiles_by_category%2
FOALDERS%2FHTTP-Message-6.36> to see the data returned by the CPAN
REST API.
* "interesting_files", "author" and "release" ->
"/release/interesting_files/{author}/{release}"
If the property "interesting_files" (or also just "interesting"),
"author" and "release" are provided, this will issue a query to the
endpoint "/release/interesting_files/{author}/{release}" to retrieve
the list of release interesting files for the specified release,
such as:
/release/interesting_files/OALDERS/HTTP-Message-6.36
For example:
my $list_obj = $cpan->release(
author => 'OALDERS',
release => 'HTTP-Message-6.36',
interesting_files => 1,
) || die( $cpan->error );
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Release objects.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Frelease%2Finteresting_files%2
FOALDERS%2FHTTP-Message-6.36> to see the data returned by the CPAN
REST API.
* "latest", and "author" -> "/release/latest_by_author/{author}"
If the property "latest", and "author" are provided, this will issue
a query to the endpoint "/release/latest_by_author/{author}" to
retrieve the latest releases by the specified author, such as:
/release/latest_by_author/OALDERS
For example:
my $list_obj = $cpan->release(
author => 'OALDERS',
latest => 1,
) || die( $cpan->error );
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Release objects.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Frelease%2Flatest_by_author%2F
OALDERS> to see the data returned by the CPAN REST API.
* "latest", and "distribution" ->
"/release/latest_by_distribution/{distribution}"
If the property "latest", and "distribution" are provided, this will
issue a query to the endpoint
"/release/latest_by_distribution/{distribution}" to retrieve the
latest releases of the specified distribution, such as:
/release/latest_by_distribution/HTTP-Message
For example:
my $release_obj = $cpan->release(
distribution => 'HTTP-Message',
latest => 1,
) || die( $cpan->error );
This would return, upon success, a Net::API::CPAN::Release object
representing the latest "release" for the specified "distribution".
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Frelease%2Flatest_by_distribut
ion%2FHTTP-Message> to see the data returned by the CPAN REST API.
* "modules", "author", and "release" ->
"/release/modules/{author}/{release}"
If the property "modules", "author", and "release" are provided,
this will issue a query to the endpoint
"/release/modules/{author}/{release}" to retrieve the list of
modules in the specified distribution, such as:
/release/modules/OALDERS/HTTP-Message-6.36
For example:
my $list_obj = $cpan->release(
author => 'OALDERS',
release => 'HTTP-Message-6.36',
modules => 1,
) || die( $cpan->error );
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Release objects.
The following options are also supported:
* "join"
You can join a.k.a. merge other objects data by setting
"join" to that object type, such as "module" or "author".
"join" value can be either a string or an array of object
types.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Frelease%2Fmodules%2FOALDERS%2
FHTTP-Message-6.36> to see the data returned by the CPAN REST API.
* "recent" -> "/release/recent"
If the property "recent", alone is provided, this will issue a query
to the endpoint "/release/recent" to retrieve the list of recent
releases, such as:
/release/recent
For example:
my $list_obj = $cpan->release(
recent => 1,
) || die( $cpan->error );
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Release objects.
The following options are also supported:
* "page"
An integer specifying the page offset starting from 1.
* "size"
An integer representing the size of each page, i.e. how many
results are returned per page. This usually defaults to 10.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Frelease%2Frecent> to see the
data returned by the CPAN REST API.
* "versions" -> "distribution"
If the property "versions" is provided having a value representing a
"distribution", this will issue a query to the endpoint
"/release/versions/{distribution}" to retrieve all releases by
versions for the specified distribution, such as:
/release/versions/HTTP-Message
For example:
my $list_obj = $cpan->release(
distribution => 'HTTP-Message',
# or, alternatively: version => '6.35,6.36,6.34',
versions => [qw( 6.35 6.36 6.34 )],
# Set this to true to get a raw list of version -> download URL instead of a list object
# plain => 1,
) || die( $cpan->error );
This would return, upon success, a Net::API::CPAN::List object of
all the "distribution" versions released.
The following options are also supported:
* "versions"
An array reference of versions to return, or a string
specifying the version(s) to return as a comma-sepated value
* "plain"
A boolean value specifying whether the result should be
returned in plain mode.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Frelease%2Fversions%2FHTTP-Mes
sage> to see the data returned by the CPAN REST API and here for the
result in plain text mode
<https://explorer.metacpan.org/?url=%2Frelease%2Fversions%2FHTTP-Mes
sage%3Fplain%3D1>.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
reverse
# Returns a list of all the modules who depend on the specified distribution
my $list_obj = $cpan->reverse( distribution => 'HTTP-Message' ) ||
die( $cpan->error );
# Returns a list of all the modules who depend on the specified module
my $list_obj = $cpan->reverse( module => 'HTTP::Message' ) ||
die( $cpan->error );
This method is used to query the CPAN REST API to retrieve reverse
dependencies, i.e. releases on "CPAN" that depend on the specified
"distribution" or "module".
* "distribution" -> "/reverse_dependencies/dist/{distribution}"
If the property "distribution" representing a distribution is
provided, this will issue a query to the endpoint
"/reverse_dependencies/dist/{distribution}" to retrieve a list of
all the modules who depend on the specified distribution, such as:
/reverse_dependencies/dist/HTTP-Message
For example:
my $list_obj = $cpan->reverse( distribution => 'HTTP-Message' ) ||
die( $cpan->error );
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Release objects.
The following options are also supported:
* "page"
An integer representing the page offset starting from 1.
* "size"
An integer representing the size of each page, i.e. how many
results are returned per page. This usually defaults to 10.
* "sort"
A string representing a field specifying how the result is
sorted.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Freverse_dependencies%2Fdist%2
FHTTP-Message> to see the data returned by the CPAN REST API.
* "module" -> "/reverse_dependencies/module/{module}"
If the property "module" representing a module is provided, this
will issue a query to the endpoint
"/reverse_dependencies/module/{module}" to retrieve a list of all
the modules who depend on the specified module, such as:
/reverse_dependencies/module/HTTP::Message
For example:
my $list_obj = $cpan->reverse( module => 'HTTP::Message' ) ||
die( $cpan->error );
This would return, upon success, a Net::API::CPAN::List object of
Net::API::CPAN::Release objects.
The following options are also supported:
* "page"
An integer representing the page offset starting from 1.
* "size"
An integer representing the size of each page, i.e. how many
results are returned per page. This usually defaults to 10.
* "sort"
A string representing a field specifying how the result is
sorted.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Freverse_dependencies%2Fmodule
%2FHTTP%3A%3AMessage> to see the data returned by the CPAN REST API.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
reverse_dependencies
This is an alias for "reverse"
search
Provided with an hash or hash reference of options and this performs a
search query and returns a Net::API::CPAN::List object, or an
Net::API::CPAN::Scroll depending on the type of search query requested.
There are 3 types of search query:
1. Using HTTP GET method
<https://github.com/metacpan/metacpan-api/blob/master/docs/API-docs.md#g
et-searches>
2. Using HTTP POST method
<https://github.com/metacpan/metacpan-api/blob/master/docs/API-docs.md#p
ost-searches> with Elastic Search query
3. Using HTTP POST method
<https://github.com/metacpan/metacpan-api/blob/master/docs/API-docs.md#p
ost-searches> with Elastic Search query using scroll
source
# Retrieves the source code of the given module path within the specified release
my $string = $cpan->source(
author => 'OALDERS',
release => 'HTTP-Message-6.36',
path => 'lib/HTTP/Message.pm',
) || die( $cpan->error );
# Retrieves the full source of the latest, authorized version of the specified module
my $string = $cpan->source( module => 'HTTP::Message' ) ||
die( $cpan->error );
This method is used to query the CPAN REST API to retrieve the source
code or data of the specified "release" element or "module".
* "author", "release" and "path" ->
"/source/{author}/{release}/{path}"
If the properties "author", "release" and "path" are provided, this
will issue a query to the endpoint
"/source/{author}/{release}/{path}" to retrieve the source code of
the given module path within the specified release, such as:
/source/OALDERS/HTTP-Message-6.36/lib/HTTP/Message.pm
For example:
my $string = $cpan->source(
author => 'OALDERS',
release => 'HTTP-Message-6.36',
path => 'lib/HTTP/Message.pm',
) || die( $cpan->error );
This will return a string representing the source data of the file
located at the specified "path" and "release".
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fsource%2FOALDERS%2FHTTP-Messa
ge-6.36%2Flib%2FHTTP%2FMessage.pm> to see the data returned by the
CPAN REST API.
* "module" -> "/source/{module}"
If the properties "module" is provided, this will issue a query to
the endpoint "/source/{module}" to retrieve the full source of the
latest, authorized version of the specified module, such as:
/source/HTTP::Message
For example:
my $string = $cpan->source( module => 'HTTP::Message' ) ||
die( $cpan->error );
This will return a string representing the source data of the
specified "module".
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fsource%2FHTTP%3A%3AMessage>
to see the data returned by the CPAN REST API.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
suggest
This takes a string and will issue a query to the endpoint
"/search/autocomplete/suggest" to retrieve the suggested result set
based on the autocomplete search query, such as:
/search/autocomplete/suggest?q=HTTP
For example:
my $list_obj = $cpan->suggest( query => 'HTTP' ) || die( $cpan->error );
This would, upon success, return a Net::API::CPAN::List object of
Net::API::CPAN::Release::Suggest objects.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fsearch%2Fautocomplete%2Fsuggest%3
Fq%3DHTTP> to see the data returned by the CPAN REST API.
top_uploaders
This will issue a query to the endpoint "/release/top_uploaders" to
retrieve an hash object of the top uploading "authors" with the total as
the key's value, such as:
/release/top_uploaders
For example:
my $hash_ref = $cpan->top_uploaders || die( $cpan->error );
This would return, upon success, an hash object of "author" and their
recent total number of "release" upload on "CPAN"
For example:
{
OALDERS => 12,
NEILB => 7,
}
The following options are also supported:
* "range"
A string specifying the result range. Valid values are "all",
"weekly", "monthly" or "yearly". It defaults to "weekly"
* "size"
An integer representing the size of each page, i.e. how many
results are returned per page. This usually defaults to 10.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Frelease%2Ftop_uploaders> to see
the data returned by the CPAN REST API.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
web
This takes a string and will issue a query to the endpoint "/search/web"
to retrieve the result set based on the search query specified similar
to the one on the MetaCPAN website, such as:
/search/web?q=HTTP
For example:
my $list_obj = $cpan->web(
query => 'HTTP',
from => 0,
size => 10,
) || die( $cpan->error );
This would, upon success, return a Net::API::CPAN::List object of
Net::API::CPAN::Module objects.
Search terms can be:
* can be unqualified string, such as "paging"
* can be author, such as "author:OALDERS"
* can be module, such as "module:HTTP::Message"
* can be distribution, such as "dist:HTTP-Message"
The following options are also supported:
* "collapsed"
Boolean. When used, this forces a collapsed even when searching
for a particular distribution or module name.
* "from"
An integer that represents offset to use in the result set.
* "size"
An integer that represents the number of results per page.
You can try it out on CPAN Explorer
<https://explorer.metacpan.org/?url=%2Fsearch%2Fweb%3Fq%3DHTTP> to see
the data returned by the CPAN REST API.
Upon failure, an error will be set and "undef" will be returned in
scalar context, or an empty list in list context.
TERMINOLOGY
The MetaCPAN REST API has quite a few endpoints returning sets of data
containing properties. Below are the meanings of some of those keywords:
* "author"
For example "JOHNDOE"
This is a "CPAN" id, and "distribution" author. It is also referred
as "cpanid"
* "cpanid"
For example "JOHNDOE"
See "author"
* "contributor"
For example: "JOHNDOE"
A "contributor" is a "CPAN" author who is contributing code to an
"author"'s "distribution".
* "distribution"
For example: "HTTP-Message"
This is a bundle of modules distributed over "CPAN" and available
for download. A "distribution" goes through a series of "releases"
over the course of its lifetime.
* "favorite"
"favorite" relates to the appreciation a "distribution" received by
having registered and non-registered user marking it as one of their
favorite distributions.
* "file"
A "file" is an element of a "distribution"
* "module"
For example "HTTP::Message"
This has the same meaning as in Perl. See perlmod for more
information on Perl modules.
* "package"
For example "HTTP::Message"
This is similar to "module", but a "package" is a "class" and a
"module" is a file.
* "permission"
A "permission" defines the role a user has over a "distribution" and
is one of "owner" or "co_maintainer"
* "release"
For example: "HTTP-Message-6.36"
A "release" is a "distribution" being released with a unique version
number.
* "reverse_dependencies"
This relates to the "distributions" depending on any given
"distribution"
ERRORS
This module does not die or croak, but instead set an error object using
"error" in Module::Generic and returns "undef" in scalar context, or an
empty list in list context.
You can retrieve the latest error object set by calling error inherited
from Module::Generic
Errors issued by this distributions are all instances of class
Net::API::CPAN::Exception
METACPAN OPENAPI SPECIFICATIONS
From the information I could gather, I have produced the specifications
<https://gitlab.com/jackdeguest/Net-API-CPAN/-/blob/master/build/cpan-op
enapi-spec-3.0.0.pl> for Open API <https://spec.openapis.org/oas/v3.0.0>
v3.0.0 for your reference. You can also find it here
<https://gitlab.com/jackdeguest/Net-API-CPAN/-/blob/master/build/cpan-op
enapi-spec-3.0.0.json> in "JSON" format.
AUTHOR
Jacques Deguest <jack@deguest.jp>
SEE ALSO
Meta CPAN API documentation
<https://github.com/metacpan/metacpan-api/blob/master/docs/API-docs.md>
<https://metacpan.org/>, <https://www.cpan.org/>
Net::API::CPAN::Activity, Net::API::CPAN::Author,
Net::API::CPAN::Changes, Net::API::CPAN::Changes::Release,
Net::API::CPAN::Contributor, Net::API::CPAN::Cover,
Net::API::CPAN::Diff, Net::API::CPAN::Distribution,
Net::API::CPAN::DownloadUrl, Net::API::CPAN::Favorite,
Net::API::CPAN::File, Net::API::CPAN::Module, Net::API::CPAN::Package,
Net::API::CPAN::Permission, Net::API::CPAN::Rating,
Net::API::CPAN::Release
Net::API::CPAN::Filter, Net::API::CPAN::List, Net::API::CPAN::Scroll
Net::API::CPAN::Mock
COPYRIGHT & LICENSE
Copyright(c) 2023 DEGUEST Pte. Ltd.
All rights reserved
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.