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 glob 33 ) ], 34); 35$EXPORT_TAGS{bsd_glob} = [@{$EXPORT_TAGS{glob}}]; 36pop @{$EXPORT_TAGS{bsd_glob}}; # no "glob" 37 38@EXPORT_OK = (@{$EXPORT_TAGS{'glob'}}, 'csh_glob'); 39 40$VERSION = '1.23'; 41 42sub 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 68XSLoader::load(); 69 70$DEFAULT_FLAGS = GLOB_CSH(); 71if ($^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) 77sub glob { 78 splice @_, 1; # no flags 79 goto &bsd_glob; 80} 81 821; 83__END__ 84 85=head1 NAME 86 87File::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 119The glob angle-bracket operator C<< <> >> is a pathname generator that 120implements the rules for file name pattern matching used by Unix-like shells 121such as the Bourne shell or C shell. 122 123File::Glob::bsd_glob() implements the FreeBSD glob(3) routine, which is 124a superset of the POSIX glob() (described in IEEE Std 1003.2 "POSIX.2"). 125bsd_glob() takes a mandatory C<pattern> argument, and an optional 126C<flags> argument, and returns a list of filenames matching the 127pattern, with interpretation of the pattern modified by the C<flags> 128variable. 129 130Since v5.6.0, Perl's CORE::glob() is implemented in terms of bsd_glob(). 131Note that they don't share the same prototype--CORE::glob() only accepts 132a single argument. Due to historical reasons, CORE::glob() will also 133split its argument on whitespace, treating it as multiple patterns, 134whereas bsd_glob() considers them as one pattern. But see C<:bsd_glob> 135under 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 146The metanotation C<a{b,c,d}e> is a shorthand for C<abe ace ade>. Left to 147right order is preserved, with results of matches being sorted separately 148at a low level to preserve this order. As a special case C<{>, C<}>, and 149C<{}> are passed undisturbed. 150 151=head2 EXPORTS 152 153See also the L</POSIX FLAGS> below, which can be exported individually. 154 155=head3 C<:bsd_glob> 156 157The C<:bsd_glob> export tag exports bsd_glob() and the constants listed 158below. It also overrides glob() in the calling package with one that 159behaves like bsd_glob() with regard to spaces (the space is treated as part 160of a file name), but supports iteration in scalar context; i.e., it 161preserves the core function's feature of returning the next item each time 162it is called. 163 164=head3 C<:glob> 165 166The C<:glob> tag, now discouraged, is the old version of C<:bsd_glob>. It 167exports the same constants and functions, but its glob() override does not 168support iteration; it returns the last file name in scalar context. That 169means 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 178This function, which is included in the two export tags listed above, 179takes one or two arguments. The first is the glob pattern. The second is 180a set of flags ORed together. The available flags are listed below under 181L</POSIX FLAGS>. If the second argument is omitted, C<GLOB_CSH> (or 182C<GLOB_CSH|GLOB_NOCASE> on VMS and DOSish systems) is used by default. 183 184=head3 C<:nocase> and C<:case> 185 186These two export tags globally modify the default flags that bsd_glob() 187and, except on VMS, Perl's built-in C<glob> operator use. C<GLOB_NOCASE> 188is turned on or off, respectively. 189 190=head3 C<csh_glob> 191 192The csh_glob() function can also be exported, but you should not use it 193directly unless you really know what you are doing. It splits the pattern 194into words and feeds each one to bsd_glob(). Perl's own glob() function 195uses this internally. 196 197=head2 POSIX FLAGS 198 199The POSIX defined flags for bsd_glob() are: 200 201=over 4 202 203=item C<GLOB_ERR> 204 205Force bsd_glob() to return an error when it encounters a directory it 206cannot open or read. Ordinarily bsd_glob() continues to find matches. 207 208=item C<GLOB_LIMIT> 209 210Make bsd_glob() return an error (GLOB_NOSPACE) when the pattern expands 211to a size bigger than the system constant C<ARG_MAX> (usually found in 212limits.h). If your system does not define this constant, bsd_glob() uses 213C<sysconf(_SC_ARG_MAX)> or C<_POSIX_ARG_MAX> where available (in that 214order). You can inspect these values using the standard C<POSIX> 215extension. 216 217=item C<GLOB_MARK> 218 219Each pathname that is a directory that matches the pattern has a slash 220appended. 221 222=item C<GLOB_NOCASE> 223 224By default, file names are assumed to be case sensitive; this flag 225makes bsd_glob() treat case differences as not significant. 226 227=item C<GLOB_NOCHECK> 228 229If the pattern does not match any pathname, then bsd_glob() returns a list 230consisting of only the pattern. If C<GLOB_QUOTE> is set, its effect 231is present in the pattern returned. 232 233=item C<GLOB_NOSORT> 234 235By default, the pathnames are sorted in ascending ASCII order; this 236flag prevents that sorting (speeding up bsd_glob()). 237 238=back 239 240The FreeBSD extensions to the POSIX standard are the following flags: 241 242=over 4 243 244=item C<GLOB_BRACE> 245 246Pre-process the string to expand C<{pat,pat,...}> strings like csh(1). 247The pattern '{}' is left unexpanded for historical reasons (and csh(1) 248does the same thing to ease typing of find(1) patterns). 249 250=item C<GLOB_NOMAGIC> 251 252Same as C<GLOB_NOCHECK> but it only returns the pattern if it does not 253contain any of the special characters "*", "?" or "[". C<NOMAGIC> is 254provided to simplify implementing the historic csh(1) globbing 255behaviour and should probably not be used anywhere else. 256 257=item C<GLOB_QUOTE> 258 259Use the backslash ('\') character for quoting: every occurrence of a 260backslash followed by a character in the pattern is replaced by that 261character, avoiding any special interpretation of the character. 262(But see below for exceptions on DOSISH systems). 263 264=item C<GLOB_TILDE> 265 266Expand patterns that start with '~' to user name home directories. 267 268=item C<GLOB_CSH> 269 270For convenience, C<GLOB_CSH> is a synonym for 271C<GLOB_BRACE | GLOB_NOMAGIC | GLOB_QUOTE | GLOB_TILDE | GLOB_ALPHASORT>. 272 273=back 274 275The POSIX provided C<GLOB_APPEND>, C<GLOB_DOOFFS>, and the FreeBSD 276extensions C<GLOB_ALTDIRFUNC>, and C<GLOB_MAGCHAR> flags have not been 277implemented in the Perl version because they involve more complex 278interaction with the underlying C structures. 279 280The following flag has been added in the Perl implementation for 281csh compatibility: 282 283=over 4 284 285=item C<GLOB_ALPHASORT> 286 287If C<GLOB_NOSORT> is not in effect, sort filenames is alphabetical 288order (case does not matter) rather than in ASCII order. 289 290=back 291 292=head1 DIAGNOSTICS 293 294bsd_glob() returns a list of matching paths, possibly zero length. If an 295error occurred, &File::Glob::GLOB_ERROR will be non-zero and C<$!> will be 296set. &File::Glob::GLOB_ERROR is guaranteed to be zero if no error occurred, 297or one of the following values otherwise: 298 299=over 4 300 301=item C<GLOB_NOSPACE> 302 303An attempt to allocate memory failed. 304 305=item C<GLOB_ABEND> 306 307The glob was stopped because an error was encountered. 308 309=back 310 311In the case where bsd_glob() has found some matching paths, but is 312interrupted by an error, it will return a list of filenames B<and> 313set &File::Glob::ERROR. 314 315Note that bsd_glob() deviates from POSIX and FreeBSD glob(3) behaviour 316by not considering C<ENOENT> and C<ENOTDIR> as errors - bsd_glob() will 317continue processing despite those errors, unless the C<GLOB_ERR> flag is 318set. 319 320Be aware that all filenames returned from File::Glob are tainted. 321 322=head1 NOTES 323 324=over 4 325 326=item * 327 328If you want to use multiple patterns, e.g. C<bsd_glob("a* b*")>, you should 329probably throw them in a set as in C<bsd_glob("{a*,b*}")>. This is because 330the argument to bsd_glob() isn't subjected to parsing by the C shell. 331Remember that you can use a backslash to escape things. 332 333=item * 334 335On DOSISH systems, backslash is a valid directory separator character. 336In this case, use of backslash as a quoting character (via GLOB_QUOTE) 337interferes with the use of backslash as a directory separator. The 338best (simplest, most portable) solution is to use forward slashes for 339directory separators, and backslashes for quoting. However, this does 340not match "normal practice" on these systems. As a concession to user 341expectation, therefore, backslashes (under GLOB_QUOTE) only quote the 342glob metacharacters '[', ']', '{', '}', '-', '~', and backslash itself. 343All other backslashes are passed through unchanged. 344 345=item * 346 347Win32 users should use the real slash. If you really want to use 348backslashes, consider using Sarathy's File::DosGlob, which comes with 349the standard Perl distribution. 350 351=back 352 353=head1 SEE ALSO 354 355L<perlfunc/glob>, glob(3) 356 357=head1 AUTHOR 358 359The Perl interface was written by Nathan Torkington E<lt>gnat@frii.comE<gt>, 360and is released under the artistic license. Further modifications were 361made by Greg Bacon E<lt>gbacon@cs.uah.eduE<gt>, Gurusamy Sarathy 362E<lt>gsar@activestate.comE<gt>, and Thomas Wegner 363E<lt>wegner_thomas@yahoo.comE<gt>. The C glob code has the 364following 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 398