X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FFile%2FFind.pm;h=9b1549429902368d7a1842c16c7eee50d867a87d;hb=3bb6d3e5122054efefe647ff1c834b844fec2fa2;hp=f43329da14c70af9e46eff11c6a9bdbe5d112479;hpb=00f4e5f0f8f9ab7a3ccc1dd6729033740c59fc4f;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/lib/File/Find.pm b/lib/File/Find.pm
index f43329d..9b15494 100644
--- a/lib/File/Find.pm
+++ b/lib/File/Find.pm
@@ -9,18 +9,16 @@ require Cwd;
 
 =head1 NAME
 
-find - traverse a file tree
-
-finddepth - traverse a directory structure depth-first
+File::Find - Traverse a directory tree.
 
 =head1 SYNOPSIS
 
     use File::Find;
-    find(\&wanted, '/foo', '/bar');
+    find(\&wanted, @directories_to_seach);
     sub wanted { ... }
 
     use File::Find;
-    finddepth(\&wanted, '/foo', '/bar');
+    finddepth(\&wanted, @directories_to_search);
     sub wanted { ... }
 
     use File::Find;
@@ -28,8 +26,40 @@ finddepth - traverse a directory structure depth-first
 
 =head1 DESCRIPTION
 
+These are functions for searching through directory trees doing work
+on each file found similar to the Unix I<find> command.  File::Find
+exports two functions, C<find> and C<finddepth>.  They work similarly
+but have subtle differences.
+
+=over 4
+
+=item B<find>
+
+  find(\&wanted,  @directories);
+  find(\%options, @directories);
+
+find() does a breadth-first search over the given @directories in the
+order they are given.  In essense, it works from the top down.
+
+For each file or directory found the &wanted subroutine is called (see
+below for details).  Additionally, for each directory found it will go
+into that directory and continue the search.
+
+=item B<finddepth>
+
+  finddepth(\&wanted,  @directories);
+  finddepth(\%options, @directories);
+
+finddepth() works just like find() except it does a depth-first search.
+It works from the bottom of the directory tree up.
+
+=back
+
+=head2 %options
+
 The first argument to find() is either a hash reference describing the
-operations to be performed for each file, or a code reference.
+operations to be performed for each file, or a code reference.  The
+code reference is described in L<The wanted function> below.
 
 Here are the possible keys for the hash:
 
@@ -37,14 +67,14 @@ Here are the possible keys for the hash:
 
 =item C<wanted>
 
-The value should be a code reference.  This code reference is called
-I<the wanted() function> below.
+The value should be a code reference.  This code reference is
+described in L<The wanted function> below.
 
 =item C<bydepth>
 
 Reports the name of a directory only AFTER all its entries
 have been reported.  Entry point finddepth() is a shortcut for
-specifying C<{ bydepth => 1 }> in the first argument of find().
+specifying C<{ bydepth =E<gt> 1 }> in the first argument of find().
 
 =item C<preprocess>
 
@@ -145,12 +175,48 @@ including all its sub-directories. The default is to 'die' in such a case.
 
 =back
 
