File::Find documentation #4867
Comments
From Ulrich.Windl@rz.uni-regensburg.deCreated by Ulrich.Windl@rz.uni-regensburg.deThe documentation for File::Find is not enough to be useful: Regards, Perl Info |
From @schwernOn Thu, Jan 17, 2002 at 12:32:51PM +0100, Ulrich Windl wrote:
Funny, the callback takes no arguments. Never realized that. Sort of However because of the way its called the caller's @_ does leak This patch also: Fixes the NAME to describe the module, not the functions therein. Makes the synopsis a little more descriptive. Adds a short overall description of the module. Adds short descriptions of each function, their arguments and Makes it a little clearer that the Big List Of Hash Arguments is Adds an explicit section about the wanted function. Reorganizes the $File::Find::dir/name and $_ explaination to Explicitly document that wanted takes no args. Ulrich, I've attached a copy of the new man page. Read it and see if Inline Patch--- lib/File/Find.pm Thu Jan 3 11:08:23 2002
+++ lib/File/Find.pm Thu Jan 17 16:31:37 2002
@@ -9,18 +9,16 @@
=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 @@
=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,8 +67,8 @@
=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>
@@ -145,21 +175,40 @@
=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. 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:
+=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
+
+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
@@ -650,7 +699,7 @@
$name = $abs_dir . $_; # $File::Find::name
- { &$wanted_callback }; # protect against wild "next"
+ { $wanted_callback->() }; # protect against wild "next"
}
@@ -731,7 +780,7 @@
$_= ($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;
}
@@ -779,7 +828,7 @@
}
@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
@@ -795,7 +844,7 @@
$name = $dir_pref . $FN; # $File::Find::name
$_ = ($no_chdir ? $name : $FN); # $_
- { &$wanted_callback }; # protect against wild "next"
+ { $wanted_callback->() }; # protect against wild "next"
}
}
@@ -819,13 +868,13 @@
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"
}
}
}
@@ -860,7 +909,7 @@
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;
@@ -882,7 +931,7 @@
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;
@@ -971,7 +1020,7 @@
# 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;
}
@@ -1026,7 +1075,7 @@
$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"
}
}
@@ -1075,7 +1124,7 @@
}
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;
-- Michael G. Schwern <schwern@pobox.com> http://www.pobox.com/~schwern/ |
From @schwernNAME SYNOPSIS use File::Find; use File::Find; DESCRIPTION find find() does a breadth-first search over the given @directories in For each file or directory found the &wanted subroutine is called finddepth finddepth() works just like find() except it does a depth-first %options Here are the possible keys for the hash: "wanted" "bydepth" "preprocess" "postprocess" "follow" * It is guaranteed that an *lstat* has been called before the * There is a variable $File::Find::fullname which holds the "follow_fast" "follow_skip" "dangling_symlinks" "no_chdir" "untaint" "untaint_pattern" "untaint_skip" The wanted function $File::Find::dir is the current directory name, For example, when examining the file /some/path/foo.ext you will have: $File::Find::dir = /some/path/ You are chdir()'d to$File::Find::dir when the function is called, unless $File::Find::name $File::Find::dir $_ no_chdir=>1 / / / When <follow> or <follow_fast> are in effect, there is also a This library is useful for the "find2perl" tool, which when fed, find2perl / -name .nfs\* -mtime +7 \ produces something like: sub wanted { Notice the "_" in the above "int(-M _)": the "_" is a magical filehandle Here's another interesting wanted function. It will find all symbolic sub wanted { See also the script "pfind" on CPAN for a nice application of this WARNINGS no warnings 'File::Find'; in the appropriate scope. See perllexwarn for more info about lexical CAVEAT You shouldn't need to set this variable, since File::Find should now If you do set $File::Find::dont_use_nlink to 1, you will notice symlinks NOTES * The path separator is ':', not '/', and the current directory is * $File::Find::dir is guaranteed to end with a ':'. If $_ contains * The default "untaint_pattern" (see above) on Mac OS is set to * The invisible system file "Icon\015" is ignored. While this file use Mac::Files; # invisible() -- returns 1 if file/directory is invisible, sub invisible($) { if ( $fileCat = FSpGetCatInfo($file) ) { Generally, invisible files are system files, unless an odd Files that appear on the desktop actually reside in an (hidden) HISTORY |
From @jhiOn Thu, Jan 17, 2002 at 04:35:47PM -0500, Michael G Schwern wrote:
Thanks, applied. -- |
From @schwernOn Fri, Jan 18, 2002 at 08:47:32AM +0100, Ulrich Windl wrote:
Ok, here it is. Hmm, what could we make changing the variables do... we could tie them Or not. ;) --- lib/File/Find.pm 2002/01/18 08:06:39 1.1 =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 For example, when examining the file /some/path/foo.ext you will have: -- Michael G. Schwern <schwern@pobox.com> http://www.pobox.com/~schwern/ |
From [Unknown Contact. See original ticket]On Thu, Jan 17, 2002 at 04:35:47PM -0500, Michael G Schwern wrote:
I think this man page would be much more useful with a few more If no-one comes up with anything, I'll have a look when I get back from tony Tony Bowden | tony@tmtm.com | http://www.tmtm.com/ |
Migrated from rt.perl.org#8274 (status was 'resolved')
Searchable as RT8274$
The text was updated successfully, but these errors were encountered: