Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

added correct README

  • Loading branch information...
commit 9318a7c88ab5dce768a968a4964da34c603acf3b 1 parent d5f4440
Barbie barbie authored
3  Changes
... ... @@ -1,5 +1,8 @@
1 1 Revision history for CPAN-Testers-WWW-Reports-Query-Reports
2 2
  3 +0.02 31/03/2012
  4 + - now with the correct README!
  5 +
3 6 0.01 30/03/2012
4 7 - First release
5 8
4 META.yml
... ... @@ -1,6 +1,6 @@
1 1 --- #YAML:1.0
2 2 name: CPAN::Testers::WWW::Reports::Query::Reports
3   -version: 0.01
  3 +version: 0.02
4 4 abstract: Retrieve CPAN Testers metadata direct from the CPAN Testers website.
5 5 author:
6 6 - Barbie <barbie@cpan.org>
@@ -22,7 +22,7 @@ build_requires:
22 22 provides:
23 23 CPAN::Testers::WWW::Reports::Query::Reports:
24 24 file: lib/CPAN/Testers/WWW/Reports/Query/Reports.pm
25   - version: 0.01
  25 + version: 0.02
26 26
27 27 resources:
28 28 repository: http://github.com/barbie/cpan-testers-www-reports-query-reports
148 README
... ... @@ -1,57 +1,57 @@
1   -User Contributed Documentation CPAN::Testers::WWW::Reports::Query::AJAX(3)
  1 +User Contributed Documentation CPAN::Testers::WWW::Reports::Query::Reports(3)
2 2
3 3
4 4 NAME
5   - CPAN::Testers::WWW::Reports::Query::AJAX - Get specific CPAN Testers
6   - results
  5 + CPAN::Testers::WWW::Reports::Query::Reports - Retrieve CPAN Testers
  6 + metadata direct from the CPAN Testers website.
  7 +
  8 +DESCRIPTION
  9 + This module queries the CPAN Testers website and retrieves a data set.
  10 + For a date request, the data set returned relates to the ids that can
  11 + be retrieved for that date. A range request will return the records for
  12 + the requested IDs.
