File::Recurse

Recurse(3)            User Contributed Perl Documentation           Recurse(3)



NAME
       File::Recurse - Recurse over files, performing some function.

SYNOPSIS
               use File::Recurse;
               use File::Copy;

               recurse { print } "/tmp";
               recurse {copy($_,"elsewhere") if -f $_} "dir";
               recurse(\&func, "/");


DESCRIPTION
       The File::Recurse module is designed for performing an operation on a
       tree of directories and files. The basic usage is simmilar to the
       find.pl library. Once one uses the File::Recurse module, you need only
       call the recurse function in order to perform recursive directory
       operations.

       The function takes two parameters a function reference and a directory.
       The function referenced by the first parameter should expect to take
       one parameter: the full path to the file currently being operated on.
       This function is called once for every file and directory under the
       directory named by the second parameter.

       For example:

               recurse(\&func, "/");

       would start at the top level of the filesystem and call "func" for
       every file and directory found (not including "/").

       Perl allows a second form of calling this function which can be useful
       for situations where you want to do something simple in the function.
       In these cases, you can define an anonymous function by using braces
       like so:

               recurse {print $_[0]} "/";

       This would print every file and directory in the filesystem. However,
       as an added convenience you can access the pathname in the variable $_.
       So the above could be rewritten as:

               recurse { print } "/";


       Context

       There is an optional third parameter which can be any scalar value
       (including a reference). This value is ignored by recurse, but will be
       passed as the second parameter to the user-defined function. This can
       be useful for building library routines that use recurse, so that they
       do not have to pass state to the function as global variables.

       Controling Recursion

       If you want to control how recursion happens, you have several options.
       First, there are some global variables that affect the overall
       operation of the recurse routine:

       $MAX_DEPTH
            This variable controls how far down a tree of directories recurse
            will go before it assumes that something bad has happened.
            Default: 100.

       $FOLLOW_SYMLINKS
            This variable tells recurse if it should descend into directories
            that are symbolic links. Default: 0.

       Normally, the return value of the function called is not used, but if
       it is -1 or -2, there is a special action taken.

       If the function returns -1 and the current filename refers to a
       directory, recurse will not descend into that directory. This can be
       used to prune searches and focus only on those directories which should
       be followed.

       If the function returns -2, the search is terminated, and recurse will
       return. This can be used to bail when a problem occurs, and you don't
       want to exit the program, or to end the search for some file once it is
       found.

SEE ALSO
       the File::Tools manpage

AUTHOR
       Written in 1996 by Aaron Sherman, ajs@ajs.com














3rd Berkeley Distribution    perl 5.005, patch 03                   Recurse(3)