Perl POD coverage for scripts and tests (not modules)

Question

Is there a way to measure POD coverage for scripts (e.g. *.pl)?

I can measure documentation coverage for packages using Pod::Coverage and Test::Pod::Coverage, but I cannot measure it for scripts, because Pod::Coverage and the underlying Devel::Symdump use require to inspect the content of the package, which fails due to the lack of a .pm file.

Is there a way to work around this?

(I have to have POD documentation in the .pl files, so moving everything into a module and documenting it there is not a good solution for me. Wherever I could do that, it's already done that way.)

Answer 1

Pod::Coverage loads (executes) the module to let it create subs and such. You would have to prevent your .pl from running normally somehow.

#!/usr/bin/perl
...
main(@ARGV) if !$ENV{NO_RUN};
1; # For do()

But once you've done that, it's easy because you tell Pod::Coverage which package to examine (package) and which file to examine (pod_from).

#!/usr/bin/perl

use strict;
use warnings;

use Test::More tests => 1;

use Pod::Coverage qw( );

{
    package the_script;
    local $ENV{NO_RUN} = 1;
    do "script.pl" or die $@;
}

my $pc = Pod::Coverage->new(
   package  => 'the_script',
   pod_from => 'script.pl',
);

# P::C expects "require the_script;" to succeed.
$INC{"the_script.pm"} = 1;

my $coverage = $pc->coverage();
die $pc->why_unrated()
   if !defined($coverage);

ok($coverage)
   or diag("Not covered: ".join(', ', $pc->naked()));

1;

Tested.

Answer 2

Make your program a modulino. That's what ikegami is doing, but he makes you set an environment variable.

run(@ARGV) unless caller;

Once your program is really a module with some default behavior, you can use module tools on it.