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.

The module also takes regular expressions in any part of the wildcard string between slashes, and can bind 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",
               derive => ["src/$1/$2.o","src/$1/$2.hpp"]);

This is the constructor for File::Wildcard objects. At a simple level, pass a single wildcard string. For more complicated operations, you can 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:

next

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

The next method is an iterator, which returns successive files. Scalar context can be used in the case of a simple find. If more than one spec was passed to new, these files are constructed and returned as a list. There is no check that these files actually 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 changing the contents of the directories you are scanning, you are better off slurping the whole tree with all.

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.

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.

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.

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

SUPPORT

This is an Alpha release. Also note that I am supporting it in my unpaid spare time.

AUTHOR

        Ivor Williams
        ivorw-file-wildcard@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.