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