File Coverage

blib/lib/Module/Install/PodFromEuclid.pm

Criterion	Covered	Total	%
statement	18	34	52.9
branch	0	12	0.0
condition	0	2	0.0
subroutine	6	8	75.0
pod	1	1	100.0
total	25	57	43.8

package Module::Install::PodFromEuclid;


=head1 NAME

Module::Install::PodFromEuclid - Module::Install extension to make POD from
Getopt::Euclid-based scripts

=head1 SYNOPSIS

  # In Makefile.PL:
  use inc::Module::Install;
  author 'John Doe';
  license 'perl';
  pod_from 'scripts/my_script.pl';

=head1 DESCRIPTION

Module::Install::PodFromEuclid is a L extension that generates
a C file automatically from an indicated script containing Getopt::Euclid
command-line specifications.

The POD file is generated using the --podfile option of Getopt::Euclid, but only
whenever authors run C. While this extension will be bundled in
your distribution, the pod_from command does nothing on the user-side.

Note: Authors should make sure that C is
installed before running C.

This module was inspired and borrows a lot from C.

=head1 COMMANDS

This plugin adds the following Module::Install command:

=over

=item C

Does nothing on the user-side. On the author-side it will generate a C
file that has the same base name as the Perl file, using Getopt::Euclid's
--podfile feature:

  pod_from 'scripts/my_script.pl';  # generate scripts/my_script.pod

If you use the C command, C will default to this value.

  all_from 'scripts/my_script.pl';
  pod_from;                         # create scripts/my_script.pod

=back

=head1 AUTHOR

Florent Angly

=head1 LICENSE

Copyright Florent Angly

This module may be used, modified, and distributed under the same terms as Perl
itself. Please see the license that came with your Perl distribution for details.

=head1 SEE ALSO

L

L

L

=cut


use 5.006;
use strict;
use warnings;
use File::Spec;
use Env qw(@INC);
use base qw(Module::Install::Base);

our $VERSION = '0.01';


sub pod_from {
   my ($self, $in_file) = @_;
   return unless $self->is_admin;
   if (not defined $in_file) {
      $in_file = $self->_all_from or die "Error: Could not determine file to make pod_from";
   }
   my @inc = map { ( '-I', File::Spec->rel2abs($_) ) } @INC;
   # use same -I included modules as caller
   my @args = ($^X, @inc, $in_file, '--podfile');
   system(@args) == 0 or die "Error: Could not run command ".join(' ',@args).": $?\n";
   return 1;
}


sub _all_from {
   my $self = shift;
   return unless $self->admin->{extensions};
   my ($metadata) = grep {
      ref($_) eq 'Module::Install::Metadata';
   } @{$self->admin->{extensions}};
   return unless $metadata;
   return $metadata->{values}{all_from} || '';
}


1;