1CPAN::Reporter::API(3)User Contributed Perl DocumentationCPAN::Reporter::API(3)
2
3
4

NAME

6       CPAN::Reporter::API - Programmer's interface to CPAN::Reporter
7

VERSION

9       version 1.2018
10

FUNCTIONS

12       CPAN::Reporter provides only a few public function for use within
13       CPAN.pm.  They are not imported during "use".  Ordinary users will
14       never need them.
15
16   "configure()"
17         CPAN::Reporter::configure();
18
19       Prompts the user to edit configuration settings stored in the
20       CPAN::Reporter "config.ini" file.  It will create the configuration
21       file if it does not exist.  It is automatically called by CPAN.pm when
22       initializing the 'test_report' option, e.g.:
23
24         cpan> o conf init test_report
25
26   "record_command()"
27         ($output, $exit_value) = CPAN::Reporter::record_command( $cmd, $secs );
28
29       Takes a command to be executed via system(), but wraps and tees it to
30       show the output to the console, capture the output, and capture the
31       exit code.  Returns an array reference of output lines (merged STDOUT
32       and STDERR) and the return value from system().  Note that this is $?,
33       so the actual exit value of the command will need to be extracted as
34       described in perlvar.
35
36       If the command matches /\b(?:Makefile|Build)\.PL\b/, then
37       Devel::Autoflush is added to "PERL5OPT" to force autoflushing of user
38       prompts.
39
40       If the command includes a pipe character ('|'), only the part of the
41       command prior to the pipe will be wrapped and teed.  The pipe will be
42       applied to the execution of the wrapper script.  This is essential to
43       capture the exit value of the command and should be otherwise
44       transparent.
45
46       If a non-zero $secs argument is provided, the command will be run with
47       a timeout of $secs (seconds) if the appropriate process management
48       modules are available.  On Win32, Win32::Job must be available; on
49       Unix, Proc::Killfam must be available.  Otherwise, code will fall-back
50       to running without a timeout.
51
52       Also, on Win32, the first space-separated element of the command must
53       be absolute, or else ".exe" will be appended and the PATH searched for
54       a matching command.
55
56       If the attempt to record fails, a warning will be issued and one or
57       more of $output or $exit_value will be undefined.
58
59   "grade_make()"
60         CPAN::Reporter::grade_make( $dist, $command, \@output, $exit);
61
62       Given a CPAN::Distribution object, the system command used to build the
63       distribution (e.g. "make", "perl Build"), an array of lines of output
64       from the command and the exit value from the command, "grade_make()"
65       determines a grade for this stage of distribution installation.  If the
66       grade is "pass", "grade_make()" does not send a CPAN Testers report for
67       this stage and returns true to signal that the build was successful.
68       Otherwise, a CPAN Testers report is sent and "grade_make()" returns
69       false.
70
71   "grade_PL()"
72         CPAN::Reporter::grade_PL( $dist, $command, \@output, $exit);
73
74       Given a CPAN::Distribution object, the system command used to run
75       Makefile.PL or Build.PL (e.g. "perl Makefile.PL"), an array of lines of
76       output from the command and the exit value from the command,
77       "grade_PL()" determines a grade for this stage of distribution
78       installation.  If the grade is "pass", "grade_PL()" does not send a
79       CPAN Testers report for this stage and returns true to signal that the
80       Makefile.PL or Build.PL ran successfully.  Otherwise, a CPAN Testers
81       report is sent and "grade_PL()" returns false.
82
83   "grade_test()"
84         CPAN::Reporter::grade_test( $dist, $command, \@output, $exit);
85
86       Given a CPAN::Distribution object, the system command used to run tests
87       (e.g.  "make test"), an array of lines of output from testing and the
88       exit value from the system command, "grade_test()" determines a grade
89       for distribution tests.  A CPAN Testers report is then sent unless
90       specified prerequisites were not satisfied, in which case the report is
91       discarded.  This function returns true if the grade is "pass" or
92       "unknown" and returns false, otherwise.
93
94   "test()" -- DEPRECATED
95         CPAN::Reporter::test( $cpan_dist, $system_command );
96
97       This function is maintained for backwards compatibility.  It
98       effectively wraps the functionality of "record_command()" and
99       "grade_test()" into a single function call. It takes a
100       CPAN::Distribution object and the system command to run distribution
101       tests.
102

SEE ALSO

104       ·   CPAN::Reporter
105
106       ·   CPAN::Reporter::Config
107
108       ·   CPAN::Reporter::FAQ
109

AUTHOR

111       David Golden <dagolden@cpan.org>
112

114       This software is Copyright (c) 2006 by David Golden.
115
116       This is free software, licensed under:
117
118         The Apache License, Version 2.0, January 2004
119
120
121
122perl v5.30.1                      2020-01-29            CPAN::Reporter::API(3)
Impressum