Browse files

added correct README

  • Loading branch information...
1 parent d5f4440 commit 9318a7c88ab5dce768a968a4964da34c603acf3b @barbie barbie committed Mar 31, 2012
Showing with 276 additions and 315 deletions.
  1. +3 −0 Changes
  2. +2 −2 META.yml
  3. +53 −95 README
  4. +218 −218 lib/CPAN/Testers/WWW/Reports/Query/Reports.pm
View
3 Changes
@@ -1,5 +1,8 @@
Revision history for CPAN-Testers-WWW-Reports-Query-Reports
+0.02 31/03/2012
+ - now with the correct README!
+
0.01 30/03/2012
- First release
View
4 META.yml
@@ -1,6 +1,6 @@
--- #YAML:1.0
name: CPAN::Testers::WWW::Reports::Query::Reports
-version: 0.01
+version: 0.02
abstract: Retrieve CPAN Testers metadata direct from the CPAN Testers website.
author:
- Barbie <barbie@cpan.org>
@@ -22,7 +22,7 @@ build_requires:
provides:
CPAN::Testers::WWW::Reports::Query::Reports:
file: lib/CPAN/Testers/WWW/Reports/Query/Reports.pm
- version: 0.01
+ version: 0.02
resources:
repository: http://github.com/barbie/cpan-testers-www-reports-query-reports
View
148 README
@@ -1,57 +1,57 @@
-User Contributed Documentation CPAN::Testers::WWW::Reports::Query::AJAX(3)
+User Contributed Documentation CPAN::Testers::WWW::Reports::Query::Reports(3)
NAME
- CPAN::Testers::WWW::Reports::Query::AJAX - Get specific CPAN Testers
- results
+ CPAN::Testers::WWW::Reports::Query::Reports - Retrieve CPAN Testers
+ metadata direct from the CPAN Testers website.
+
+DESCRIPTION
+ This module queries the CPAN Testers website and retrieves a data set.
+ For a date request, the data set returned relates to the ids that can
+ be retrieved for that date. A range request will return the records for
+ the requested IDs.
SYNOPSIS
- my $query = CPAN::Testers::WWW::Reports::Query::AJAX->new(
- distribution => 'App-Maisha',
- version => '0.12', # optional, will default to latest version
+ # establish the object
+ my $query = CPAN::Testers::WWW::Reports::Query::Reports->new;
+
+ # get list of ids for a particular date
+ my $result = $query->date(
+ '2012-02-08' # must be YYYY-MM-DD format
);
- # basic results
- printf "ALL: %d\n" .
- "PASS: %d\n" .
- "FAIL: %d\n" .
- "NA: %d\n" .
- "UNKNOWN: %d\n" .
- "%age PASS: %d\n" .
- "%age FAIL: %d\n" .
- "%age NA: %d\n" .
- "%age UNKNOWN: %d\n",
-
- $query->all,
- $query->pass,
- $query->fail,
- $query->na,
- $query->unknown,
- $query->pc_pass,
- $query->pc_fail,
- $query->pc_na,
- $query->pc_unknown;
+ # $query is a hash ref
+ print "From: $result->{from}, To: $result->{to}, Range: $result->{range}\n";
+
+ # $result->{list} is an array of the actual ids posted for the given date.
+ # note that this list may not include all ids within $result->{range}.
+ print "List: " . join(', ',@{$result->{list}}) . "\n";
- # get the raw data for all results, or a specific version if supplied
- my $data = $query->raw;
- # basic filters (see new() for details)
- my $query = CPAN::Testers::WWW::Reports::Query::AJAX->new(
- distribution => 'App-Maisha',
- version => '0.12',
- osname => 'Win32',
- patches => 1,
- perlmat => 1,
- perlver => '5.10.0',
- format => 'xml' # xml is default, text also supported
+ # get metabase for a range of ids
+ my $result = $query->range(
+ '20080300-20120330'
+
+ # '20120330' # just get <id>
+ # '20120330-' # from <id> until the latest [see caveat]
+ # '-20120330' # previous <n> reports up to <id> [see caveat]
+ # '-' # the latest <n> reports [see caveat]
);
- printf "Win32 PASS: %d\n", $query->pass;
+ # $result is a hash ref, with the reports ids as the top level keys
+ my @ids = sort keys %$result;
+ my $id = $ids[0];
+ print "id = $id, dist = '$result->{$id}{dist}', version = '$result->{$id}{version}'\n";
-DESCRIPTION
- This module queries the CPAN Testers website (via the AJAX interface)
- and retrieves a simple data set of results. It then parses these to
- answer a few simple questions.
+
+ # get the raw data for all results, or a specific version if supplied
+ my $data = $query->raw;
+
+ Caveat
+ When using the range parameter, note that at most 2500 records will be
+ returned. This is to avoid accidental request for all the records!
+
+ This value may change in the future.
INTERFACE
The Constructor
@@ -62,55 +62,18 @@ INTERFACE
'config' can be anything that Config::IniFiles accepts for the
-file option.
- Counter Methods
- · all
-
- For the given query, the total number of reports stored.
-
- · pass
+ Search Methods
+ · date
- For the given query, the total number of PASS reports stored.
+ For the given date, returns a hash describing the IDs accessible
+ for that date.
- · fail
+ · range
- For the given query, the total number of FAIL reports stored.
-
- · na
-
- For the given query, the total number of NA reports stored.
-
- · unknown
-
- For the given query, the total number of UNKNOWN reports stored.
-
- · pc_pass
-
- For the given query, the percentage number of PASS reports stored
- against all reports stored.
-
- · pc_fail
-
- For the given query, the percentage number of FAIL reports stored
- against all reports stored.
-
- · pc_na
-
- For the given query, the percentage number of NA reports stored
- against all reports stored.
-
- · pc_unknown
-
- For the given query, the percentage number of UNKNOWN reports
- stored against all reports stored.
+ For the given range, returns the metadata records stored for those
+ IDs.
Data Methods
- · data
-
- Returns the basic data structure as a hash reference. If a version
- is passed as a parameter, the data only for that version is
- returned. Otherwise all the results are returned, with the version
- as the top level key of the hash.
-
· raw
Returns the raw content returned from the server.
@@ -125,31 +88,26 @@ BUGS, PATCHES & FIXES
fix not be forthcoming, please feel free to (politely) remind me.
RT Queue -
- http://rt.cpan.org/Public/Dist/Display.html?Name=CPAN::Testers::WWW::Reports::Query::AJAX
+ http://rt.cpan.org/Public/Dist/Display.html?Name=CPAN::Testers::WWW::Reports::Query::Reports
SEE ALSO
CPAN::Testers::Data::Generator, CPAN::Testers::WWW::Reports
http://www.cpantesters.org/, http://stats.cpantesters.org/,
http://wiki.cpantesters.org/
- I would also like to thank Leo Lapworth from prompting me to write
- this, sorry its taken so long to release. However, you may be
- interested in his alternative query distribution
- CPAN::Testers::Reports::Query::JSON.
-
Initially released during the 2012 QA Hackathon in Paris.
AUTHOR
Barbie, <barbie@cpan.org>
for Miss Barbell Productions <http://www.missbarbell.co.uk>.
COPYRIGHT AND LICENSE
- Copyright (C) 2011-2012 Barbie for Miss Barbell Productions.
+ Copyright (C) 2012 Barbie for Miss Barbell Productions.
This module is free software; you can redistribute it and/or
- modify it under the same terms as Perl itself.
+ modify it under the Artistic License 2.0.
-perl v5.10.1 2CPAN::Testers::WWW::Reports::Query::AJAX(3)
+perl v5.10.1 CPAN::Testers::WWW::Reports::Query::Reports(3)
View
436 lib/CPAN/Testers/WWW/Reports/Query/Reports.pm
@@ -1,218 +1,218 @@
-package CPAN::Testers::WWW::Reports::Query::Reports;
-
-use strict;
-use warnings;
-
-our $VERSION = '0.01';
-
-#----------------------------------------------------------------------------
-
-=head1 NAME
-
-CPAN::Testers::WWW::Reports::Query::Reports - Retrieve CPAN Testers metadata direct from the CPAN Testers website.
-
-=head1 DESCRIPTION
-
-This module queries the CPAN Testers website and retrieves a data set. For a
-date request, the data set returned relates to the ids that can be retrieved
-for that date. A range request will return the records for the requested IDs.
-
-=head1 SYNOPSIS
-
- # establish the object
- my $query = CPAN::Testers::WWW::Reports::Query::Reports->new;
-
- # get list of ids for a particular date
- my $result = $query->date(
- '2012-02-08' # must be YYYY-MM-DD format
- );
-
- # $query is a hash ref
- print "From: $result->{from}, To: $result->{to}, Range: $result->{range}\n";
-
- # $result->{list} is an array of the actual ids posted for the given date.
- # note that this list may not include all ids within $result->{range}.
- print "List: " . join(', ',@{$result->{list}}) . "\n";
-
-
- # get metabase for a range of ids
- my $result = $query->range(
- '20080300-20120330'
-
- # '20120330' # just get <id>
- # '20120330-' # from <id> until the latest [see caveat]
- # '-20120330' # previous <n> reports up to <id> [see caveat]
- # '-' # the latest <n> reports [see caveat]
- );
-
- # $result is a hash ref, with the reports ids as the top level keys
- my @ids = sort keys %$result;
- my $id = $ids[0];
- print "id = $id, dist = '$result->{$id}{dist}', version = '$result->{$id}{version}'\n";
-
-
- # get the raw data for all results, or a specific version if supplied
- my $data = $query->raw;
-
-
-=head2 Caveat
-
-When using the range parameter, note that at most 2500 records will be
-returned. This is to avoid accidental request for all the records!
-
-This value may change in the future.
-
-=cut
-
-#----------------------------------------------------------------------------
-# Library Modules
-
-use WWW::Mechanize;
-use JSON::XS;
-
-#----------------------------------------------------------------------------
-# Variables
-
-my $URL = 'http://www.cpantesters.org/cgi-bin/reports-metadata.cgi';
-#$URL = 'http://reports/cgi-bin/reports-metadata.cgi'; # local test version
-
-my $mech = WWW::Mechanize->new();
-$mech->agent_alias( 'Linux Mozilla' );
-
-# -------------------------------------
-# Program
-
-sub new {
- my($class, %hash) = @_;
- my $self = {};
- bless $self, $class;
-
- return $self;
-}
-
-sub raw {
- my $self = shift;
- return $self->{content};
-}
-
-sub date {
- my $self = shift;
- my $date = shift || return;
-
- return unless($date =~ /^\d{4}\-\d{2}\-\d{2}$/);
-
- return unless($self->_request( "date=$date" ));
-
- return $self->_parse();
-}
-
-sub range {
- my $self = shift;
- my $range = shift || return;
-
- return unless($range =~ /^(\d+)?\-(\d+)?$/ || $range =~ /^(\d+)$/);
-
- return unless($self->_request( "range=$range" ));
-
- return $self->_parse();
-}
-
-sub _request {
- my $self = shift;
- my $param = shift || return;
-
- my $url = join( '?', $URL, $param );
- #print "URL: $url\n";
- eval { $mech->get( $url ); };
- if($@ || !$mech->success()) {
- die $@;
- return;
- }
-
- $self->{content} = $mech->content;
-}
-
-sub _parse {
- my $self = shift;
-
- return decode_json($self->{content});
-}
-
-q("With thanks to the 2012 QA Hackathon");
-
-__END__
-
-=head1 INTERFACE
-
-=head2 The Constructor
-
-=over
-
-=item * new
-
-Instatiates the object CPAN::WWW::Testers. Requires a hash of parameters, with
-'config' being the only mandatory key. Note that 'config' can be anything that
-L<Config::IniFiles> accepts for the I<-file> option.
-
-=back
-
-=head2 Search Methods
-
-=over 4
-
-=item * date
-
-For the given date, returns a hash describing the IDs accessible for that date.
-
-=item * range
-
-For the given range, returns the metadata records stored for those IDs.
-
-=back
-
-=head2 Data Methods
-
-=over 4
-
-=item * raw
-
-Returns the raw content returned from the server.
-
-=back
-
-=head1 BUGS, PATCHES & FIXES
-
-There are no known bugs at the time of this release. However, if you spot a
-bug or are experiencing difficulties, that is not explained within the POD
-documentation, please send bug reports and patches to the RT Queue (see below).
-
-Fixes are dependant upon their severity and my availablity. Should a fix not
-be forthcoming, please feel free to (politely) remind me.
-
-RT Queue -
-http://rt.cpan.org/Public/Dist/Display.html?Name=CPAN::Testers::WWW::Reports::Query::Reports
-
-=head1 SEE ALSO
-
-L<CPAN::Testers::Data::Generator>,
-L<CPAN::Testers::WWW::Reports>
-
-F<http://www.cpantesters.org/>,
-F<http://stats.cpantesters.org/>,
-F<http://wiki.cpantesters.org/>
-
-Initially released during the 2012 QA Hackathon in Paris.
-
-=head1 AUTHOR
-
- Barbie, <barbie@cpan.org>
- for Miss Barbell Productions <http://www.missbarbell.co.uk>.
-
-=head1 COPYRIGHT AND LICENSE
-
- Copyright (C) 2012 Barbie for Miss Barbell Productions.
-
- This module is free software; you can redistribute it and/or
- modify it under the Artistic License 2.0.
-
-=cut
+package CPAN::Testers::WWW::Reports::Query::Reports;
+
+use strict;
+use warnings;
+
+our $VERSION = '0.02';
+
+#----------------------------------------------------------------------------
+
+=head1 NAME
+
+CPAN::Testers::WWW::Reports::Query::Reports - Retrieve CPAN Testers metadata direct from the CPAN Testers website.
+
+=head1 DESCRIPTION
+
+This module queries the CPAN Testers website and retrieves a data set. For a
+date request, the data set returned relates to the ids that can be retrieved
+for that date. A range request will return the records for the requested IDs.
+
+=head1 SYNOPSIS
+
+ # establish the object
+ my $query = CPAN::Testers::WWW::Reports::Query::Reports->new;
+
+ # get list of ids for a particular date
+ my $result = $query->date(
+ '2012-02-08' # must be YYYY-MM-DD format
+ );
+
+ # $query is a hash ref
+ print "From: $result->{from}, To: $result->{to}, Range: $result->{range}\n";
+
+ # $result->{list} is an array of the actual ids posted for the given date.
+ # note that this list may not include all ids within $result->{range}.
+ print "List: " . join(', ',@{$result->{list}}) . "\n";
+
+
+ # get metabase for a range of ids
+ my $result = $query->range(
+ '20080300-20120330'
+
+ # '20120330' # just get <id>
+ # '20120330-' # from <id> until the latest [see caveat]
+ # '-20120330' # previous <n> reports up to <id> [see caveat]
+ # '-' # the latest <n> reports [see caveat]
+ );
+
+ # $result is a hash ref, with the reports ids as the top level keys
+ my @ids = sort keys %$result;
+ my $id = $ids[0];
+ print "id = $id, dist = '$result->{$id}{dist}', version = '$result->{$id}{version}'\n";
+
+
+ # get the raw data for all results, or a specific version if supplied
+ my $data = $query->raw;
+
+
+=head2 Caveat
+
+When using the range parameter, note that at most 2500 records will be
+returned. This is to avoid accidental request for all the records!
+
+This value may change in the future.
+
+=cut
+
+#----------------------------------------------------------------------------
+# Library Modules
+
+use WWW::Mechanize;
+use JSON::XS;
+
+#----------------------------------------------------------------------------
+# Variables
+
+my $URL = 'http://www.cpantesters.org/cgi-bin/reports-metadata.cgi';
+#$URL = 'http://reports/cgi-bin/reports-metadata.cgi'; # local test version
+
+my $mech = WWW::Mechanize->new();
+$mech->agent_alias( 'Linux Mozilla' );
+
+# -------------------------------------
+# Program
+
+sub new {
+ my($class, %hash) = @_;
+ my $self = {};
+ bless $self, $class;
+
+ return $self;
+}
+
+sub raw {
+ my $self = shift;
+ return $self->{content};
+}
+
+sub date {
+ my $self = shift;
+ my $date = shift || return;
+
+ return unless($date =~ /^\d{4}\-\d{2}\-\d{2}$/);
+
+ return unless($self->_request( "date=$date" ));
+
+ return $self->_parse();
+}
+
+sub range {
+ my $self = shift;
+ my $range = shift || return;
+
+ return unless($range =~ /^(\d+)?\-(\d+)?$/ || $range =~ /^(\d+)$/);
+
+ return unless($self->_request( "range=$range" ));
+
+ return $self->_parse();
+}
+
+sub _request {
+ my $self = shift;
+ my $param = shift || return;
+
+ my $url = join( '?', $URL, $param );
+ #print "URL: $url\n";
+ eval { $mech->get( $url ); };
+ if($@ || !$mech->success()) {
+ die $@;
+ return;
+ }
+
+ $self->{content} = $mech->content;
+}
+
+sub _parse {
+ my $self = shift;
+
+ return decode_json($self->{content});
+}
+
+q("With thanks to the 2012 QA Hackathon");
+
+__END__
+
+=head1 INTERFACE
+
+=head2 The Constructor
+
+=over
+
+=item * new
+
+Instatiates the object CPAN::WWW::Testers. Requires a hash of parameters, with
+'config' being the only mandatory key. Note that 'config' can be anything that
+L<Config::IniFiles> accepts for the I<-file> option.
+
+=back
+
+=head2 Search Methods
+
+=over 4
+
+=item * date
+
+For the given date, returns a hash describing the IDs accessible for that date.
+
+=item * range
+
+For the given range, returns the metadata records stored for those IDs.
+
+=back
+
+=head2 Data Methods
+
+=over 4
+
+=item * raw
+
+Returns the raw content returned from the server.
+
+=back
+
+=head1 BUGS, PATCHES & FIXES
+
+There are no known bugs at the time of this release. However, if you spot a
+bug or are experiencing difficulties, that is not explained within the POD
+documentation, please send bug reports and patches to the RT Queue (see below).
+
+Fixes are dependant upon their severity and my availablity. Should a fix not
+be forthcoming, please feel free to (politely) remind me.
+
+RT Queue -
+http://rt.cpan.org/Public/Dist/Display.html?Name=CPAN::Testers::WWW::Reports::Query::Reports
+
+=head1 SEE ALSO
+
+L<CPAN::Testers::Data::Generator>,
+L<CPAN::Testers::WWW::Reports>
+
+F<http://www.cpantesters.org/>,
+F<http://stats.cpantesters.org/>,
+F<http://wiki.cpantesters.org/>
+
+Initially released during the 2012 QA Hackathon in Paris.
+
+=head1 AUTHOR
+
+ Barbie, <barbie@cpan.org>
+ for Miss Barbell Productions <http://www.missbarbell.co.uk>.
+
+=head1 COPYRIGHT AND LICENSE
+
+ Copyright (C) 2012 Barbie for Miss Barbell Productions.
+
+ This module is free software; you can redistribute it and/or
+ modify it under the Artistic License 2.0.
+
+=cut

0 comments on commit 9318a7c

Please sign in to comment.