NAME

PAUSE::Users - interface to PAUSE's users file (00whois.xml)

SYNOPSIS

 use PAUSE::Users;

 my $users    = PAUSE::Users->new();
 my $iterator = $users->user_iterator();

 while (defined($user = $iterator->next_user)) {
   print "PAUSE id = ", $user->id, "\n";
   print "Name     = ", $user->fullname, "\n";
 }

DESCRIPTION

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

PAUSE::Users provides an interface to the 00whois.xml file produced by the Perl Authors Upload Server (PAUSE). This file contains a list of all PAUSE users, with some basic information about each user.

At the moment this module supports a single iterator interface. The next_user() method returns an instance of PAUSE::Users::User (I know, bit of an odd name).

Here's the simple skeleton for iterating over all PAUSE users:

 my $iterator = PAUSE::Users->new()->user_iterator();

 while (my $user = $iterator->next_user) {
    # doing something with $user
 }

The user object supports the following methods:

id

The user's PAUSE id. For example my PAUSE id is NEILB.

fullname

The full name of the user, as they would write it. So expect to see Kanji and plenty of other non-ASCII characters here. You are UTF-8 clean, right?

asciiname

An ASCII version of the user's name. This might be the romaji version of a Japanese name, or the fullname without any accents. For example, author NANIS has fullname A. Sinan Ünür, and asciiname A. Sinan Unur.

email

The contact email address for the author, or CENSORED if the author specified that their email address should not be shared.

has_cpandir

Set to 1 if the author has a directory on CPAN, and 0 if not. This is only true (1) if the author currently has something on CPAN. If you upload a dist then delete it, the dist will be on BackPAN but not on CPAN, and has_cpandir will return 0.

homepage

The author's homepage, if they've specified one. This might be their blog, their employer's home page, or any other URL they've chosen to associate with their account.

introduced

When the author's PAUSE account was created, specified as seconds since the epoch. This may change to being an instance of DateTime.

00whois.xml file format

The meat of the file is a list of <cpanid> elements, each of which contains details of one PAUSE user:

 <?xml version="1.0" encoding="UTF-8"?>
 <cpan-whois xmlns='http://www.cpan.org/xmlns/whois'
            last-generated='Sat Nov 16 18:19:01 2013 UTC'
            generated-by='/home/puppet/pause/cron/cron-daily.pl'>
  
  ...
  
  <cpanid>
   <id>NEILB</id>
   <type>author</type>
   <fullname>Neil Bowers</fullname>
   <email>neil@bowers.com</email>
   <has_cpandir>1</has_cpandir>
  </cpanid>
  
  ...
  
 </cpan-whois>

NOTES

I started off trying a couple of XML modules, but I was surprised at how slow they were, and not really iterator-friendly. So the current version of the iterator does line-based parsing using regexps. You really shouldn't do that, but 00whois.xml is automatically generated, follows a well-defined format, which very rarely changes.

SEE ALSO

Parse::CPAN::Whois is another module that parses 00whois.xml, but you have to download it yourself first.

Parse::CPAN::Authors is another module for getting information about PAUSE users, but based on 01.mailrc.txt.gz.

PAUSE::Permissions, PAUSE::Packages.

REPOSITORY

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

AUTHOR

Neil Bowers <neilb@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 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.