-The wanted() function does whatever verifications you want.
-C<$File::Find::dir> contains the current directory name, and C<$_> the
-current filename within that directory.  C<$File::Find::name> contains
-the complete pathname to the file. You are chdir()'d to
-C<$File::Find::dir> when the function is called, unless C<no_chdir>
-was specified.  When C<follow> or C<follow_fast> are in effect, there is
+=head2 The wanted function
+
+The wanted() function does whatever verifications you want on each
+file and directory.  It takes no arguments but rather does its work
+through a collection of variables.
+
+=over 4
+
+=item C<$File::Find::dir> is the current directory name,
+
+=item C<$_> is the current filename within that directory
+
+=item C<$File::Find::name> is the complete pathname to the file.
+
+=back
+
+Don't modify these variables.
+
+For example, when examining the file /some/path/foo.ext you will have:
+
+    $File::Find::dir  = /some/path/
+    $_                = foo.ext
+    $File::Find::name = /some/path/foo.ext
+
+You are chdir()'d toC<$File::Find::dir> when the function is called,
+unless C<no_chdir> was specified. Note that when changing to
+directories is in effect the root directory (F</>) is a somewhat
+special case inasmuch as the concatenation of C<$File::Find::dir>,
+C<'/'> and C<$_> is not literally equal to C<$File::Find::name>. The
+table below summarizes all variants:
+
+              $File::Find::name  $File::Find::dir  $_
+ default      /                  /                 .
+ no_chdir=>0  /etc               /                 etc
+              /etc/x             /etc              x
+
+ no_chdir=>1  /                  /                 /
+              /etc               /                 /etc
+              /etc/x             /etc              /etc/x
+
+
+When <follow> or <follow_fast> are in effect, there is
 also a C<$File::Find::fullname>.  The function may set
 C<$File::Find::prune> to prune the tree unless C<bydepth> was
 specified.  Unless C<follow> or C<follow_fast> is specified, for
@@ -502,7 +568,7 @@ sub _find_opt {
     local ($wanted_callback, $avoid_nlink, $bydepth, $no_chdir, $follow,
 	$follow_skip, $full_check, $untaint, $untaint_skip, $untaint_pat,
 	$pre_process, $post_process, $dangling_symlinks);
-    local($dir, $name, $fullname, $prune);
+    local($dir, $name, $fullname, $prune, $_);
 
     my $cwd            = $wanted->{bydepth} ? Cwd::fastcwd() : Cwd::getcwd();
     my $cwd_untainted  = $cwd;
@@ -550,8 +616,6 @@ sub _find_opt {
 		$cwd = "$cwd:" unless ($cwd =~ /:$/); # for safety
 
 		if ($top_item eq $File::Find::current_dir) {
-                  # avoid empty name after return to '/'
-                  $name = '/' unless length( $name );
 		    $abs_dir = $cwd;
 		}
 		else {
@@ -636,8 +700,9 @@ sub _find_opt {
 	    }
 
 	    $name = $abs_dir . $_; # $File::Find::name
+	    $_ = $name if $no_chdir;
 
-	    { &$wanted_callback }; # protect against wild "next"
+	    { $wanted_callback->() }; # protect against wild "next"
 
 	}
 
@@ -718,7 +783,7 @@ sub _find_dir($$$) {
 	    $_= ($no_chdir ? $dir_name : $dir_rel ); # $_
 	    # prune may happen here
 	    $prune= 0;
-	    { &$wanted_callback };	# protect against wild "next"
+	    { $wanted_callback->() };	# protect against wild "next"
 	    next if $prune;
 	}
 
@@ -766,7 +831,7 @@ sub _find_dir($$$) {
 	}
 	@filenames = readdir DIR;
 	closedir(DIR);
-	@filenames = &$pre_process(@filenames) if $pre_process;
+	@filenames = $pre_process->(@filenames) if $pre_process;
 	push @Stack,[$CdLvl,$dir_name,"",-2]   if $post_process;
 
 	# default: use whatever was specifid
@@ -782,7 +847,7 @@ sub _find_dir($$$) {
 		
 		$name = $dir_pref . $FN; # $File::Find::name
 		$_ = ($no_chdir ? $name : $FN); # $_
-		{ &$wanted_callback }; # protect against wild "next"
+		{ $wanted_callback->() }; # protect against wild "next"
 	    }
 
 	}
@@ -806,13 +871,13 @@ sub _find_dir($$$) {
 		    else {
 			$name = $dir_pref . $FN; # $File::Find::name
 			$_= ($no_chdir ? $name : $FN); # $_
-			{ &$wanted_callback }; # protect against wild "next"
+			{ $wanted_callback->() }; # protect against wild "next"
 		    }
 		}
 		else {
 		    $name = $dir_pref . $FN; # $File::Find::name
 		    $_= ($no_chdir ? $name : $FN); # $_
-		    { &$wanted_callback }; # protect against wild "next"
+		    { $wanted_callback->() }; # protect against wild "next"
 		}
 	    }
 	}
