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).

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.o','src/$1.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:

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'. 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. =item * follow: if given a true value indicates that symbolic links are to be followed. (TODO)

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 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.

cpanm File::Wildcard

perl -MCPAN -e shell
install File::Wildcard