debian man page for file::find::wanted

Wanted(3pm)						User Contributed Perl Documentation					       Wanted(3pm)

NAME
       File::Find::Wanted - More obvious wrapper around File::Find

VERSION
       Version 1.00

SYNOPSIS
       File::Find is a great module, except that it doesn't actually find anything.  Its "find()" function walks a directory tree and calls a
       callback function.  Unfortunately, the callback function is deceptively called "wanted", which implies that it should return a boolean
       saying whether you want the file.  That's not how it works.

       Most of the time you call "find()", you just want to build a list of files.  There are other modules that do this for you, most notably
       Richard Clamp's great File::Find::Rule, but in many cases, it's overkill, and you need to learn a new syntax.

       With the "find_wanted" function, you supply a callback sub and a list of starting directories, but the sub actually should return a boolean
       saying whether you want the file in your list or not.

       To get a list of all files ending in .jpg:

	   my @files = find_wanted( sub { -f && /.jpg$/ }, $dir );

       For a list of all directories that are not CVS or .svn:

	   my @files = find_wanted( sub { -d && !/^(CVS|.svn)$/ }, $dir ) );

       It's easy, direct, and simple.

WHY DO THIS
?
       The cynical may say "that's just the same as doing this":

	   my @files;
	   find( sub { push @files, $File::Find::name if -f && /.jpg$/ }, $dir );

       Sure it is, but File::Find::Wanted makes it more obvious, and saves a line of code.  That's worth it to me.  I'd like it if find_wanted()
       made its way into the File::Find distro, but for now, this will do.

FUNCTIONS
   find_wanted( &wanted, @directories )
       Descends through @directories, calling the wanted function as it finds each file.  The function returns a list of all the files and
       directories for which the wanted function returned a true value.

       This is just a wrapper around "File::Find::find()".  See File::Find for details on how to modify its behavior.

COPYRIGHT &; LICENSE
       Copyright 2005-2012 Andy Lester.

       This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License v2.0.

perl v5.14.2							    2012-06-08							       Wanted(3pm)