.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "CPAN::Reporter::API 3pm"
.TH CPAN::Reporter::API 3pm "2016-07-20" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CPAN::Reporter::API \- Programmer's interface to CPAN::Reporter
.SH "VERSION"
.IX Header "VERSION"
version 1.2018
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
CPAN::Reporter provides only a few public function for use within \s-1CPAN\s0.pm.
They are not imported during \f(CW\*(C`use\*(C'\fR.  Ordinary users will never need them.
.ie n .SS """configure()"""
.el .SS "\f(CWconfigure()\fP"
.IX Subsection "configure()"
.Vb 1
\&  CPAN::Reporter::configure();
.Ve
.PP
Prompts the user to edit configuration settings stored in the CPAN::Reporter
\&\f(CW\*(C`config.ini\*(C'\fR file.  It will create the configuration file if it does not exist.
It is automatically called by \s-1CPAN\s0.pm when initializing the 'test_report'
option, e.g.:
.PP
.Vb 1
\&  cpan> o conf init test_report
.Ve
.ie n .SS """record_command()"""
.el .SS "\f(CWrecord_command()\fP"
.IX Subsection "record_command()"
.Vb 1
\&  ($output, $exit_value) = CPAN::Reporter::record_command( $cmd, $secs );
.Ve
.PP
Takes a command to be executed via \fIsystem()\fR, but wraps and tees it to
show the output to the console, capture the output, and capture the
exit code.  Returns an array reference of output lines (merged \s-1STDOUT\s0 and
\&\s-1STDERR\s0) and the return value from \fIsystem()\fR.  Note that this is \f(CW$?\fR, so the
actual exit value of the command will need to be extracted as described in
perlvar.
.PP
If the command matches /\eb(?:Makefile|Build)\e.PL\eb/, then Devel::Autoflush
is added to \f(CW\*(C`PERL5OPT\*(C'\fR to force autoflushing of user prompts.
.PP
If the command includes a pipe character ('|'), only the part of the 
command prior to the pipe will be wrapped and teed.  The pipe will be
applied to the execution of the wrapper script.  This is essential to 
capture the exit value of the command and should be otherwise transparent.
.PP
If a non-zero \f(CW$secs\fR argument is provided, the command will be run with a
timeout of \f(CW$secs\fR (seconds) if the appropriate process management modules are
available.  On Win32, Win32::Job must be available; on Unix, Proc::Killfam
must be available.  Otherwise, code will fall-back to running without a
timeout.
.PP
Also, on Win32, the first space-separated element of the command must be
absolute, or else \*(L".exe\*(R" will be appended and the \s-1PATH\s0 searched for a matching
command.
.PP
If the attempt to record fails, a warning will be issued and one or more of 
\&\f(CW$output\fR or \f(CW$exit_value\fR will be undefined.
.ie n .SS """grade_make()"""
.el .SS "\f(CWgrade_make()\fP"
.IX Subsection "grade_make()"
.Vb 1
\&  CPAN::Reporter::grade_make( $dist, $command, \e@output, $exit);
.Ve
.PP
Given a CPAN::Distribution object, the system command used to build the
distribution (e.g. \*(L"make\*(R", \*(L"perl Build\*(R"), an array of lines of output from the
command and the exit value from the command, \f(CW\*(C`grade_make()\*(C'\fR determines a grade
for this stage of distribution installation.  If the grade is \*(L"pass\*(R",
\&\f(CW\*(C`grade_make()\*(C'\fR does \fBnot\fR send a \s-1CPAN\s0 Testers report for this stage and returns
true to signal that the build was successful.  Otherwise, a \s-1CPAN\s0 Testers report
is sent and \f(CW\*(C`grade_make()\*(C'\fR returns false.
.ie n .SS """grade_PL()"""
.el .SS "\f(CWgrade_PL()\fP"
.IX Subsection "grade_PL()"
.Vb 1
\&  CPAN::Reporter::grade_PL( $dist, $command, \e@output, $exit);
.Ve
.PP
Given a CPAN::Distribution object, the system command used to run Makefile.PL
or Build.PL (e.g. \*(L"perl Makefile.PL\*(R"), an array of lines of output from the
command and the exit value from the command, \f(CW\*(C`grade_PL()\*(C'\fR determines a grade
for this stage of distribution installation.  If the grade is \*(L"pass\*(R",
\&\f(CW\*(C`grade_PL()\*(C'\fR does \fBnot\fR send a \s-1CPAN\s0 Testers report for this stage and returns
true to signal that the Makefile.PL or Build.PL ran successfully.  Otherwise, a
\&\s-1CPAN\s0 Testers report is sent and \f(CW\*(C`grade_PL()\*(C'\fR returns false.
.ie n .SS """grade_test()"""
.el .SS "\f(CWgrade_test()\fP"
.IX Subsection "grade_test()"
.Vb 1
\&  CPAN::Reporter::grade_test( $dist, $command, \e@output, $exit);
.Ve
.PP
Given a CPAN::Distribution object, the system command used to run tests (e.g.
\&\*(L"make test\*(R"), an array of lines of output from testing and the exit value from
the system command, \f(CW\*(C`grade_test()\*(C'\fR determines a grade for distribution tests.
A \s-1CPAN\s0 Testers report is then sent unless specified prerequisites were not
satisfied, in which case the report is discarded.  This function returns true
if the grade is \*(L"pass\*(R" or \*(L"unknown\*(R" and returns false, otherwise.
.ie n .SS """test()"" \*(-- \s-1DEPRECATED\s0"
.el .SS "\f(CWtest()\fP \*(-- \s-1DEPRECATED\s0"
.IX Subsection "test() DEPRECATED"
.Vb 1
\&  CPAN::Reporter::test( $cpan_dist, $system_command );
.Ve
.PP
This function is maintained for backwards compatibility.  It effectively 
wraps the functionality of \f(CW\*(C`record_command()\*(C'\fR and \f(CW\*(C`grade_test()\*(C'\fR into
a single function call. It takes a CPAN::Distribution object and the system
command to run distribution tests.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
CPAN::Reporter
.IP "\(bu" 4
CPAN::Reporter::Config
.IP "\(bu" 4
CPAN::Reporter::FAQ
.SH "AUTHOR"
.IX Header "AUTHOR"
David Golden <dagolden@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2006 by David Golden.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Apache License, Version 2.0, January 2004
.Ve