Provided by: libfile-wildcard-perl_0.11-4_all bug

NAME

       File::Wildcard - Enhanced glob processing

SYNOPSIS

         use File::Wildcard;
         my $foo = File::Wildcard->new(path => "/home/me///core");
         while (my $file = $foo->next) {
            unlink $file;
         }

DESCRIPTION

       When looking at how various operating systems do filename wildcard expansion (globbing),
       VMS has a nice syntax which allows expansion and searching of whole directory trees. It
       would be nice if other operating systems had something like this built in. The best Unix
       can manage is through the utility program "find".

       This module provides this facility to Perl. Whereas native VMS syntax uses the ellipsis
       "...", this will not fit in with POSIX filenames, as ... is a valid (though somewhat
       strange) filename. Instead, the construct "///" is used as this cannot syntactically be
       part of a filename, as you do not get three concurrent filename separators with nothing
       between (three slashes are used to avoid confusion with //node/path/name syntax).

       You don't have to use this syntax, as you can do the splitting yourself and pass in an
       arrayref as your path.

       The module also forms a regular expression for the whole of the wildcard string, and binds
       a series of back references ($1, $2 etc.) which are available to construct new filenames.

   new
       "File::Wildcard-"new( $wildcard, [,option => value,...]);>

         my $foo = File::Wildcard->new( path => "/home/me///core");
         my $srcfnd = File::Wildcard->new( path => "src///*.cpp",
                      match => qr(^src/(.*?)\.cpp$),
                      derive => ['src/$1.o','src/$1.hpp']);

       This is the constructor for File::Wildcard objects. At a simple level, pass a single
       wildcard string as a path.

       For more complicated operations, you can supply your own match regexp, or use the derive
       option to specify regular expression captures to form the basis of other filenames that
       are constructed for you.

       The $srcfnd example gives you object files and header files corresponding to C++ source
       files.

       Here are the options that are available:

       "path"
           This is the input parameter that specifies the range of files that will be looked at.
           This is a glob spec which can also contain the ellipsis '///' (it could contain more
           than one ellipsis, but the benefit of this is questionable, and multiple ellipsi would
           cause a performance hit).

           Note that the path can be relative or absolute. new will do the right thing, working
           out that a path starting with '/' is absolute. In order to recurse from the current
           directory downwards, specify './//foo'.

           As an alternative, you can supply an arrayref with the path constituents already
           split. If you do this, you need to tell new if the path is absolute.  Include an empty
           string for an ellipsis. For example:

             'foo///bar/*.c' is equivalent to ['foo','','bar','*.c']

           You can also construct a File::Wildcard without a path. A call to next will return
           undef, but paths can be added using the append and prepend methods.

       "absolute"
           This is ignored unless you are using a pre split path. If you are passing a string as
           the path, new will work out whether the path is absolute or relative. Pass a true
           value for absolute paths.

           If your original filespec started with '/' before you split it, specify absolute => 1.
           absolute is not required for Windows if the path contains a drive specification, e.g.
           C:/foo/bar.

       "case_insensitive"
           By default, the module will use Filesys::Type to determine whether the file system of
           your wildcard is defined. This is an optional module (see Module::Optional), and
           File::Wildcard will guess at case sensitivity based on your operating system. This
           will not always be correct, as the file system might be VFAT mounted on Linux or ODS-5
           on VMS.

           Specifying the option "case_insensitive" explicitly forces this behaviour on the
           wildcard.

           Note that File::Wildcard will use the file system of the current working directory if
           the path is not absolute. If the path is absolute, you should specify the
           case_sensitivity option explicitly.

       "exclude"
           You can provide a regexp to apply to any generated paths, which will cause any
           matching paths not to be processed. If the root of a directory tree matches, no
           processing is done on the entire tree.

           This option can be useful for excluding version control repositories, e.g.

             exclude => qr/.svn/

       "match"
           Optional. If you do not specify a regexp, you get all the files that match the glob;
           in addition, new will set up a regexp for you, to provide a capture for each wildcard
           used in the path.

           If you do provide a match parameter, this will be used instead, and will filter the
           results.

       "derive"
           Supply an arrayref with a list of derived filenames, which will be constructed for
           each matching file. This causes next to return an arrayref instead of a scalar.

       "follow"
           If given a true value indicates that symbolic links are to be followed. Otherwise, the
           symbolic link target itself is presented, but the ellipsis will not traverse the link.

           This module detects a looping symlink that points to a directory higher up, and will
           only present the tree once.

       "ellipsis_order"
           This can take one of the following values: normal, breadth-first, inside-out.  The
           default option is normal. This controls how File::Wildcard handles the ellipsis. The
           default is a normal depth first search, presenting the name of each containing
           directory before the contents.

           The inside-out order presents the contents of directories first before the directory,
           which is useful when you want to remove files and directories (all O/S require
           directories to be empty before rmdir will work). See t/03_absolute.t as this uses
           inside-out order to tidy up after the test.

           Breadth-first is rarely needed (but I do have an application for it). Here, the whole
           directory contents is presented before traversing any subdirectories.

           Consider the following tree:
              a/
              a/bar/
              a/bar/drink
              a/foo/
              a/foo/lish

           breadth-first will give the following order: qw(a/ a/bar/ a/foo/ a/bar/drink
           a/foo/lish). normal gives the order in which the files are listed.  inside-out gives
           the following: qw(a/bar/drink a/bar/ a/foo/lish a/foo/ a/).

       "sort"
           By default, globbing returns the list of files in the order in which they are returned
           by the dirhandle (internally). If you specify sort => 1, the files are sorted into
           ASCII sequence (case insensitively if we are operating that way). If you specify a
           CODEREF, this will be used as a comparison routine. Note that this takes its operands
           in @_, not in $a and $b.

       "debug" and "debug_output"
           You can enable a trace of the internal states of File::Wildcard by setting debug to a
           true value. Set debug_output to an open filehandle to get the trace in a file. If you
           are submitting bug reports for File::Wildcard, attaching debug trace files would be
           very useful.

           debug_output defaults to STDERR.

   match
         my $foo_re = $foo->match;
         $foo->match('bar/core');

       This is a get and set method that gives access to the match regexp that the File::Wildcard
       object is using. It is possible to change the regex on the fly in the middle of a search
       (though I don't know why anyone would want to do this).

   append
         $foo->append(path => '/home/me///*.tmp');

       appends a path to an object's todo list. This will be globbed after the object has
       finished processing the existing wildcards.

   prepend
         $srcfnd->prepend(path => $include_file);

       This is similar to append, but prepends the path to the todo list. In other words, the
       current wildcard operation is interrupted to serve the new path, then the previous
       wildcard operation is resumed when this is exhausted.

   next
         while (my $core = $foo->next) {
             unlink $core;
         }
         my ($src,$obj,$hdr) = @{$srcfnd->next};

       The "next" method is an iterator, which returns successive files. Returns matching files
       if there was no derive option passed to new. If there was a derive option, returns an
       arrayref containing the matching filespec and all derived filespecs. The derived filespecs
       do not have to exist.

       Note that "next" maintains an internal cursor, which retains context and state
       information. Beware if the contents of directories are changing while you are iterating
       with next; you may get unpredictable results. If you are intending to change the contents
       of the directories you are scanning (with unlink or rename), you are better off deferring
       this operation until you have processed the whole tree. For the pending delete or rename
       operations, you could always use another File::Wildcard object - see the spike example
       below:

   all
         my @cores = $foo->all;

       "all" returns an array of matching files, in the simple case. Returns an array of arrays
       if you are constructing new filenames, like the $srcfnd example.

       Beware of the performance and memory implications of using "all". The method will not
       return until it has read the entire directory tree. Use of the "all" method is not
       recommended for traversing large directory trees and whole file systems. Consider coding
       the traversal using the iterator "next" instead.

   reset
       "reset" causes the wildcard context to be set to re-read the first filename again. Note
       that this will cause directory contents to be re-read.

       Note also that this will cause the path to revert to the original path specified to new.
       Any additional paths appended or prepended will be forgotten.

   close
       Release all directory handles associated with the File::Wildcard object.  An object that
       has been closed will be garbage collected once it goes out of scope. Wildcards that have
       been exhausted are automatically closed, (i.e. "all" was used, or c<next> returned undef).

       Subsequent calls to "next" will return undef. It is possible to call "reset" after "close"
       on the same File::Wildcard object, which will cause it to be reopened.

EXAMPLES

The spike

             my $todo = File::Wildcard->new;

             ...

             $todo->append(path => $file);

             ...

             while (my $file = $todo->next) {
             ...
             }

           You can use an empty wildcard to store a list of filenames for later processing. The
           order in which they will be seen depends on whether append or prepend is used.

       •   Shell style globbing

             my $wc_args = File::Wildcard->new;

             $wc_args->append(path => $_) for @ARGV;

             while ($wc_args->next) {
             ...
             }

           On Unix, file wildcards on the command line are globbed by the shell before perl sees
           them, unless the wildcards are escaped or quoted. This is not true of other operating
           systems. MS-DOS does no globbing at all for example.

           File::Wildcard gives you the bonus of elliptic globbing with '///'.

CAVEAT

       This module takes POSIX filenames, which use forward slash '/' as a path separator. All
       operating systems that run Perl can manage this type of path. The module is not designed
       to work with native file specs.  If you want to write code that is portable, convert
       native filespecs to the POSIX form. There is of course no difference on Unix platforms.

BUGS

       Please report bugs to http://rt.cpan.org

AUTHOR

               Ivor Williams
               ivorw-file-wildcard010 at xemaps.com

COPYRIGHT

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

       The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

       glob(3), File::Find, File::Find::Rule.