#############################################################################
# Pod/Find.pm -- finds files containing POD documentation
#
-# Author: Marek Rouchal <marek@saftsack.fs.uni-bayreuth.de>
+# Author: Marek Rouchal <marekr@cpan.org>
#
# Copyright (C) 1999-2000 by Marek Rouchal (and borrowing code
# from Nick Ing-Simmon's PodToHtml). All rights reserved.
#############################################################################
package Pod::Find;
+use strict;
use vars qw($VERSION);
-$VERSION = 0.23; ## Current version of this package
+$VERSION = '1.35'; ## Current version of this package
require 5.005; ## requires this Perl version or later
use Carp;
+BEGIN {
+ if ($] < 5.006) {
+ require Symbol;
+ import Symbol;
+ }
+}
+
#############################################################################
=head1 NAME
use Pod::Find qw(pod_find);
+From this version on the typical SCM (software configuration management)
+files/directories like RCS, CVS, SCCS, .svn are ignored.
+
=cut
-use strict;
#use diagnostics;
use Exporter;
use File::Spec;
Search for PODs in the current Perl interpreter's I<@INC> paths. This
automatically considers paths specified in the C<PERL5LIB> environment
-as this is prepended to I<@INC> by the Perl interpreter itself.
+as this is included in I<@INC> by the Perl interpreter itself.
=back
for (@new_INC) {
if ( $_ eq '.' ) {
$_ = ':';
- } elsif ( $_ =~ s|^((?:\.\./)+)|':' x (length($1)/3)|e ) {
+ } elsif ( $_ =~ s{^((?:\.\./)+)}{':' x (length($1)/3)}e ) {
$_ = ':'. $_;
} else {
- $_ =~ s|^\./|:|;
+ $_ =~ s{^\./}{:};
}
}
push(@search, grep($_ ne File::Spec->curdir, @new_INC));
File::Find::find( sub {
my $item = $File::Find::name;
if(-d) {
- if($dirs_visited{$item}) {
+ if($item =~ m{/(?:RCS|CVS|SCCS|\.svn)$}) {
+ $File::Find::prune = 1;
+ return;
+ }
+ elsif($dirs_visited{$item}) {
warn "Directory '$item' already seen, skipping.\n"
if($opts{-verbose});
$File::Find::prune = 1;
}, $try); # end of File::Find::find
}
chdir $pwd;
- %pods;
+ return %pods;
}
sub _check_for_duplicates {
my ($file, $name, $names_ref, $pods_ref) = @_;
if($$names_ref{$name}) {
warn "Duplicate POD found (shadowing?): $name ($file)\n";
- warn " Already seen in ",
+ warn ' Already seen in ',
join(' ', grep($$pods_ref{$_} eq $name, keys %$pods_ref)),"\n";
}
else {
$$names_ref{$name} = 1;
}
- $$pods_ref{$file} = $name;
+ return $$pods_ref{$file} = $name;
}
sub _check_and_extract_name {
# check extension or executable flag
# this involves testing the .bat extension on Win32!
- unless(-f $file && -T _ && ($file =~ /\.(pod|pm|plx?)\z/i || -x _ )) {
- return undef;
+ unless(-f $file && -T $file && ($file =~ /\.(pod|pm|plx?)\z/i || -x $file )) {
+ return;
}
- return undef unless contains_pod($file,$verbose);
+ return unless contains_pod($file,$verbose);
# strip non-significant path components
# TODO what happens on e.g. Win32?
my $name = $file;
if(defined $root_rx) {
- $name =~ s!$root_rx!!s;
- $name =~ s!$SIMPLIFY_RX!!os if(defined $SIMPLIFY_RX);
+ $name =~ s/$root_rx//s;
+ $name =~ s/$SIMPLIFY_RX//s if(defined $SIMPLIFY_RX);
}
else {
if ($^O eq 'MacOS') {
$name =~ s/^.*://s;
} else {
- $name =~ s:^.*/::s;
+ $name =~ s{^.*/}{}s;
}
}
_simplify($name);
- $name =~ s!/+!::!g; #/
+ $name =~ s{/+}{::}g;
if ($^O eq 'MacOS') {
- $name =~ s!:+!::!g; # : -> ::
+ $name =~ s{:+}{::}g; # : -> ::
} else {
- $name =~ s!/+!::!g; # / -> ::
+ $name =~ s{/+}{::}g; # / -> ::
}
- $name;
+ return $name;
}
=head2 C<simplify_name( $str )>
if ($^O eq 'MacOS') {
$str =~ s/^.*://s;
} else {
- $str =~ s:^.*/::s;
+ $str =~ s{^.*/}{}s;
}
_simplify($str);
- $str;
+ return $str;
}
# internal sub only
for (@new_INC) {
if ( $_ eq '.' ) {
$_ = ':';
- } elsif ( $_ =~ s|^((?:\.\./)+)|':' x (length($1)/3)|e ) {
+ } elsif ( $_ =~ s{^((?:\.\./)+)}{':' x (length($1)/3)}e ) {
$_ = ':'. $_;
} else {
- $_ =~ s|^\./|:|;
+ $_ =~ s{^\./}{:};
}
}
push (@search_dirs, @new_INC);
if -d $Config::Config{'scriptdir'};
}
- warn "Search path is: ".join(' ', @search_dirs)."\n"
+ warn 'Search path is: '.join(' ', @search_dirs)."\n"
if $options{'-verbose'};
# Loop over directories
# Don't bother if can't find the directory
if (-d $dir) {
- warn "Looking in directory $dir\n"
+ warn "Looking in directory $dir\n"
if $options{'-verbose'};
# Now concatenate this directory with the pod we are searching for
# Loop over possible extensions
foreach my $ext ('', '.pod', '.pm', '.pl') {
my $fullext = $fullname . $ext;
- if (-f $fullext &&
+ if (-f $fullext &&
contains_pod($fullext, $options{'-verbose'}) ) {
warn "FOUND: $fullext\n" if $options{'-verbose'};
return $fullext;
if $options{'-verbose'};
next Dir;
}
- # for some strange reason the path on MacOS/darwin is
+ # for some strange reason the path on MacOS/darwin/cygwin is
# 'pods' not 'pod'
# this could be the case also for other systems that
# have a case-tolerant file system, but File::Spec
- # does not recognize 'darwin' yet
- #if(File::Spec->case_tolerant && -d File::Spec->catdir($dir,'pods')) {
- if($^O =~ /macos|darwin/i && -d File::Spec->catdir($dir,'pods')) {
+ # does not recognize 'darwin' yet. And cygwin also has "pods",
+ # but is not case tolerant. Oh well...
+ if((File::Spec->case_tolerant || $^O =~ /macos|darwin|cygwin/i)
+ && -d File::Spec->catdir($dir,'pods')) {
$dir = File::Spec->catdir($dir,'pods');
redo Dir;
}
}
}
# No match;
- return undef;
+ return;
}
=head2 C<contains_pod( $file , $verbose )>
$verbose = shift if @_;
# check for one line of POD
- unless(open(POD,"<$file")) {
+ my $podfh;
+ if ($] < 5.006) {
+ $podfh = gensym();
+ }
+
+ unless(open($podfh,"<$file")) {
warn "Error: $file is unreadable: $!\n";
- return undef;
+ return;
}
local $/ = undef;
- my $pod = <POD>;
- close(POD) || die "Error closing $file: $!\n";
- unless($pod =~ /\n=(head\d|pod|over|item)\b/s) {
+ my $pod = <$podfh>;
+ close($podfh) || die "Error closing $file: $!\n";
+ unless($pod =~ /^=(head\d|pod|over|item|cut)\b/m) {
warn "No POD in $file, skipping.\n"
if($verbose);
return 0;
=head1 AUTHOR
-Marek Rouchal E<lt>marek@saftsack.fs.uni-bayreuth.deE<gt>,
+Please report bugs using L<http://rt.cpan.org>.
+
+Marek Rouchal E<lt>marekr@cpan.orgE<gt>,
heavily borrowing code from Nick Ing-Simmons' PodToHtml.
Tim Jenness E<lt>t.jenness@jach.hawaii.eduE<gt> provided
https://perl5.git.perl.org / perl5.git / blobdiff