NAME
    CPAN::Testers::Report - Creates CPAN Testers test-report objects

SYNOPSIS
      use CPAN::Testers::Report;
      use Config;

      my $test_report = CPAN::Testers::Report->new();
      $test_report->comments('Rejoice!');
      $test_report->config(Config::myconfig()) || die $test_report->error();
      $test_report->dist('Test-Reporter-1.34') || die $test_report->error();
      $test_report->from('Adam J. Foxson <afoxson@pobox.com>') || die $test_report->error();
      $test_report->grade('pass') || die $test_report->error();

DESCRIPTION
    Welcome to CPAN::Testers::Report. This is the first distribution in the
    CPAN::Testers namespace. This module is designed to be part of the
    next-generation implementation of the CPAN Tester's stack. When
    complete, this distribution and its constituents will obsolete
    Test::Reporter.

    This module provides an abstraction for test reports. Objects will
    encapsulate all data and information about a single, specific test
    report. These objects can then be submitted to a user's transport of
    choice for delivery.

    This is a developer's release. The interface is not stable; The API may
    change at any time without notice. This module is not yet recommended
    for general use.

METHODS
    * archname
        Automatically calculated but can be overriden. This is a short name
        to characterize the current architecture.

    * comments
        User-specified comments to include with the test report. This is
        oftentimes the output of a failed 'make test'. Optional.

    * config
        This method should be the recipient of Config::myconfig().
        Mandatory. If this method returns undef, it failed.

    * dist
        Full distribution name and version of which this test report is
        about. For example 'Test-Reporter-1.34'. Mandatory. If this methods
        returns undef, it failed. Attempts to call this method with anything
        resembling a distribution of perl itself will not be honored (use
        perlbug).

    * dist_name
        Automatically calculated but can be overriden. This represents the
        distribution's name only. For example 'Test-Reporter'.

    * dist_vers
        Automatically calculated but can be overriden. This represents the
        distribution's version only. For example '1.34'.

    * error
        Returns an error message when an error has occurred.

    * from
        Name and e-mail address of the tester. For example 'Adam J. Foxson
        <afoxson@pobox.com>'. Optional, but if specified it must be RFC 2822
        compliant. If you ever need to parse this out to separate the name
        from the e-mail address, visit Email::Address. If this method
        returns undef, it failed (i.e., what you specified was not RFC 2822
        compliant).

    * grade
        Grade for the result of 'make test'. Must be pass, fail, na, or
        unknown. 'Pass' indicates that all tests passed. 'Fail' indicates
        one or more tests failed. 'Na' indicates that the distribution will
        not work on this platform. 'Unknown' indicates that the distribution
        did not include tests. Mandatory. If this method returns undef, it
        failed.

    * interpreter
        At the moment always returns 'perl'.

    * interpreter_vers_numeric
        Automatically calculated but can be overriden. This represents the
        interpreter's version. For example in the format of '5.8.8'.

    * interpreter_vers_float
        Automatically calculated but can be overriden. This represents the
        interpreter's version. For example in the format of '5.008008'.

    * interpreter_vers_extra
        Automatically calculated but can be overriden. This usually
        represents the interpreter's patch/patchlevel, if available. For
        example 'patchlevel 12345'.

    * new
        Constructor. Accepts no arguments at this time.

    * osname
        Automatically calculated but can be overriden. This is the operating
        system name.

    * osvers
        Automatically calculated but can be overriden. This is the operating
        system version.

    * report_vers
        Revision of the internal test report object format.

    * rfc2822_date
        Automatically calculated but can be overriden. This is the
        RFC2822-compliant datetime.

    * via
        Automatically calculated (based on the caller) but can be overriden.
        This represents the automation wrapping CPAN::Testers::Report. This
        is usually something like CPAN::Reporter, CPAN::YACSmoke.

TODO
    Please excuse me for a few moments while I think aloud publically. :-)

    * Add tests for error conditions
        At a minimum:

        * dist()
        * from()
        * grade()
        * config()

    * Add a validate() method to ensure overall consistency?
        This is not intended to indicate suitablity for any particular
        transport. This is more about verifying that the object contains the
        minimum necessary data and in a correct form to even be considered a
        valid test report. A transport could call this as a sanity check
        before attempting delivery.

        * a distribution that is parseable into its name and version
        components
        * a config that is parseable into its archname, osvers, and perl
        version components
        * a from, if specified, must be RFC 2822 compliant
        * a grade that is one of 'pass', 'fail', 'na', or 'unknown'

    * Decide what to do about "interpreter"
        The idea behind this is that CPAN modules might theoretically be
        able to be run under interpreters other than perl itself. Therefore,
        it might be a potentially valueable endeavor to test this. For
        example, in the past, ponie would have been an example of where this
        might have occurred. Nowadays, would pugs perhaps be a current
        example?

        The question is whether or not we want to actually accomodate for
        this possibility. Or to restate, do we want to have support for
        testing CPAN distributions with interpreters that are "perl-like"?

    * Shall the metadata be handled specially (from/date/via) ?
        These are all three bits of data that are arguably part of a
        test-report, but a test-report can be fully 100% valid in all of
        their absence. As such, I'm wondering if we want to handle these
        differently/specially. Food for thought!

    * RFC 2822 compliance regex shouldn't be assembled on a per object basis
        This is inefficient and needs to be addressed.

    * Hmm. What to do about the subject...
        Doesn't really belong in this module (because the concept of
        'Subject' is specfic only to a particular class of transport), but
        we don't want each e-mail based transport reimplementing this
        functionality or duplicating code. And, we need the flexibility to
        change it in the future without major disruption. So then, what we
        might want to do is create a new distribution that provides methods
        to do both parsing and generating of subjects, once passed a
        previously generated subject or CPAN::Testers::Report object.

    * Hmm. What to do about the "stringified formatted report"...
        Almost 3am! Time for bed... More to come tomorrow...

COPYRIGHT
    Copyright (c) 2007 Adam J. Foxson and the CPAN Testers. All rights
    reserved.

LICENSE
    This program is free software; you may redistribute it and/or modify it
    under the same terms as Perl itself.

SEE ALSO
    * perl
    * CPAN::Testers

AUTHOR
    Adam J. Foxson <afoxson@pobox.com>

    With many thanks to:

    * Richard Soderberg <rsod@cpan.org>
    * Kirrily "Skud" Robert <skud@cpan.org>
    * Kurt Starsinic <Kurt.Starsinic@isinet.com>
    * Barbie <barbie@missbarbell.co.uk>
    * David Golden <dagolden@cpan.org>

