File Coverage

blib/lib/PAUSE/Users.pm
Criterion Covered Total %
statement 20 20 100.0
branch n/a
condition n/a
subroutine 7 7 100.0
pod 0 1 0.0
total 27 28 96.4


line stmt bran cond sub pod time code
1             package PAUSE::Users;
2             $PAUSE::Users::VERSION = '0.09';
3             # ABSTRACT: interface to PAUSE's users file (00whois.xml)
4              
5 2     2   72043 use strict;
  2         9  
  2         59  
6 2     2   10 use warnings;
  2         5  
  2         60  
7              
8 2     2   1026 use MooX::Role::CachedURL 0.04;
  2         201429  
  2         74  
9              
10 2     2   1127 use Moo;
  2         6691  
  2         12  
11 2     2   1851 use PAUSE::Users::User;
  2         6  
  2         69  
12 2     2   921 use PAUSE::Users::UserIterator;
  2         8  
  2         352  
13             with 'MooX::Role::CachedURL';
14              
15             has '+url' =>
16             (
17             default => sub { 'http://www.cpan.org/authors/00whois.xml' },
18             );
19              
20             has '+max_age' =>
21             (
22             default => sub { '1 day' },
23             );
24              
25             sub user_iterator
26             {
27 2     2 0 459749 my $self = shift;
28              
29 2         21 return PAUSE::Users::UserIterator->new( users => $self );
30             }
31              
32             1;
33              
34             =encoding utf8
35              
36             =head1 NAME
37              
38             PAUSE::Users - interface to PAUSE's users file (00whois.xml)
39              
40             =head1 SYNOPSIS
41              
42             use PAUSE::Users;
43              
44             my $users = PAUSE::Users->new(max_age => '1 day');
45             my $iterator = $users->user_iterator();
46              
47             while (defined($user = $iterator->next_user)) {
48             print "PAUSE id = ", $user->id, "\n";
49             print "Name = ", $user->fullname, "\n";
50             }
51              
52             =head1 DESCRIPTION
53              
54             PAUSE::Users provides an interface to the C<00whois.xml>
55             file produced by the Perl Authors Upload Server (PAUSE).
56             This file contains a list of all PAUSE users, with some basic information
57             about each user.
58              
59             By default PAUSE::Users will request the file from PAUSE at most once a day,
60             using a locally cached copy otherwise. You can specify the caching time
61             using the C attribute. You can express the caching time using any
62             of the expressions supported by L.
63              
64             At the moment this module supports a single iterator interface.
65             The C method returns an instance of L
66             (I know, bit of an odd name).
67              
68             Here's the simple skeleton for iterating over all PAUSE users:
69              
70             my $iterator = PAUSE::Users->new()->user_iterator();
71              
72             while (my $user = $iterator->next_user) {
73             # doing something with $user
74             }
75              
76             =head1 Constructor
77              
78             The constructor takes the following attributes
79              
80             =over 4
81              
82             =item * cache_path
83             Specify the full path to the local file where the contents of
84             00whois.xml should be cached. If not set, an appropriate
85             path for your operating system will be generated using L.
86              
87             If you don't set this attribute, then after instantiating PAUSE::Users
88             you can get this attribute to see where the content is being cached.
89              
90             =item * path
91             The full path to your own copy of 00whois.xml.
92             If this is provided, then PAUSE::Users won't check to see if
93             CPAN's copy is more recent than your file.
94              
95             =item * max_age
96             The maximum age for the cached copy, which is stored in the file
97             referenced with the C attribute. If your cached copy
98             was updated with the last C seconds, then PAUSE::Users
99             won't even check whether the CPAN copy has been updated.
100              
101             You can specify the C using any of the notations supported
102             by L. It defaults to '1 day'.
103              
104             =back
105              
106             =head1 The user object
107              
108             The user object supports the following methods:
109              
110             =over 4
111              
112             =item id
113              
114             The user's PAUSE id. For example my PAUSE id is NEILB.
115              
116             =item fullname
117              
118             The full name of the user, as they would write it.
119             So expect to see Kanji and plenty of other non-ASCII characters here.
120             You are UTF-8 clean, right?
121              
122             =item asciiname
123              
124             An ASCII version of the user's name. This might be the romaji version
125             of a Japanese name, or the fullname without any accents.
126             For example, author NANIS has fullname A. Sinan Ünür,
127             and asciiname A. Sinan Unur.
128              
129             =item email
130              
131             The contact email address for the author, or C if the
132             author specified that their email address should not be shared.
133              
134             =item has_cpandir
135              
136             Set to C<1> if the author has a directory on CPAN, and 0 if not.
137             This is only true (1) if the author I has something on CPAN.
138             If you upload a dist then delete it, the dist will be on BackPAN but
139             not on CPAN, and C will return 0.
140              
141             =item homepage
142              
143             The author's homepage, if they've specified one.
144             This might be their blog, their employer's home page,
145             or any other URL they've chosen to associate with their account.
146              
147             =item introduced
148              
149             When the author's PAUSE account was created, specified as
150             seconds since the epoch. This may change to being an instance
151             of L.
152              
153             =back
154              
155             =head1 00whois.xml file format
156              
157             The meat of the file is a list of CcpanidE> elements,
158             each of which contains details of one PAUSE user:
159              
160            
161            
162             last-generated='Sat Nov 16 18:19:01 2013 UTC'
163             generated-by='/home/puppet/pause/cron/cron-daily.pl'>
164            
165             ...
166            
167            
168             NEILB
169             author
170             Neil Bowers
171             neil@bowers.com
172             1
173            
174            
175             ...
176            
177            
178              
179             In addition to all PAUSE users, the underlying file (00whois.xml)
180             also contains details of perl.org mailing lists.
181             For example, here's the entry for Perl5-Porters:
182              
183            
184             P5P
185             list
186             The Perl5 Porters Mailing List
187             perl5-porters@perl.org
188             Mail perl5-porters-subscribe@perl.org
189             0
190            
191              
192             All B type entries are ignored by C.
193              
194             =head1 NOTES
195              
196             I started off trying a couple of XML modules, but I was surprised at
197             how slow they were, and not really iterator-friendly.
198             So the current version of the iterator does line-based parsing using
199             regexps. You really shouldn't do that, but 00whois.xml is automatically
200             generated, follows a well-defined format, which very rarely changes.
201              
202             =head1 SEE ALSO
203              
204             L is another module that parses 00whois.xml,
205             but you have to download it yourself first.
206              
207             L is another module for getting information about
208             PAUSE users, but based on C<01.mailrc.txt.gz>.
209              
210             L provides a similar interface to 00whois.xml.
211              
212             L does a real-time search for CPAN authors
213             using L.
214              
215             L fetches 4 of the PAUSE indices and lets you query an aggregation
216             of the data they contain.
217              
218             L, L.
219              
220             =head1 REPOSITORY
221              
222             L
223              
224             =head1 AUTHOR
225              
226             Neil Bowers Eneilb@cpan.orgE
227              
228             =head1 COPYRIGHT AND LICENSE
229              
230             This software is copyright (c) 2013 by Neil Bowers .
231              
232             This is free software; you can redistribute it and/or modify it under
233             the same terms as the Perl 5 programming language system itself.
234              
235             =cut
236