7 13
8 14 SYNOPSIS
9   - my $query = CPAN::Testers::WWW::Reports::Query::AJAX->new(
10   - distribution => 'App-Maisha',
11   - version => '0.12', # optional, will default to latest version
  15 + # establish the object
  16 + my $query = CPAN::Testers::WWW::Reports::Query::Reports->new;
  17 +
  18 + # get list of ids for a particular date
  19 + my $result = $query->date(
  20 + '2012-02-08' # must be YYYY-MM-DD format
12 21 );
13 22
14   - # basic results
15   - printf "ALL: %d\n" .
16   - "PASS: %d\n" .
17   - "FAIL: %d\n" .
18   - "NA: %d\n" .
19   - "UNKNOWN: %d\n" .
20   - "%age PASS: %d\n" .
21   - "%age FAIL: %d\n" .
22   - "%age NA: %d\n" .
23   - "%age UNKNOWN: %d\n",
24   -
25   - $query->all,
26   - $query->pass,
27   - $query->fail,
28   - $query->na,
29   - $query->unknown,
30   - $query->pc_pass,
31   - $query->pc_fail,
32   - $query->pc_na,
33   - $query->pc_unknown;
  23 + # $query is a hash ref
  24 + print "From: $result->{from}, To: $result->{to}, Range: $result->{range}\n";
  25 +
  26 + # $result->{list} is an array of the actual ids posted for the given date.
  27 + # note that this list may not include all ids within $result->{range}.
  28 + print "List: " . join(', ',@{$result->{list}}) . "\n";
34 29
35   - # get the raw data for all results, or a specific version if supplied
36   - my $data = $query->raw;
37 30
38   - # basic filters (see new() for details)
39   - my $query = CPAN::Testers::WWW::Reports::Query::AJAX->new(
40   - distribution => 'App-Maisha',
41   - version => '0.12',
42   - osname => 'Win32',
43   - patches => 1,
44   - perlmat => 1,
45   - perlver => '5.10.0',
46   - format => 'xml' # xml is default, text also supported
  31 + # get metabase for a range of ids
  32 + my $result = $query->range(
  33 + '20080300-20120330'
  34 +
  35 + # '20120330' # just get <id>
  36 + # '20120330-' # from <id> until the latest [see caveat]
  37 + # '-20120330' # previous <n> reports up to <id> [see caveat]
  38 + # '-' # the latest <n> reports [see caveat]
47 39 );
48 40
49   - printf "Win32 PASS: %d\n", $query->pass;
  41 + # $result is a hash ref, with the reports ids as the top level keys
  42 + my @ids = sort keys %$result;
  43 + my $id = $ids[0];
  44 + print "id = $id, dist = '$result->{$id}{dist}', version = '$result->{$id}{version}'\n";
50 45
51   -DESCRIPTION
52   - This module queries the CPAN Testers website (via the AJAX interface)
53   - and retrieves a simple data set of results. It then parses these to
54   - answer a few simple questions.
  46 +
  47 + # get the raw data for all results, or a specific version if supplied
  48 + my $data = $query->raw;
  49 +
  50 + Caveat
  51 + When using the range parameter, note that at most 2500 records will be
  52 + returned. This is to avoid accidental request for all the records!
  53 +
  54 + This value may change in the future.
55 55
56 56 INTERFACE
57 57 The Constructor
@@ -62,55 +62,18 @@ INTERFACE
62 62 'config' can be anything that Config::IniFiles accepts for the
63 63 -file option.
64 64
65   - Counter Methods
66   - · all
67   -
68   - For the given query, the total number of reports stored.
69   -
70   - · pass
  65 + Search Methods
  66 + · date
71 67
72   - For the given query, the total number of PASS reports stored.
  68 + For the given date, returns a hash describing the IDs accessible
  69 + for that date.
73 70
74   - · fail
  71 + · range
75 72
76   - For the given query, the total number of FAIL reports stored.
77   -
78   - · na
79   -
80   - For the given query, the total number of NA reports stored.
81   -
82   - · unknown
83   -
84   - For the given query, the total number of UNKNOWN reports stored.
85   -
86   - · pc_pass
87   -
88   - For the given query, the percentage number of PASS reports stored
89   - against all reports stored.
90   -
91   - · pc_fail
92   -
93   - For the given query, the percentage number of FAIL reports stored
94   - against all reports stored.
95   -
96   - · pc_na
97   -
98   - For the given query, the percentage number of NA reports stored
99   - against all reports stored.
100   -
101   - · pc_unknown
102   -
103   - For the given query, the percentage number of UNKNOWN reports
104   - stored against all reports stored.
  73 + For the given range, returns the metadata records stored for those
  74 + IDs.
105 75
106 76 Data Methods
107   - · data
108   -
109   - Returns the basic data structure as a hash reference. If a version
110   - is passed as a parameter, the data only for that version is
111   - returned. Otherwise all the results are returned, with the version
112   - as the top level key of the hash.
113   -
114 77 · raw
115 78
116 79 Returns the raw content returned from the server.
@@ -125,7 +88,7 @@ BUGS, PATCHES & FIXES
125 88 fix not be forthcoming, please feel free to (politely) remind me.
126 89
127 90 RT Queue -
128   - http://rt.cpan.org/Public/Dist/Display.html?Name=CPAN::Testers::WWW::Reports::Query::AJAX
  91 + http://rt.cpan.org/Public/Dist/Display.html?Name=CPAN::Testers::WWW::Reports::Query::Reports
129 92
130 93 SEE ALSO
131 94 CPAN::Testers::Data::Generator, CPAN::Testers::WWW::Reports
@@ -133,11 +96,6 @@ SEE ALSO
133 96 http://www.cpantesters.org/, http://stats.cpantesters.org/,
134 97 http://wiki.cpantesters.org/
135 98
136   - I would also like to thank Leo Lapworth from prompting me to write
137   - this, sorry its taken so long to release. However, you may be
138   - interested in his alternative query distribution
139   - CPAN::Testers::Reports::Query::JSON.
140   -
141 99 Initially released during the 2012 QA Hackathon in Paris.
142 100
143 101 AUTHOR
@@ -145,11 +103,11 @@ AUTHOR
145 103 for Miss Barbell Productions <http://www.missbarbell.co.uk>.
146 104
147 105 COPYRIGHT AND LICENSE
148   - Copyright (C) 2011-2012 Barbie for Miss Barbell Productions.
  106 + Copyright (C) 2012 Barbie for Miss Barbell Productions.
149 107
150 108 This module is free software; you can redistribute it and/or
151   - modify it under the same terms as Perl itself.
  109 + modify it under the Artistic License 2.0.
152 110
153 111
154 112
155   -perl v5.10.1 2CPAN::Testers::WWW::Reports::Query::AJAX(3)
  113 +perl v5.10.1 CPAN::Testers::WWW::Reports::Query::Reports(3)
436 lib/CPAN/Testers/WWW/Reports/Query/Reports.pm
... ... @@ -1,218 +1,218 @@
1   -package CPAN::Testers::WWW::Reports::Query::Reports;
2   -
3   -use strict;
4   -use warnings;
5   -
6   -our $VERSION = '0.01';
7   -
8   -#----------------------------------------------------------------------------
9   -
10   -=head1 NAME
11   -
12   -CPAN::Testers::WWW::Reports::Query::Reports - Retrieve CPAN Testers metadata direct from the CPAN Testers website.
13   -
14   -=head1 DESCRIPTION
15   -
16   -This module queries the CPAN Testers website and retrieves a data set. For a
17   -date request, the data set returned relates to the ids that can be retrieved
18   -for that date. A range request will return the records for the requested IDs.
19   -
20   -=head1 SYNOPSIS
21   -
22   - # establish the object
23   - my $query = CPAN::Testers::WWW::Reports::Query::Reports->new;
24   -
25   - # get list of ids for a particular date
26   - my $result = $query->date(
27   - '2012-02-08' # must be YYYY-MM-DD format
28   - );
29   -
30   - # $query is a hash ref
31   - print "From: $result->{from}, To: $result->{to}, Range: $result->{range}\n";
32   -
33   - # $result->{list} is an array of the actual ids posted for the given date.
34   - # note that this list may not include all ids within $result->{range}.
35   - print "List: " . join(', ',@{$result->{list}}) . "\n";
36   -
37   -
38   - # get metabase for a range of ids
39   - my $result = $query->range(
40   - '20080300-20120330'
41   -
42   - # '20120330' # just get <id>
43   - # '20120330-' # from <id> until the latest [see caveat]
44   - # '-20120330' # previous <n> reports up to <id> [see caveat]
45   - # '-' # the latest <n> reports [see caveat]
46   - );
47   -
48   - # $result is a hash ref, with the reports ids as the top level keys
49   - my @ids = sort keys %$result;
50   - my $id = $ids[0];
51   - print "id = $id, dist = '$result->{$id}{dist}', version = '$result->{$id}{version}'\n";
52   -
53   -
54   - # get the raw data for all results, or a specific version if supplied
55   - my $data = $query->raw;
56   -
57   -
58   -=head2 Caveat
59   -
60   -When using the range parameter, note that at most 2500 records will be
61   -returned. This is to avoid accidental request for all the records!
62   -
63   -This value may change in the future.
64   -
65   -=cut
66   -
67   -#----------------------------------------------------------------------------
68   -# Library Modules
69   -
70   -use WWW::Mechanize;
71   -use JSON::XS;
72   -
73   -#----------------------------------------------------------------------------
74   -# Variables
75   -
76   -my $URL = 'http://www.cpantesters.org/cgi-bin/reports-metadata.cgi';
77   -#$URL = 'http://reports/cgi-bin/reports-metadata.cgi'; # local test version
78   -
79   -my $mech = WWW::Mechanize->new();
80   -$mech->agent_alias( 'Linux Mozilla' );
81   -
82   -# -------------------------------------
83   -# Program
84   -
85   -sub new {
86   - my($class, %hash) = @_;
87   - my $self = {};
88   - bless $self, $class;
89   -
90   - return $self;
91   -}
92   -
93   -sub raw {
94   - my $self = shift;
95   - return $self->{content};
96   -}
97   -
98   -sub date {
99   - my $self = shift;
100   - my $date = shift || return;
101   -
102   - return unless($date =~ /^\d{4}\-\d{2}\-\d{2}$/);
103   -
104   - return unless($self->_request( "date=$date" ));
105   -
106   - return $self->_parse();
107   -}
108   -
109   -sub range {
110   - my $self = shift;
111   - my $range = shift || return;
112   -
113   - return unless($range =~ /^(\d+)?\-(\d+)?$/ || $range =~ /^(\d+)$/);
114   -
115   - return unless($self->_request( "range=$range" ));
116   -
117   - return $self->_parse();
118   -}
119   -
120   -sub _request {
121   - my $self = shift;
122   - my $param = shift || return;
123   -
124   - my $url = join( '?', $URL, $param );
125   - #print "URL: $url\n";
126   - eval { $mech->get( $url ); };
127   - if($@ || !$mech->success()) {
128   - die $@;
129   - return;
130   - }
131   -
132   - $self->{content} = $mech->content;
133   -}
134   -
135   -sub _parse {
136   - my $self = shift;
137   -
138   - return decode_json($self->{content});
139   -}
140   -
141   -q("With thanks to the 2012 QA Hackathon");
142   -
143   -__END__
144   -
145   -=head1 INTERFACE
146   -
147   -=head2 The Constructor
148   -
149   -=over
150   -
151   -=item * new
152   -
153   -Instatiates the object CPAN::WWW::Testers. Requires a hash of parameters, with
154   -'config' being the only mandatory key. Note that 'config' can be anything that
155   -L<Config::IniFiles> accepts for the I<-file> option.
156   -
157   -=back
158   -
159   -=head2 Search Methods
160   -
161   -=over 4
162   -
163   -=item * date
164   -
165   -For the given date, returns a hash describing the IDs accessible for that date.
166   -
167   -=item * range
168   -
169   -For the given range, returns the metadata records stored for those IDs.
170   -
171   -=back
172   -
173   -=head2 Data Methods
174   -
175   -=over 4
176   -
177   -=item * raw
178   -
179   -Returns the raw content returned from the server.
180   -
181   -=back
182   -
183   -=head1 BUGS, PATCHES & FIXES
184   -
185   -There are no known bugs at the time of this release. However, if you spot a
186   -bug or are experiencing difficulties, that is not explained within the POD
187   -documentation, please send bug reports and patches to the RT Queue (see below).
188   -
189   -Fixes are dependant upon their severity and my availablity. Should a fix not
190   -be forthcoming, please feel free to (politely) remind me.
191   -
192   -RT Queue -
193   -http://rt.cpan.org/Public/Dist/Display.html?Name=CPAN::Testers::WWW::Reports::Query::Reports
194   -
195   -=head1 SEE ALSO
196   -
197   -L<CPAN::Testers::Data::Generator>,
198   -L<CPAN::Testers::WWW::Reports>
199   -
200   -F<http://www.cpantesters.org/>,
201   -F<http://stats.cpantesters.org/>,
202   -F<http://wiki.cpantesters.org/>
203   -
204   -Initially released during the 2012 QA Hackathon in Paris.
205   -
206   -=head1 AUTHOR
207   -
208   - Barbie, <barbie@cpan.org>
209   - for Miss Barbell Productions <http://www.missbarbell.co.uk>.
210   -
211   -=head1 COPYRIGHT AND LICENSE
212   -
213   - Copyright (C) 2012 Barbie for Miss Barbell Productions.
214   -
215   - This module is free software; you can redistribute it and/or
216   - modify it under the Artistic License 2.0.
217   -
218   -=cut
  1 +package CPAN::Testers::WWW::Reports::Query::Reports;
  2 +
  3 +use strict;
  4 +use warnings;
  5 +
  6 +our $VERSION = '0.02';
  7 +
  8 +#----------------------------------------------------------------------------
  9 +
  10 +=head1 NAME
  11 +
  12 +CPAN::Testers::WWW::Reports::Query::Reports - Retrieve CPAN Testers metadata direct from the CPAN Testers website.
  13 +
  14 +=head1 DESCRIPTION
  15 +
  16 +This module queries the CPAN Testers website and retrieves a data set. For a
  17 +date request, the data set returned relates to the ids that can be retrieved
  18 +for that date. A range request will return the records for the requested IDs.
  19 +
  20 +=head1 SYNOPSIS
  21 +
  22 + # establish the object
  23 + my $query = CPAN::Testers::WWW::Reports::Query::Reports->new;
  24 +
  25 + # get list of ids for a particular date
  26 + my $result = $query->date(
  27 + '2012-02-08' # must be YYYY-MM-DD format
  28 + );
  29 +
  30 + # $query is a hash ref
  31 + print "From: $result->{from}, To: $result->{to}, Range: $result->{range}\n";
  32 +
  33 + # $result->{list} is an array of the actual ids posted for the given date.
  34 + # note that this list may not include all ids within $result->{range}.
  35 + print "List: " . join(', ',@{$result->{list}}) . "\n";
  36 +
  37 +
  38 + # get metabase for a range of ids
  39 + my $result = $query->range(
  40 + '20080300-20120330'
  41 +
  42 + # '20120330' # just get <id>
  43 + # '20120330-' # from <id> until the latest [see caveat]
  44 + # '-20120330' # previous <n> reports up to <id> [see caveat]
  45 + # '-' # the latest <n> reports [see caveat]
  46 + );
  47 +
  48 + # $result is a hash ref, with the reports ids as the top level keys
  49 + my @ids = sort keys %$result;
  50 + my $id = $ids[0];
  51 + print "id = $id, dist = '$result->{$id}{dist}', version = '$result->{$id}{version}'\n";
  52 +
  53 +
  54 + # get the raw data for all results, or a specific version if supplied
  55 + my $data = $query->raw;
  56 +
  57 +
  58 +=head2 Caveat
  59 +
  60 +When using the range parameter, note that at most 2500 records will be
  61 +returned. This is to avoid accidental request for all the records!
  62 +
  63 +This value may change in the future.
  64 +
  65 +=cut
  66 +
  67 +#----------------------------------------------------------------------------
  68 +# Library Modules
  69 +
  70 +use WWW::Mechanize;
  71 +use JSON::XS;
  72 +
  73 +#----------------------------------------------------------------------------
  74 +# Variables
  75 +
  76 +my $URL = 'http://www.cpantesters.org/cgi-bin/reports-metadata.cgi';
  77 +#$URL = 'http://reports/cgi-bin/reports-metadata.cgi'; # local test version
  78 +
  79 +my $mech = WWW::Mechanize->new();
  80 +$mech->agent_alias( 'Linux Mozilla' );
  81 +
  82 +# -------------------------------------
  83 +# Program
  84 +
  85 +sub new {
  86 + my($class, %hash) = @_;
  87 + my $self = {};
  88 + bless $self, $class;
  89 +
  90 + return $self;
  91 +}
  92 +
  93 +sub raw {
  94 + my $self = shift;
  95 + return $self->{content};
  96 +}
  97 +
  98 +sub date {
  99 + my $self = shift;
  100 + my $date = shift || return;
  101 +
  102 + return unless($date =~ /^\d{4}\-\d{2}\-\d{2}$/);
  103 +
  104 + return unless($self->_request( "date=$date" ));
  105 +
  106 + return $self->_parse();
  107 +}
  108 +
  109 +sub range {
  110 + my $self = shift;
  111 + my $range = shift || return;
  112 +
  113 + return unless($range =~ /^(\d+)?\-(\d+)?$/ || $range =~ /^(\d+)$/);
  114 +
  115 + return unless($self->_request( "range=$range" ));
  116 +
  117 + return $self->_parse();
  118 +}
  119 +
  120 +sub _request {
  121 + my $self = shift;
  122 + my $param = shift || return;
  123 +
  124 + my $url = join( '?', $URL, $param );
  125 + #print "URL: $url\n";
  126 + eval { $mech->get( $url ); };
  127 + if($@ || !$mech->success()) {
  128 + die $@;
  129 + return;
  130 + }
  131 +
  132 + $self->{content} = $mech->content;
  133 +}
  134 +
  135 +sub _parse {
  136 + my $self = shift;
  137 +
  138 + return decode_json($self->{content});
  139 +}
  140 +
  141 +q("With thanks to the 2012 QA Hackathon");
  142 +
  143 +__END__
  144 +
  145 +=head1 INTERFACE
  146 +
  147 +=head2 The Constructor
  148 +
  149 +=over
  150 +
  151 +=item * new
  152 +
  153 +Instatiates the object CPAN::WWW::Testers. Requires a hash of parameters, with
  154 +'config' being the only mandatory key. Note that 'config' can be anything that
  155 +L<Config::IniFiles> accepts for the I<-file> option.
  156 +
  157 +=back
  158 +
  159 +=head2 Search Methods
  160 +
  161 +=over 4
  162 +
  163 +=item * date
  164 +
  165 +For the given date, returns a hash describing the IDs accessible for that date.
  166 +
  167 +=item * range
  168 +
  169 +For the given range, returns the metadata records stored for those IDs.
  170 +
  171 +=back
  172 +
  173 +=head2 Data Methods
  174 +
  175 +=over 4
  176 +
  177 +=item * raw
  178 +
  179 +Returns the raw content returned from the server.
  180 +
  181 +=back
  182 +
  183 +=head1 BUGS, PATCHES & FIXES
  184 +
  185 +There are no known bugs at the time of this release. However, if you spot a
  186 +bug or are experiencing difficulties, that is not explained within the POD
  187 +documentation, please send bug reports and patches to the RT Queue (see below).
  188 +
  189 +Fixes are dependant upon their severity and my availablity. Should a fix not
  190 +be forthcoming, please feel free to (politely) remind me.
  191 +
  192 +RT Queue -
  193 +http://rt.cpan.org/Public/Dist/Display.html?Name=CPAN::Testers::WWW::Reports::Query::Reports
  194 +
  195 +=head1 SEE ALSO
  196 +
  197 +L<CPAN::Testers::Data::Generator>,
  198 +L<CPAN::Testers::WWW::Reports>
  199 +
  200 +F<http://www.cpantesters.org/>,
  201 +F<http://stats.cpantesters.org/>,
  202 +F<http://wiki.cpantesters.org/>
  203 +
  204 +Initially released during the 2012 QA Hackathon in Paris.
  205 +
  206 +=head1 AUTHOR
  207 +
  208 + Barbie, <barbie@cpan.org>
  209 + for Miss Barbell Productions <http://www.missbarbell.co.uk>.
  210 +
  211 +=head1 COPYRIGHT AND LICENSE
  212 +
  213 + Copyright (C) 2012 Barbie for Miss Barbell Productions.
  214 +
  215 + This module is free software; you can redistribute it and/or
  216 + modify it under the Artistic License 2.0.
  217 +
  218 +=cut

0 comments on commit 9318a7c

Please sign in to comment.
Something went wrong with that request. Please try again.