NAME

XPAN::Query - Query a {CPAN,MiniCPAN,DarkPAN} mirror

VERSION

This document describes version 0.05 of XPAN::Query (from Perl distribution XPAN-Query), released on 2014-08-16.

SYNOPSIS

 use XPAN::Query qw(
     list_xpan_packages
     list_xpan_modules
     list_xpan_dists
     list_xpan_authors
 );
 my $res = list_ubuntu_releases(detail=>1);
 # raw data is in $Ubuntu::Releases::data;

DESCRIPTION

XPAN is a term I coined for any repository (directory tree, be it on a local filesystem or a remote network) that has structure like a CPAN mirror, specifically having a modules/02packages.details.txt.gz file. This includes a normal CPAN mirror, a MiniCPAN, or a DarkPAN. Currently it excludes BackPAN, because it does not have 02packages.details.txt.gz, only authors/id/C/CP/CPANID directories.

With this module, you can query various things about the repository. This module fetches 02packages.details.txt.gz and parses it (caching it locally for a period of time).

FUNCTIONS

list_xpan_authors(%args) -> any

List authors in {CPAN,MiniCPAN,DarkPAN} mirror.

Examples:

 list_xpan_authors( url => "/cpan");

List all authors.

 list_xpan_authors( query => "MICHAEL", url => "/cpan"); # -> ["MICHAEL", "MICHAELW"]

Grep by CPAN ID.

Arguments ('*' denotes required arguments):

• cache_period => int (default: 86400)

• detail => bool

  If set to true, will return array of records instead of just ID's.

• query => str

  Search query.

• temp_dir => str

• url* => str

  URL to repository, e.g. '/cpan' or 'http://host/cpan'.

Return value:

 (any)

By default will return an array of CPAN ID's. If you set detail to true, will return array of records.

list_xpan_dists(%args) -> any

List distributions in {CPAN,MiniCPAN,DarkPAN} mirror.

Examples:

 list_xpan_dists( url => "/cpan");

List all distributions.

 list_xpan_dists( query => "data-table", url => "/cpan");

Result: [ { author => "BIGJ", file => "Data-TableAutoSum-0.08.tar.gz", name => "Data-TableAutoSum", version => 0.08, }, { author => "EZDB", file => "Data-Table-Excel-0.5.tar.gz", name => "Data-Table-Excel", version => 0.5, }, { author => "EZDB", file => "Data-Table-1.70.tar.gz", name => "Data-Table", version => "1.70", }, ]. Grep by distribution name, return detailed record.

 list_xpan_dists();

Filter by author, return JSON.

For simplicity and performance, this module parses distribution names from tarball filenames mentioned in 02packages.details.txt.gz, so it is not perfect (some release tarballs, especially older ones, are not properly named). For more proper way, one needs to read the metadata file (*.meta) for each distribution.

Arguments ('*' denotes required arguments):

• author => str

  Filter by author.

• cache_period => int (default: 86400)

• detail => bool

  If set to true, will return array of records instead of just ID's.

• query => str

  Search query.

• temp_dir => str

• url* => str

  URL to repository, e.g. '/cpan' or 'http://host/cpan'.

Return value:

 (any)

By default will return an array of distribution names. If you set detail to true, will return array of records.

list_xpan_modules(%args) -> any

List packages in {CPAN,MiniCPAN,DarkPAN} mirror.

Arguments ('*' denotes required arguments):

• author => str

  Filter by author.

• cache_period => int (default: 86400)

• detail => bool

  If set to true, will return array of records instead of just ID's.

• dist => str

  Filter by distribution.

• query => str

  Search query.

• temp_dir => str

• url* => str

  URL to repository, e.g. '/cpan' or 'http://host/cpan'.

Return value:

 (any)

By default will return an array of package names. If you set detail to true, will return array of records.

list_xpan_packages(%args) -> any

List packages in {CPAN,MiniCPAN,DarkPAN} mirror.

Arguments ('*' denotes required arguments):

• author => str

  Filter by author.

• cache_period => int (default: 86400)

• detail => bool

  If set to true, will return array of records instead of just ID's.

• dist => str

  Filter by distribution.

• query => str

  Search query.

• temp_dir => str

• url* => str

  URL to repository, e.g. '/cpan' or 'http://host/cpan'.

Return value:

 (any)

By default will return an array of package names. If you set detail to true, will return array of records.

SEE ALSO

Parse::CPAN::Packages is a more full-featured and full-fledged module to parse 02packages.details.txt.gz. The downside is, startup and performance is slower.

Parse::CPAN::Packages::Fast is created as a more lightweight alternative to Parse::CPAN::Packages.

PAUSE::Packages also parses 02packages.details.txt.gz, it's just that the interface is different.

PAUSE::Users parses authors/00whois.xml. XPAN::Query does not parse this file, it is currently not generated/downloaded by CPAN::Mini, for example.

Tangentially related: BackPAN::Index

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/XPAN-Query.

SOURCE

Source repository is at https://github.com/sharyanto/perl-XPAN-Query.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=XPAN-Query

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Steven Haryanto.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm XPAN::Query

perl -MCPAN -e shell
install XPAN::Query