Neil Bowers > PAUSE-Permissions-0.09 > PAUSE::Permissions

Download:
PAUSE-Permissions-0.09.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

New  1
Open  1
View/Report Bugs
Module Version: 0.09   Source   Latest Release: PAUSE-Permissions-0.10

NAME ^

PAUSE::Permissions - interface to PAUSE's module permissions file (06perms.txt)

SYNOPSIS ^

  use PAUSE::Permissions 0.08;
  
  my $pp = PAUSE::Permissions->new;
  my $mp = $pp->module_permissions('HTTP::Client');
  
  my $owner    = $mp->owner;
  my @comaints = $mp->co_maintainers;

  my $iterator = $pp->module_iterator();
  while (my $mp = $iterator->next_module) {
    print "module = ", $mp->name, "\n";
    print "  owner = ", $mp->owner // 'none', "\n";
  }

DESCRIPTION ^

PAUSE::Permissions provides an interface to the 06perms.txt file produced by the Perl Authors Upload Server (PAUSE). The file records who has what permissions for every module on CPAN. The format and interpretation of this file are covered in "The 06perms.txt file" below.

By default, the module will mirror 06perms.txt from CPAN, using HTTP::Tiny to request it and store it locally. By default it will get the file from http://www.cpan.org, but you can pass an alternate URI to the constructor:

  $perms_uri = "http://$CPAN_MIRROR/modules/06perms.txt";
  $pp = PAUSE::Permissions->new(uri => $perms_uri);

If you've already got a copy lying around, you can tell the module to use that:

  $pp = PAUSE::Permissions->new( filename => '/tmp/06perms.txt' );

Having created an instance of PAUSE::Permissions, you can then call the module_permissions method to get the permissions for a particular module. The SYNOPSIS gives the basic usage.

Note: you should make sure you're using version 0.08 or later. PAUSE now treats package names case insensitively with respect to permissions, so this module does now as well.

METHODS ^

There are only four methods you need to know: the constructor (new), getting an iterator over individual entries (entry_iterator), getting an iterator over modules (module_iterator), and module_permissions().

new

The constructor takes a hash of options:

So you might use the following, to get 06perms.txt from your 'local' CPAN mirror and store it somewhere of your choosing:

  $pp = PAUSE::Permissions->new(
                uri     => 'http://cpan.inode.at/modules/06perms.txt',
                cachdir => '/tmp/pause',
            );

module_iterator

This is a method that returns an instance of PAUSE::Permissions::ModuleIterator, which provides a simple mechanism for iterating over the whole permissions file, module by module:

  $pp       = PAUSE::Permissions->new();
  $iterator = $pp->module_iterator();
  
  while (my $module = $iterator->next_module) {
    print "module    = ", $module->name,           "\n";
    print "owner     = ", $module->owner,          "\n";
    print "co-maints = ", $module->co_maintainers, "\n";
  }

The next_module() method returns either an instance of PAUSE::Permissions::Module, or undef when the end of the file is reached.

entry_iterator

This is a method that returns an instance of PAUSE::Permissions::EntryIterator, which provides a simple mechanism for iterating over the whole permissions file, line by line:

  $pp       = PAUSE::Permissions->new();
  $iterator = $pp->entry_iterator();
  while (my $entry = $iterator->next) {
    print "module = ", $entry->module,     "\n";
    print "user   = ", $entry->user,       "\n";
    print "perm   = ", $entry->permission, "\n";
  }

The module method returns a module name; user returns the PAUSE id of a PAUSE user; perm is one of the three permission identifiers ('m', 'f', or 'c').

module_permissions

The module_permissions method takes a single module name, and returns an instance of PAUSE::Permissions::Module:

  $mp = $pp->module_permissions( $module_name );

Refer to the documentation for PAUSE::Permissions::Module, but the key methods are:

module_permissions() returns undef if the module wasn't found in the permissions list. If you've only just registered your new module, or only just uploaded the first release, then it might not have made it into the file yet.

The 06perms.txt file ^

You can find the file on CPAN:

http://www.cpan.org/modules/06perms.txt

As of October 2012 this file is 8.4M in size.

The file starts with a header, followed by one blank line, then the body. The body contains one line per module per user:

  Config::Properties,CMANLEY,c
  Config::Properties,RANDY,f
  Config::Properties,SALVA,m

Each line has three values, separated by commas:

Note that this file lists modules, not distributions. Every module in a CPAN distribution will be listed separately in this file. Modules are listed in alphabetical order, and for a given module, the PAUSE ids are listed in alphabetical order.

There are three characters that can appear in the permissions column:

If you first upload a module, you'll get an 'f' against you in the file. If you subsequently register the module, you'll get an 'm' against you. Internally PAUSE will have you recorded with both an 'm' and an 'f', but 06perms.txt only lists the highest precedence permission for each user.

What do the permissions mean?

SEE ALSO ^

App::PAUSE::CheckPerms checks whether all modules in (your) CPAN distributions have the same permissions.

tmpdir() in File::Spec::Functions is used to get a local directory for caching 06perms.txt.

HTTP::Tiny is used to mirror 06perms.txt from CPAN.

TODO ^

REPOSITORY ^

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

AUTHOR ^

Neil Bowers <neilb@cpan.org>

Thanks to Andreas König, for patiently answering many questions on how this stuff all works.

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2012-2013 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: