ext/File-Glob/Glob.pm

   1 package File::Glob;
   2
   3 use strict;
   4 our($VERSION, @ISA, @EXPORT_OK, @EXPORT_FAIL, %EXPORT_TAGS, $DEFAULT_FLAGS);
   5
   6 require XSLoader;
   7
   8 @ISA = qw(Exporter);
   9
  10 # NOTE: The glob() export is only here for compatibility with 5.6.0.
  11 # csh_glob() should not be used directly, unless you know what you're doing.
  12
  13 %EXPORT_TAGS = (
  14     'glob' => [ qw(
  15         GLOB_ABEND
  16         GLOB_ALPHASORT
  17         GLOB_ALTDIRFUNC
  18         GLOB_BRACE
  19         GLOB_CSH
  20         GLOB_ERR
  21         GLOB_ERROR
  22         GLOB_LIMIT
  23         GLOB_MARK
  24         GLOB_NOCASE
  25         GLOB_NOCHECK
  26         GLOB_NOMAGIC
  27         GLOB_NOSORT
  28         GLOB_NOSPACE
  29         GLOB_QUOTE
  30         GLOB_TILDE
  31         bsd_glob
  32         glob
  33     ) ],
  34 );
  35 $EXPORT_TAGS{bsd_glob} = [@{$EXPORT_TAGS{glob}}];
  36 pop @{$EXPORT_TAGS{bsd_glob}}; # no "glob"
  37
  38 @EXPORT_OK   = (@{$EXPORT_TAGS{'glob'}}, 'csh_glob');
  39
  40 $VERSION = '1.20';
  41
  42 sub import {
  43     require Exporter;
  44     local $Exporter::ExportLevel = $Exporter::ExportLevel + 1;
  45     Exporter::import(grep {
  46         my $passthrough;
  47         if ($_ eq ':case') {
  48             $DEFAULT_FLAGS &= ~GLOB_NOCASE()
  49         }
  50         elsif ($_ eq ':nocase') {
  51             $DEFAULT_FLAGS |= GLOB_NOCASE();
  52         }
  53         elsif ($_ eq ':globally') {
  54             no warnings 'redefine';
  55             *CORE::GLOBAL::glob = \&File::Glob::csh_glob;
  56         }
  57         elsif ($_ eq ':bsd_glob') {
  58             no strict; *{caller."::glob"} = \&bsd_glob_override;
  59             $passthrough = 1;
  60         }
  61         else {
  62             $passthrough = 1;
  63         }
  64         $passthrough;
  65     } @_);
  66 }
  67
  68 XSLoader::load();
  69
  70 $DEFAULT_FLAGS = GLOB_CSH();
  71 if ($^O =~ /^(?:MSWin32|VMS|os2|dos|riscos)$/) {
  72     $DEFAULT_FLAGS |= GLOB_NOCASE();
  73 }
  74
  75 # File::Glob::glob() is deprecated because its prototype is different from
  76 # CORE::glob() (use bsd_glob() instead)
  77 sub glob {
  78     splice @_, 1; # no flags
  79     goto &bsd_glob;
  80 }
  81
  82 1;
  83 __END__
  84
  85 =head1 NAME
  86
  87 File::Glob - Perl extension for BSD glob routine
  88
  89 =head1 SYNOPSIS
  90
  91   use File::Glob ':bsd_glob';
  92
  93   @list = bsd_glob('*.[ch]');
  94   $homedir = bsd_glob('~gnat', GLOB_TILDE | GLOB_ERR);
  95
  96   if (GLOB_ERROR) {
  97     # an error occurred reading $homedir
  98   }
  99
 100   ## override the core glob (CORE::glob() does this automatically
 101   ## by default anyway, since v5.6.0)
 102   use File::Glob ':globally';
 103   my @sources = <*.{c,h,y}>;
 104
 105   ## override the core glob, forcing case sensitivity
 106   use File::Glob qw(:globally :case);
 107   my @sources = <*.{c,h,y}>;
 108
 109   ## override the core glob forcing case insensitivity
 110   use File::Glob qw(:globally :nocase);
 111   my @sources = <*.{c,h,y}>;
 112
 113   ## glob on all files in home directory
 114   use File::Glob ':globally';
 115   my @sources = <~gnat/*>;
 116
 117 =head1 DESCRIPTION
 118
 119 The glob angle-bracket operator C<< <> >> is a pathname generator that
 120 implements the rules for file name pattern matching used by Unix-like shells
 121 such as the Bourne shell or C shell.
 122
 123 File::Glob::bsd_glob() implements the FreeBSD glob(3) routine, which is
 124 a superset of the POSIX glob() (described in IEEE Std 1003.2 "POSIX.2").
 125 bsd_glob() takes a mandatory C<pattern> argument, and an optional
 126 C<flags> argument, and returns a list of filenames matching the
 127 pattern, with interpretation of the pattern modified by the C<flags>
 128 variable.
 129
 130 Since v5.6.0, Perl's CORE::glob() is implemented in terms of bsd_glob().
 131 Note that they don't share the same prototype--CORE::glob() only accepts
 132 a single argument.  Due to historical reasons, CORE::glob() will also
 133 split its argument on whitespace, treating it as multiple patterns,
 134 whereas bsd_glob() considers them as one pattern.  But see C<:bsd_glob>
 135 under L</EXPORTS>, below.
 136
 137 =head2 META CHARACTERS
 138
 139   \       Quote the next metacharacter
 140   []      Character class
 141   {}      Multiple pattern
 142   *       Match any string of characters
 143   ?       Match any single character
 144   ~       User name home directory
 145
 146 The metanotation C<a{b,c,d}e> is a shorthand for C<abe ace ade>.  Left to
 147 right order is preserved, with results of matches being sorted separately
 148 at a low level to preserve this order.  As a special case C<{>, C<}>, and
 149 C<{}> are passed undisturbed.
 150
 151 =head2 EXPORTS
 152
 153 See also the L</POSIX FLAGS> below, which can be exported individually.
 154
 155 =head3 C<:bsd_glob>
 156
 157 The C<:bsd_glob> export tag exports bsd_glob() and the constants listed
 158 below.  It also overrides glob() in the calling package with one that
 159 behaves like bsd_glob() with regard to spaces (the space is treated as part
 160 of a file name), but supports iteration in scalar context; i.e., it
 161 preserves the core function's feature of returning the next item each time
 162 it is called.
 163
 164 =head3 C<:glob>
 165
 166 The C<:glob> tag, now discouraged, is the old version of C<:bsd_glob>.  It
 167 exports the same constants and functions, but its glob() override does not
 168 support iteration; it returns the last file name in scalar context.  That
 169 means this will loop forever:
 170
 171     use File::Glob ':glob';
 172     while (my $file = <* copy.txt>) {
 173         ...
 174     }
 175
 176 =head3 C<bsd_glob>
 177
 178 This function, which is included in the two export tags listed above,
 179 takes one or two arguments.  The first is the glob pattern.  The second is
 180 a set of flags ORed together.  The available flags are listed below under
 181 L</POSIX FLAGS>.  If the second argument is omitted, C<GLOB_CSH> (or
 182 C<GLOB_CSH|GLOB_NOCASE> on VMS and DOSish systems) is used by default.
 183
 184 =head3 C<:nocase> and C<:case>
 185
 186 These two export tags globally modify the default flags that bsd_glob()
 187 and, except on VMS, Perl's built-in C<glob> operator use.  C<GLOB_NOCASE>
 188 is turned on or off, respectively.
 189
 190 =head3 C<csh_glob>
 191
 192 The csh_glob() function can also be exported, but you should not use it
 193 directly unless you really know what you are doing.  It splits the pattern
 194 into words and feeds each one to bsd_glob().  Perl's own glob() function
 195 uses this internally.
 196
 197 =head2 POSIX FLAGS
 198
 199 The POSIX defined flags for bsd_glob() are:
 200
 201 =over 4
 202
 203 =item C<GLOB_ERR>
 204
 205 Force bsd_glob() to return an error when it encounters a directory it
 206 cannot open or read.  Ordinarily bsd_glob() continues to find matches.
 207
 208 =item C<GLOB_LIMIT>
 209
 210 Make bsd_glob() return an error (GLOB_NOSPACE) when the pattern expands
 211 to a size bigger than the system constant C<ARG_MAX> (usually found in
 212 limits.h).  If your system does not define this constant, bsd_glob() uses
 213 C<sysconf(_SC_ARG_MAX)> or C<_POSIX_ARG_MAX> where available (in that
 214 order).  You can inspect these values using the standard C<POSIX>
 215 extension.
 216
 217 =item C<GLOB_MARK>
 218
 219 Each pathname that is a directory that matches the pattern has a slash
 220 appended.
 221
 222 =item C<GLOB_NOCASE>
 223
 224 By default, file names are assumed to be case sensitive; this flag
 225 makes bsd_glob() treat case differences as not significant.
 226
 227 =item C<GLOB_NOCHECK>
 228
 229 If the pattern does not match any pathname, then bsd_glob() returns a list
 230 consisting of only the pattern.  If C<GLOB_QUOTE> is set, its effect
 231 is present in the pattern returned.
 232
 233 =item C<GLOB_NOSORT>
 234
 235 By default, the pathnames are sorted in ascending ASCII order; this
 236 flag prevents that sorting (speeding up bsd_glob()).
 237
 238 =back
 239
 240 The FreeBSD extensions to the POSIX standard are the following flags:
 241
 242 =over 4
 243
 244 =item C<GLOB_BRACE>
 245
 246 Pre-process the string to expand C<{pat,pat,...}> strings like csh(1).
 247 The pattern '{}' is left unexpanded for historical reasons (and csh(1)
 248 does the same thing to ease typing of find(1) patterns).
 249
 250 =item C<GLOB_NOMAGIC>
 251
 252 Same as C<GLOB_NOCHECK> but it only returns the pattern if it does not
 253 contain any of the special characters "*", "?" or "[".  C<NOMAGIC> is
 254 provided to simplify implementing the historic csh(1) globbing
 255 behaviour and should probably not be used anywhere else.
 256
 257 =item C<GLOB_QUOTE>
 258
 259 Use the backslash ('\') character for quoting: every occurrence of a
 260 backslash followed by a character in the pattern is replaced by that
 261 character, avoiding any special interpretation of the character.
 262 (But see below for exceptions on DOSISH systems).
 263
 264 =item C<GLOB_TILDE>
 265
 266 Expand patterns that start with '~' to user name home directories.
 267
 268 =item C<GLOB_CSH>
 269
 270 For convenience, C<GLOB_CSH> is a synonym for
 271 C<GLOB_BRACE | GLOB_NOMAGIC | GLOB_QUOTE | GLOB_TILDE | GLOB_ALPHASORT>.
 272
 273 =back
 274
 275 The POSIX provided C<GLOB_APPEND>, C<GLOB_DOOFFS>, and the FreeBSD
 276 extensions C<GLOB_ALTDIRFUNC>, and C<GLOB_MAGCHAR> flags have not been
 277 implemented in the Perl version because they involve more complex
 278 interaction with the underlying C structures.
 279
 280 The following flag has been added in the Perl implementation for
 281 csh compatibility:
 282
 283 =over 4
 284
 285 =item C<GLOB_ALPHASORT>
 286
 287 If C<GLOB_NOSORT> is not in effect, sort filenames is alphabetical
 288 order (case does not matter) rather than in ASCII order.
 289
 290 =back
 291
 292 =head1 DIAGNOSTICS
 293
 294 bsd_glob() returns a list of matching paths, possibly zero length.  If an
 295 error occurred, &File::Glob::GLOB_ERROR will be non-zero and C<$!> will be
 296 set.  &File::Glob::GLOB_ERROR is guaranteed to be zero if no error occurred,
 297 or one of the following values otherwise:
 298
 299 =over 4
 300
 301 =item C<GLOB_NOSPACE>
 302
 303 An attempt to allocate memory failed.
 304
 305 =item C<GLOB_ABEND>
 306
 307 The glob was stopped because an error was encountered.
 308
 309 =back
 310
 311 In the case where bsd_glob() has found some matching paths, but is
 312 interrupted by an error, it will return a list of filenames B<and>
 313 set &File::Glob::ERROR.
 314
 315 Note that bsd_glob() deviates from POSIX and FreeBSD glob(3) behaviour
 316 by not considering C<ENOENT> and C<ENOTDIR> as errors - bsd_glob() will
 317 continue processing despite those errors, unless the C<GLOB_ERR> flag is
 318 set.
 319
 320 Be aware that all filenames returned from File::Glob are tainted.
 321
 322 =head1 NOTES
 323
 324 =over 4
 325
 326 =item *
 327
 328 If you want to use multiple patterns, e.g. C<bsd_glob("a* b*")>, you should
 329 probably throw them in a set as in C<bsd_glob("{a*,b*}")>.  This is because
 330 the argument to bsd_glob() isn't subjected to parsing by the C shell.
 331 Remember that you can use a backslash to escape things.
 332
 333 =item *
 334
 335 On DOSISH systems, backslash is a valid directory separator character.
 336 In this case, use of backslash as a quoting character (via GLOB_QUOTE)
 337 interferes with the use of backslash as a directory separator.  The
 338 best (simplest, most portable) solution is to use forward slashes for
 339 directory separators, and backslashes for quoting.  However, this does
 340 not match "normal practice" on these systems.  As a concession to user
 341 expectation, therefore, backslashes (under GLOB_QUOTE) only quote the
 342 glob metacharacters '[', ']', '{', '}', '-', '~', and backslash itself.
 343 All other backslashes are passed through unchanged.
 344
 345 =item *
 346
 347 Win32 users should use the real slash.  If you really want to use
 348 backslashes, consider using Sarathy's File::DosGlob, which comes with
 349 the standard Perl distribution.
 350
 351 =back
 352
 353 =head1 SEE ALSO
 354
 355 L<perlfunc/glob>, glob(3)
 356
 357 =head1 AUTHOR
 358
 359 The Perl interface was written by Nathan Torkington E<lt>gnat@frii.comE<gt>,
 360 and is released under the artistic license.  Further modifications were
 361 made by Greg Bacon E<lt>gbacon@cs.uah.eduE<gt>, Gurusamy Sarathy
 362 E<lt>gsar@activestate.comE<gt>, and Thomas Wegner
 363 E<lt>wegner_thomas@yahoo.comE<gt>.  The C glob code has the
 364 following copyright:
 365
 366     Copyright (c) 1989, 1993 The Regents of the University of California.
 367     All rights reserved.
 368
 369     This code is derived from software contributed to Berkeley by
 370     Guido van Rossum.
 371
 372     Redistribution and use in source and binary forms, with or without
 373     modification, are permitted provided that the following conditions
 374     are met:
 375
 376     1. Redistributions of source code must retain the above copyright
 377        notice, this list of conditions and the following disclaimer.
 378     2. Redistributions in binary form must reproduce the above copyright
 379        notice, this list of conditions and the following disclaimer in the
 380        documentation and/or other materials provided with the distribution.
 381     3. Neither the name of the University nor the names of its contributors
 382        may be used to endorse or promote products derived from this software
 383        without specific prior written permission.
 384
 385     THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND
 386     ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 387     IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 388     ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
 389     FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 390     DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 391     OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 392     HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 393     LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 394     OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 395     SUCH DAMAGE.
 396
 397 =cut