CPAN::...er::API(3pm)

📦
version 1.2020 · 5 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

okay so bestie, this is CPAN::Reporter::API — it's giving "Programmer's interface to CPAN::Reporter" 🫶 like, the backstage pass to the whole thing.

🌸 VERSION 🌸

version 1.2020 ✨ (yes queen, we're on that version)

🎀 FUNCTIONS 🎀

so here's the tea, CPAN::Reporter only hands out a few public functions for use inside CPAN.pm. they are not imported during "use" — like, they don't just show up uninvited 😤. and fr fr, ordinary users will never need them. this is strictly for the devs in the group chat.

💅 configure()

CPAN::Reporter::configure();

this one prompts the user to edit the configuration settings stored in the CPAN::Reporter config.ini file 🌸. it will create that config file if it doesn't already exist — very "i made it myself, you're welcome" energy. it gets automatically called by CPAN.pm when initializing the 'test_report' option, like:

cpan> o conf init test_report

🌈 record_command()

($output, $exit_value) = CPAN::Reporter::record_command( $cmd, $secs );

takes a command to be executed via system(), 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 STDOUT and STDERR) and the return value from system().

⚠️ okay important: this return value is $?, so the actual exit value of the command will need to be extracted as described in perlvar. don't forget bestie 😭

a few things to know:

  • If the command matches /\b(?:Makefile|Build)\.PL\b/, then Devel::Autoflush is added to "PERL5OPT" to force autoflushing of user prompts 🦋.
  • 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 ✨.
  • If a non-zero $secs argument is provided, the command will be run with a timeout of $secs (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 🙈.
  • Also, on Win32, the first space-separated element of the command must be absolute, or else ".exe" will be appended and the PATH searched for a matching command 👑.
  • If the attempt to record fails, a warning will be issued and one or more of $output or $exit_value will be undefined 💀.

⭐ grade_make()

CPAN::Reporter::grade_make( $dist, $command, \@output, $exit);

given a CPAN::Distribution object, the system command used to build the distribution (e.g. "make", "perl Build"), an array of lines of output from the command and the exit value from the command, grade_make() determines a grade for this stage of distribution installation 🌸.

If the grade is "pass", grade_make() does not send a CPAN Testers report for this stage and returns true to signal that the build was successful 🎉. Otherwise, a CPAN Testers report is sent and grade_make() returns false 😔.

🦋 grade_PL()

CPAN::Reporter::grade_PL( $dist, $command, \@output, $exit);

given a CPAN::Distribution object, the system command used to run Makefile.PL or Build.PL (e.g. "perl Makefile.PL"), an array of lines of output from the command and the exit value from the command, grade_PL() determines a grade for this stage of distribution installation ✨.

If the grade is "pass", grade_PL() does not send a CPAN Testers report for this stage and returns true to signal that the Makefile.PL or Build.PL ran successfully 💖. Otherwise, a CPAN Testers report is sent and grade_PL() returns false 💀.

💜 grade_test()

CPAN::Reporter::grade_test( $dist, $command, \@output, $exit);

given a CPAN::Distribution object, the system command used to run tests (e.g. "make test"), an array of lines of output from testing and the exit value from the system command, grade_test() determines a grade for distribution tests 🌈.

A CPAN 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 "pass" or "unknown" and returns false, otherwise 👑

🥀 test() — DEPRECATED

CPAN::Reporter::test( $cpan_dist, $system_command );
🚨 bestie this one is DEPRECATED. it's still here, but like... it's giving legacy.

this function is maintained for backwards compatibility 🫶. It effectively wraps the functionality of record_command() and grade_test() into a single function call. It takes a CPAN::Distribution object and the system command to run distribution tests 🎀.

👀 SEE ALSO 👀

  • CPAN::Reporter
  • CPAN::Reporter::Config
  • CPAN::Reporter::FAQ

🌟 AUTHOR 🌟

David Golden <dagolden@cpan.org> 💌

This software is Copyright (c) 2023 by David Golden.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

and that's the whole page bestie, no cap 💅 this was CPAN::Reporter::API(3pm) from the User Contributed Perl Documentation, running under perl v5.40.0 and dated 2024-08-17 — slay, you read the whole thing, i'm so proud of you 🫶✨💖

📦 where this page comes from