@@ -847,7 +912,7 @@ sub _find_dir($$$) {
 	    if ( $nlink == -2 ) {
 		$name = $dir = $p_dir; # $File::Find::name / dir
                 $_ = $File::Find::current_dir;
-		&$post_process;		# End-of-directory processing
+		$post_process->();		# End-of-directory processing
 	    }
 	    elsif ( $nlink < 0 ) {  # must be finddepth, report dirname now
 		$name = $dir_name;
@@ -861,15 +926,15 @@ sub _find_dir($$$) {
 		}
 		else {
 		    if ( substr($name,-2) eq '/.' ) {
-			$name =~ s|/\.$||;
+			substr($name, length($name) == 2 ? -1 : -2) = '';
 		    }
 		    $dir = $p_dir;
 		    $_ = ($no_chdir ? $dir_name : $dir_rel );
 		    if ( substr($_,-2) eq '/.' ) {
-			s|/\.$||;
+			substr($_, length($_) == 2 ? -1 : -2) = '';
 		    }
 		}
-		{ &$wanted_callback }; # protect against wild "next"
+		{ $wanted_callback->() }; # protect against wild "next"
 	     }
 	     else {
 		push @Stack,[$CdLvl,$p_dir,$dir_rel,-1]  if  $bydepth;
@@ -958,7 +1023,7 @@ sub _find_dir_symlnk($$$) {
 	    # prune may happen here
 	    $prune= 0;
 	    lstat($_); # make sure  file tests with '_' work
-	    { &$wanted_callback }; # protect against wild "next"
+	    { $wanted_callback->() }; # protect against wild "next"
 	    next if $prune;
 	}
 
@@ -1013,7 +1078,7 @@ sub _find_dir_symlnk($$$) {
 		$fullname = $new_loc; # $File::Find::fullname 
 		$name = $dir_pref . $FN; # $File::Find::name
 		$_ = ($no_chdir ? $name : $FN); # $_
-		{ &$wanted_callback }; # protect against wild "next"
+		{ $wanted_callback->() }; # protect against wild "next"
 	    }
 	}
 
@@ -1052,17 +1117,17 @@ sub _find_dir_symlnk($$$) {
 		}
 		else {
 		    if ( substr($name,-2) eq '/.' ) {
-			$name =~ s|/\.$||; # $File::Find::name
+			substr($name, length($name) == 2 ? -1 : -2) = ''; # $File::Find::name
 		    }
 		    $dir = $p_dir; # $File::Find::dir
 		    $_ = ($no_chdir ? $dir_name : $dir_rel); # $_
 		    if ( substr($_,-2) eq '/.' ) {
-			s|/\.$||;
+			substr($_, length($_) == 2 ? -1 : -2) = '';
 		    }
 		}
 
 		lstat($_); # make sure file tests with '_' work
-		{ &$wanted_callback }; # protect against wild "next"
+		{ $wanted_callback->() }; # protect against wild "next"
 	    }
 	    else {
 		push @Stack,[$dir_loc, $updir_loc, $p_dir, $dir_rel,-1]  if  $bydepth;
@@ -1124,7 +1189,8 @@ $File::Find::current_dir = File::Spec->curdir || '.';
 
 $File::Find::dont_use_nlink = 1
     if $^O eq 'os2' || $^O eq 'dos' || $^O eq 'amigaos' || $^O eq 'MSWin32' ||
-       $^O eq 'cygwin' || $^O eq 'epoc' || $^O eq 'NetWare';
+       $^O eq 'cygwin' || $^O eq 'epoc' || $^O eq 'qnx' ||
+	   $^O eq 'nto';
 
 # Set dont_use_nlink in your hint file if your system's stat doesn't
 # report the number of links in a directory as an indication