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.