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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.