- NAME
- SYNOPSIS
- DESCRIPTION
  - Iterators
- ENVIRONMENT
- BUGS

# NAME

ActiveState::CPAN - Get information and files from CPAN

# SYNOPSIS

     use ActiveState::CPAN ();
     my $cpan = ActiveState::CPAN->new;

# DESCRIPTION

ActiveState::CPAN provides an interface for fetching files off CPAN and for extracting information from the various meta and index files. The following methods are provided:

$cpan = ActiveState::CPAN->new( %options )

  This constructs a new ActiveState::CPAN object. The following options are recognized:

  mirror => $url_or_path

    Give the URL of the CPAN mirror to fetch files from. The module works best with a local CPAN mirror and this option might also be given as a path to the local mirror. If not provided, then the CPAN_ROOT environment variable is consulted, and finally a set of hardcoded URLs are used.

  cache => $path

    The cache is a directory containing a partial mirror of CPAN. If files are requested from remote mirrors or backpan they will be stored in the cache and served back from here the next time they are requested.

    You need to specify a cache if you rely on $cpan->get_file() to return file system path names for all CPAN paths.

  backpan => $url

    Give the URL of the backpan server to use to fetch files that have expired from CPAN. The default is "http://backpan.cpan.org/".

    An explict `undef` can be passed to disable the fallback on Backpan.

  verbose => $bool

    If TRUE print trace messages to STDOUT about operations are taken, like downloads from remote servers. Default is TRUE.

$cpan->clear_cache

  This will delete all the files in the cache directory. Use with care. This is a noop if you did not pass the `cache` option to the constructor.

$cpan->local_mirror

  Returns the file system path to the local mirror used. Returns `undef` if there is no local mirror.

$cpan->author( $author_id )

  Returns the email alias for the given CPAN author. The alias is on the form:

          Gisle Aas <gisle@aas.no>

$cpan->authors

  Returns a reference to a hash that maps author ids to email aliases.

$cpan->packages( %opt )

  This returns the list of packages on CPAN. The packages are returned as a reference to a hash with the following keys:

  name

    This is the bare name of the package. It's a string like "libwww-perl".

  version

    This is the version number of the package. It's a string like "5.812".

  maturity

    The maturity of the distribution. This will be either "released" or "developer".

  author

    This is the CPAN author id owning the package. It's a string like "GAAS".

  extension

    This is the file suffix of the package file. It's a string like "tar.gz"

  path

    This is the CPAN relative path of the package file. It's a string like "authors/id/G/GA/GAAS/libwww-perl-5.812.tar.gz".

  The passed in options determine what packages are returned. The recognized options are:

  indexed => 1

    If passed with a TRUE value only list packages with indexed modules (as determined by the CPAN indexer).

  recent => 1

    The most recently uploaded packages are returned first.

$cpan->packages_iter( %opt )

  This returns an iterator that returns the packages on CPAN. The iterator returns the name, version, maturity, author, extension and path of the package. In scalar context the path is returned.

  The recognized options are the same as for packages() described above.

$cpan->package_info( $path )

  Returns a hash reference like the ones that package() returns. In list context it returns separate values like package iterator does.

$cpan->modules_iter()

  This returns an iterator that returns the indexed modules on CPAN. The iterator returns module name, module version and the CPAN relative package path. In scalar context the module name is returned.

$cpan->files( %opt )

  This returns the list of path names of the files on CPAN. Symlinks are not returned. The options passed in can be used to select what path names are returned. The recognized options are:

  matching => qr/.../

    Only list path names that match the given regular expression.

  package => 1

    If passed with a TRUE value only list package files, also called CPAN distributions. These have normally names that end in .tar.gz.

  author => $author_id

    Only list files uploaded by the given CPAN author. The $author_id is a string like "GAAS".

  order_by => $field
  order_by => "$field desc"

    Return the files sorted by the given field, which can be one of "path", "size", "mtime". Append the string " desc" to the field name to sort in descending order. For example:

           order_by => "mtime desc"

    will return the most recently uploaded files first.

$cpan->files_iter( %opt )

  This returns an iterator that returns the files on CPAN. Symlinks are not returned. The iterator returns the path name, the size and the last modified timestamp. In scalar context only the path name is returned.

  The recognized options are the same as for files() described above.

  The timestamp is in ISO 8601 compact format: YYYYMMDDThhmmss (with a literal "T").

$cpan->get( $path )

  Returns the full content of the given file or undef if the file can't be found. Compressed files are automatically uncompressed.

$cpan->get_file( $path )

  Returns the file sytem path that corresponds to the given CPAN path. This will either be the path to a local CPAN mirror or a path within the cache. If there is no cache configured, then this function might return `undef`.

$cpan->open( $path )

  Opens the given CPAN file and returns a file handle to it. Croaks if the file can't be found or opened. Compressed files are automatically uncompressed.

$cpan->unpack( $path )
$cpan->unpack( $path, $dir )

  Will unpack a CPAN package to the given directory. If $dir isn't provided it defaults to the basename of $path. It returns the path to the unpacked directory ($dir) and croaks if it gets into trouble.

## Iterators

The methods with names that end with `_iter` return iterators. Iterators are functions that return the next element in a sequence each time they are called, and return nothing once the sequence is exhausted. Example usage:

        my $next = $cpan->files_iter(author => "GAAS", package => 1);
        while (my($path, $size, $mtime) = $next->()) {
            print "$path $size $mtime\n";
        }

More information about iterators at Iterator::Simple. This module also contains some utilities for wrapping and combining iterators.

# ENVIRONMENT

If the CPAN_ROOT environment variable is set it will be used as the primary mirror. It can be an URL or the name of a directory.

# BUGS

none.