#!/usr/bin/perl -- -*- mode: cperl -*-

=head1 NAME

ctgetreports - Quickly fetch cpantesters results with all reports

=head1 SYNOPSIS

  ctgetoptions [options] distroname ...

=head1 OPTIONS

=over 8

=cut

my $optpod = <<'=back';

=item B<--cachedir=s>

Directory to keep mirrored data in. Defaults to C<$HOME/var/cpantesters>.

=item B<--dumpvars=s>

Dump all queryable variables matching the regular expression given as
argument at the end of the loop for a distro.

=item B<--help|h>

Prints a brief message and exists.

=item B<--interactive|i>

After every parsed report asks if you want to see it in a pager.

=item B<--local>

Do not mirror more than neccessary. Use a local *.html file if present
even if older than 24 hours.

=item B<--pager=s>

Pager (needed when -i is given). Defaults to C<less>.

=item B<--q=s@>

Query, may be repeated.

Example: C<--q mod:Clone --q meta:writer>

=item B<--vdistro=s>

Versioned distro. Needed if we do not want the most recent. Makes no
sense if there is more than one argument on the command line.

Example: C<--vdistro IPC-Run-0.80>

=item B<--verbose|v+>

Feedback during download.

=back

=head1 DESCRIPTION

!!!!Alert: alpha quality software, subject to change without warning!!!!

The intent is to get at both the summary at cpantesters and the
individual reports and parse the reports and collect the data for
further inspection.

We always only fetch the reports for the most recent (optionally
picked) release. Target root directory is C<$HOME/var/cpantesters>

The C<--q> paramater can be repeated. It takes one argument which
stands for a query. This query must consist of two parts, a qualifier
and the query itself. Qualifiers are one of the following

  conf       parameters from the output of 'perl -V'
             e.g.: conf:usethreads, conf:cc
  mod        for installed modules, either from perrequisites or from the toolchain
             e.g.: mod:Test::Simple, mod:Imager
  meta       all other parameters
             e.g.: meta:perl, meta:from

The conf parameters specify a word used by the C<Config> module.

The mod parameters consist of a package name.

The meta parameters are the following: C<perl> for the perl version,
C<from> for the sender of the report, C<date> for the date in the mail
header, C<writer> for the module that produced the report.


=head2 Examples

This gets all recent reports for Object-Relation and outputs the
version number of the prerequisite Clone:

  $0 --q mod:Clone Object-Relation

Collects reports about Clone and reports the default set of metadata:

  $0 Clone

Collect reports for Devel-Events and report the version number of
Moose in thses reports and sort by success/failure. If Moose broke
Devel-Events is becomes pretty obvious:

  $0 --q mod:Moose Devel-Events |sort

Which tool was used to write how many reports, sorted by frequency:

  $0 --q meta:writer Template-Timer | sed -e 's/.*meta:writer//' | sort | uniq -c | sort -n

Who was in the From field of the mails whose report writer was not determined:

  $0 --q meta:writer --q meta:from Template-Timer | grep 'UNDEF'

At the time of this writing this collected the results of
IPC-Run-0.80_91 which was not really the latest release. In this case
manual investigations were necessary to find out that 0.80 was the
most recent:

  $0 IPC-Run

Pick the specific release IPC-Run-0.80:

  $0 --vdistro IPC-Run-0.80 IPC-Run

The following is a simple job to refresh all HTML pages we already
have and fetch new reports referenced there too:

  perl -le '
  for my $dirent (glob "$ENV{HOME}/var/cpantesters/cpantesters-show/*.html"){
    my($distro) = $dirent =~ m|/([^/]+)\.html$| or next;
    print $distro;
    my $system = "ctgetreports --verbose --verbose $distro";
    0 == system $system or die;
  }'

=cut

use strict;
use warnings;

use CPAN::Testers::ParseReport;
use Getopt::Long;
use Pod::Usage qw(pod2usage);

sub Usage () {
    die "Usage: FIXME";
};
our %Opt;
my @opt = $optpod =~ /B<--(\S+)>/g;
for (@opt) {
    $_ .= "!" unless /[+!=]/;
}

GetOptions(\%Opt,
           @opt,
          ) or pod2usage(2);

if ($Opt{help}) {
    pod2usage(0);
}

if (! @ARGV) {
    pod2usage(2);
}

if ($Opt{dumpvars}) {
    eval { require YAML::Syck };
    if ($@) {
        die "YAML::Syck required for dumpvars option: $@";
    }
}

$|=1;
DISTRO: for my $distro (@ARGV) {
    CPAN::Testers::ParseReport::parse_distro($distro,%Opt);
    last DISTRO if $CPAN::Testers::ParseReport::Signal;
}
__END__
