maintenance/check_NAME.pl

   1 #!/usr/bin/perl
   2
   3 =head1 NAME
   4
   5 check_NAMEs.pl - check NAME in module POD has fully qualified object name
   6
   7 =head1 SYNOPSIS
   8
   9 B<check_NAMEs.pl> [B<-d|--dir> path] [B<-v|--verbose>] [B<-?|-h|--help>]
  10
  11 =head1 DESCRIPTION
  12
  13 This script is designed to find all Bioperl modules which don't
  14 have the fully qualified object name with correct capitalization
  15 in the "NAME" section of the POD.
  16
  17 The full name is required for the PDOC POD to HTML script to
  18 correctly render the module documentation.
  19
  20 =cut
  21
  22 use strict;
  23 use File::Find;
  24 use Getopt::Long;
  25
  26 #
  27 # command line options
  28 #
  29
  30 my ($verbose, $dir, $help) = (0, '../Bio/', undef);
  31 GetOptions(
  32     'v|verbose' => \$verbose,
  33     'd|dir:s' => \$dir,
  34     'h|help|?' => sub{ exec('perldoc',$0); exit(0) }
  35 );
  36
  37 #
  38 # globals
  39 #
  40
  41 my $num_found = 0;
  42
  43 #
  44 # find all modules
  45 #
  46
  47 print STDERR "Searching for incorrect NAME POD section of all modules in: $dir\n";
  48 find( \&find_modules, $dir );
  49 print STDERR "$num_found found.\n";
  50
  51 # this is where the action is
  52
  53 sub find_modules {
  54     # only want files with .pm
  55     return unless m/\.pm$/;
  56     return unless -f $_;
  57
  58     my $fname = $_;
  59     my $pm = $File::Find::name;
  60     $pm =~ s{.*?/(?=Bio/)}{};  # remove up to first slash before Bio/
  61     $pm =~ s{\.pm$}{};         # remove .pm suffix
  62     $pm =~ s{/}{::}g;          # convert / to ::
  63
  64     print STDERR "# $File::Find::name\n" if $verbose;
  65
  66     # slurp in the file
  67     my $text = do { local( @ARGV, $/ ) = $fname ; <> } ;
  68
  69     # check if the NAME section has the _full_ module name in it
  70     if ($text !~ m/^=head1\s+NAME.*?^$pm/xms) {
  71       print "$pm\n";
  72       $num_found++;
  73     }
  74 }
  75
  76
  77 =head1 OPTIONS
  78
  79 =over 3
  80
  81 =item B<-d | --dir> path
  82
  83 Overides the default directory to recursively look for .pm file
  84 (Default is '../Bio')
  85
  86 =item B<-v | --verbose>
  87
  88 Show the progress through files during the POD checking.
  89
  90 =item B<-? | -h  | --help>
  91
  92 This help text.
  93
  94 =back
  95
  96 =head1 FEEDBACK
  97
  98 =head2 Mailing Lists
  99
 100 User feedback is an integral part of the evolution of this and other
 101 Bioperl modules. Send your comments and suggestions preferably to
 102 the Bioperl mailing list.  Your participation is much appreciated.
 103
 104   bioperl-l@bioperl.org                  - General discussion
 105   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
 106
 107 =head2 Reporting Bugs
 108
 109 Report bugs to the Bioperl bug tracking system to help us keep track
 110 of the bugs and their resolution. Bug reports can be submitted via the
 111 web:
 112
 113   https://github.com/bioperl/bioperl-live/issues
 114
 115 =head1 AUTHOR - Torsten Seemann
 116
 117 Email: torsten-dot-seemann-at-infotech-dot-monash-dot-edu-dot-au
 118
 119 =cut