Neil Bowers > PAUSE-Packages-0.15 > PAUSE::Packages

Download:
PAUSE-Packages-0.15.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  1
View/Report Bugs
Module Version: 0.15   Source  

NAME ^

PAUSE::Packages - interface to PAUSE's packages file (02packages.details.txt)

SYNOPSIS ^

  use PAUSE::Packages 0.12;

  my $pp       = PAUSE::Packages->new;
  my $iterator = $pp->release_iterator();

  while (my $release = $iterator->next_release) {
    print 'path = ', $release->path, "\n";
    print '   modules = ', join(', ', @{ $release->modules }), "\n";
  }

  $release = $pp->release('Module-Path');

  # to parse a local file
    my $pp = PAUSE::Packages->new(
        url => 'file:///path/to/02packages.details.txt',
        ua  => LWP::UserAgent->new,
    );

DESCRIPTION ^

NOTE: this is very much an alpha release. any and all feedback appreciated.

PAUSE::Packages provides an interface to the 02packages.details.txt file produced by the Perl Authors Upload Server (PAUSE). The file records what version of what modules are included in each release of a distribution that is on CPAN.

PAUSE::Packages processes 02packages.details.txt and caches a transformed version of the data, with the following characteristics:

The interface for this distribution is very much still in flux, as is the documentation.

constructor ^

The constructor (new()) can be passed an argument path, along with a path to a local copy of the cached format used by PAUSE::Packages:

 $pp = PAUSE::Packages->new(path => 'mypackages.txt');

Note: this is not the same format used by 02packages.details.txt, as described above.

If you don't specify a path, then the local cache path is generated, and you can use the path attribute to find out what it is:

 $pp = PAUSE::Packages->new();
 print "cache path = ", $pp->path, "\n";

In a future release this will change: there will be separate attributes for the cache path and the path to your own local copy.

METHODS ^

release_iterator()

See the SYNOPSIS.

This supports one optional argument, well_formed, which if true says that the iterator should only return releases where the dist name and author's PAUSE id could be found:

 my $iterator = PAUSE::Packages->new()->release_iterator(
                    well_formed => 1
                );

This saves you from having to write code like the following:

 while (my $release = $iterator->next_release) {
    next unless defined($release->distinfo);
    next unless defined($release->distinfo->dist);
    next unless defined($release->distinfo->cpanid);
    ...
 }

release($DISTNAME)

Takes a dist name and returns an instance of PAUSE::Packages::Release, or undef if a release couldn't be found for the specified distname.

ua( MyUserAgent->new )

Allows you to provide your own UserAgent. This is useful if you're working off a local copy of 02packages.details.txt The default UserAgent is HTTP::Tiny, which does not support the file:// schema. So, if you want to work with a local file you can either set up local web server using something like App::HTTPThis, or you can provide a your own UserAgent (like LWP::UserAgent which does support this behaviour.

url

The URL to the 02packages.details.txt which you would like to parse. Defaults to cpan.org If you want to use the file:// scheme to fetch your local package, be sure to provide your own UserAgent. See the ua method above.

NOTE ^

The behaviour of this module changed between version 0.01 and 0.02, so you should make sure you're using 0.02 or later:

  use PAUSE::Packages 0.02;

SEE ALSO ^

There are at least three other modules on CPAN for parsing 02packages.details.txt. There are two main differences between these modules and PAUSE::Packages: (1) you have to download 02packages yourself, and (2) if there are multiple releases of a dist on CPAN, containing different modules (eg due to refactoring), then you'll see the union of all modules, instead of just the modules in the most recent release.

REPOSITORY ^

https://github.com/neilbowers/PAUSE-Packages

AUTHOR ^

Neil Bowers <neilb@cpan.org>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2013-2014 by Neil Bowers <neilb@cpan.org>.

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

syntax highlighting: