Users.pm

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