lib/perl5/vendor_perl/5.10/CPAN/Reporter/History.pod

# Generated by Pod::WikiDoc version 0.18

=pod

=head1 NAME

CPAN::Reporter::History - Read or write a CPAN::Reporter history log

=head1 VERSION

This documentation refers to version 1.13

=head1 SYNOPSIS

     use CPAN::Reporter::History 'have_tested';
 
     @results = have_tested( dist => 'Dist-Name-1.23' );

=head1 DESCRIPTION

Interface for interacting with the CPAN::Reporter history file.  Most methods
are private for use only within CPAN::Reporter itself.  However, a public
function is provided to query the history file for results. 

=head1 USAGE

The following function is available.  It is not exported by default.

=head2 C<<< have_tested() >>>

     # all reports for Foo-Bar-1.23
     @results = have_tested( dist => 'Foo-Bar-1.23' );
 
     # all NA reports
     @results = have_tested( grade => 'NA' );
 
     # all reports on the current Perl/platform
     @results = have_tested();

Searches the CPAN::Reporter history file for records exactly matching search
criteria, given as pairs of field-names and desired values.  

Ordinary search criteria include:

=over

=item *

C<<< dist >>> -- the distribution tarball name without any filename suffix; from 
a C<<< CPAN::Distribution >>> object, this is provided by the C<<< base_id >>> method.

=item *

C<<< phase >>> -- phase the report was generated during: either 'PL', 
'make' or 'test'

=item *

C<<< grade >>> -- CPAN Testers grade: 'PASS', 'FAIL', 'NA' or'UNKNOWN'; Also may
be 'DISCARD' for any failing reports not sent due to missing prerequisites

=back

Without additional criteria, a search will be limited to the current
version of Perl and the current architecture and OS version.  
Additional criteria may be specified explicitly or, by specifying the empty 
string, C<<< q{} >>>, will match that field for I<any> record.

     # all reports for Foo-Bar-1.23 on any version of perl 
     # on the current architecture and OS version
     @results = have_tested( dist => 'Foo-Bar-1.23', perl => q{} );

These additional criteria include:

=over

=item *

C<<< perl >>> -- perl version and possible patchlevel; this will be
dotted decimal (5.6.2) starting with version 5.6, or will be numeric style as
given by C<<< $] >>> for older versions; if a patchlevel exists, it must be specified
similar to "5.11.0 patch 12345"

=item *

C<<< archname >>> -- platform architecture name as given by $Config{archname}

=item *

C<<< osvers >>> -- operating system version as given by $Config{osvers}

=back

The function returns an array of hashes representing each test result, with
all of the fields listed above.

=head1 SEE ALSO

=over

=item *

L<CPAN::Reporter>

=item *

L<CPAN::Reporter::FAQ>

=back

=head1 AUTHOR

David A. Golden (DAGOLDEN)

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2006, 2007, 2008 by David A. Golden

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at 
L<http://www.apache.org/licenses/LICENSE-2.0>

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.