1package File::Glob; 2 3use strict; 4our($VERSION, @ISA, @EXPORT_OK, @EXPORT_FAIL, %EXPORT_TAGS, 5 $AUTOLOAD, $DEFAULT_FLAGS); 6 7use XSLoader (); 8 9@ISA = qw(Exporter); 10 11# NOTE: The glob() export is only here for compatibility with 5.6.0. 12# csh_glob() should not be used directly, unless you know what you're doing. 13 14@EXPORT_OK = qw( 15 csh_glob 16 bsd_glob 17 glob 18 GLOB_ABEND 19 GLOB_ALPHASORT 20 GLOB_ALTDIRFUNC 21 GLOB_BRACE 22 GLOB_CSH 23 GLOB_ERR 24 GLOB_ERROR 25 GLOB_LIMIT 26 GLOB_MARK 27 GLOB_NOCASE 28 GLOB_NOCHECK 29 GLOB_NOMAGIC 30 GLOB_NOSORT 31 GLOB_NOSPACE 32 GLOB_QUOTE 33 GLOB_TILDE 34); 35 36%EXPORT_TAGS = ( 37 'glob' => [ qw( 38 GLOB_ABEND 39 GLOB_ALPHASORT 40 GLOB_ALTDIRFUNC 41 GLOB_BRACE 42 GLOB_CSH 43 GLOB_ERR 44 GLOB_ERROR 45 GLOB_LIMIT 46 GLOB_MARK 47 GLOB_NOCASE 48 GLOB_NOCHECK 49 GLOB_NOMAGIC 50 GLOB_NOSORT 51 GLOB_NOSPACE 52 GLOB_QUOTE 53 GLOB_TILDE 54 glob 55 bsd_glob 56 ) ], 57); 58 59$VERSION = '1.02'; 60 61sub import { 62 require Exporter; 63 my $i = 1; 64 while ($i < @_) { 65 if ($_[$i] =~ /^:(case|nocase|globally)$/) { 66 splice(@_, $i, 1); 67 $DEFAULT_FLAGS &= ~GLOB_NOCASE() if $1 eq 'case'; 68 $DEFAULT_FLAGS |= GLOB_NOCASE() if $1 eq 'nocase'; 69 if ($1 eq 'globally') { 70 local $^W; 71 *CORE::GLOBAL::glob = \&File::Glob::csh_glob; 72 } 73 next; 74 } 75 ++$i; 76 } 77 goto &Exporter::import; 78} 79 80sub AUTOLOAD { 81 # This AUTOLOAD is used to 'autoload' constants from the constant() 82 # XS function. If a constant is not found then control is passed 83 # to the AUTOLOAD in AutoLoader. 84 85 my $constname; 86 ($constname = $AUTOLOAD) =~ s/.*:://; 87 my ($error, $val) = constant($constname); 88 if ($error) { 89 require Carp; 90 Carp::croak($error); 91 } 92 eval "sub $AUTOLOAD { $val }"; 93 goto &$AUTOLOAD; 94} 95 96XSLoader::load 'File::Glob', $VERSION; 97 98# Preloaded methods go here. 99 100sub GLOB_ERROR { 101 return (constant('GLOB_ERROR'))[1]; 102} 103 104sub GLOB_CSH () { 105 GLOB_BRACE() 106 | GLOB_NOMAGIC() 107 | GLOB_QUOTE() 108 | GLOB_TILDE() 109 | GLOB_ALPHASORT() 110} 111 112$DEFAULT_FLAGS = GLOB_CSH(); 113if ($^O =~ /^(?:MSWin32|VMS|os2|dos|riscos|MacOS)$/) { 114 $DEFAULT_FLAGS |= GLOB_NOCASE(); 115} 116 117# Autoload methods go after =cut, and are processed by the autosplit program. 118 119sub bsd_glob { 120 my ($pat,$flags) = @_; 121 $flags = $DEFAULT_FLAGS if @_ < 2; 122 return doglob($pat,$flags); 123} 124 125# File::Glob::glob() is deprecated because its prototype is different from 126# CORE::glob() (use bsd_glob() instead) 127sub glob { 128 splice @_, 1; # don't pass PL_glob_index as flags! 129 goto &bsd_glob; 130} 131 132## borrowed heavily from gsar's File::DosGlob 133my %iter; 134my %entries; 135 136sub csh_glob { 137 my $pat = shift; 138 my $cxix = shift; 139 my @pat; 140 141 # glob without args defaults to $_ 142 $pat = $_ unless defined $pat; 143 144 # extract patterns 145 $pat =~ s/^\s+//; # Protect against empty elements in 146 $pat =~ s/\s+$//; # things like < *.c> and <*.c >. 147 # These alone shouldn't trigger ParseWords. 148 if ($pat =~ /\s/) { 149 # XXX this is needed for compatibility with the csh 150 # implementation in Perl. Need to support a flag 151 # to disable this behavior. 152 require Text::ParseWords; 153 @pat = Text::ParseWords::parse_line('\s+',0,$pat); 154 } 155 156 # assume global context if not provided one 157 $cxix = '_G_' unless defined $cxix; 158 $iter{$cxix} = 0 unless exists $iter{$cxix}; 159 160 # if we're just beginning, do it all first 161 if ($iter{$cxix} == 0) { 162 if (@pat) { 163 $entries{$cxix} = [ map { doglob($_, $DEFAULT_FLAGS) } @pat ]; 164 } 165 else { 166 $entries{$cxix} = [ doglob($pat, $DEFAULT_FLAGS) ]; 167 } 168 } 169 170 # chuck it all out, quick or slow 171 if (wantarray) { 172 delete $iter{$cxix}; 173 return @{delete $entries{$cxix}}; 174 } 175 else { 176 if ($iter{$cxix} = scalar @{$entries{$cxix}}) { 177 return shift @{$entries{$cxix}}; 178 } 179 else { 180 # return undef for EOL 181 delete $iter{$cxix}; 182 delete $entries{$cxix}; 183 return undef; 184 } 185 } 186} 187 1881; 189__END__ 190 191=head1 NAME 192 193File::Glob - Perl extension for BSD glob routine 194 195=head1 SYNOPSIS 196 197 use File::Glob ':glob'; 198 @list = bsd_glob('*.[ch]'); 199 $homedir = bsd_glob('~gnat', GLOB_TILDE | GLOB_ERR); 200 if (GLOB_ERROR) { 201 # an error occurred reading $homedir 202 } 203 204 ## override the core glob (CORE::glob() does this automatically 205 ## by default anyway, since v5.6.0) 206 use File::Glob ':globally'; 207 my @sources = <*.{c,h,y}> 208 209 ## override the core glob, forcing case sensitivity 210 use File::Glob qw(:globally :case); 211 my @sources = <*.{c,h,y}> 212 213 ## override the core glob forcing case insensitivity 214 use File::Glob qw(:globally :nocase); 215 my @sources = <*.{c,h,y}> 216 217=head1 DESCRIPTION 218 219File::Glob::bsd_glob() implements the FreeBSD glob(3) routine, which is 220a superset of the POSIX glob() (described in IEEE Std 1003.2 "POSIX.2"). 221bsd_glob() takes a mandatory C<pattern> argument, and an optional 222C<flags> argument, and returns a list of filenames matching the 223pattern, with interpretation of the pattern modified by the C<flags> 224variable. 225 226Since v5.6.0, Perl's CORE::glob() is implemented in terms of bsd_glob(). 227Note that they don't share the same prototype--CORE::glob() only accepts 228a single argument. Due to historical reasons, CORE::glob() will also 229split its argument on whitespace, treating it as multiple patterns, 230whereas bsd_glob() considers them as one pattern. 231 232The POSIX defined flags for bsd_glob() are: 233 234=over 4 235 236=item C<GLOB_ERR> 237 238Force bsd_glob() to return an error when it encounters a directory it 239cannot open or read. Ordinarily bsd_glob() continues to find matches. 240 241=item C<GLOB_LIMIT> 242 243Make bsd_glob() return an error (GLOB_NOSPACE) when the pattern expands 244to a size bigger than the system constant C<ARG_MAX> (usually found in 245limits.h). If your system does not define this constant, bsd_glob() uses 246C<sysconf(_SC_ARG_MAX)> or C<_POSIX_ARG_MAX> where available (in that 247order). You can inspect these values using the standard C<POSIX> 248extension. 249 250=item C<GLOB_MARK> 251 252Each pathname that is a directory that matches the pattern has a slash 253appended. 254 255=item C<GLOB_NOCASE> 256 257By default, file names are assumed to be case sensitive; this flag 258makes bsd_glob() treat case differences as not significant. 259 260=item C<GLOB_NOCHECK> 261 262If the pattern does not match any pathname, then bsd_glob() returns a list 263consisting of only the pattern. If C<GLOB_QUOTE> is set, its effect 264is present in the pattern returned. 265 266=item C<GLOB_NOSORT> 267 268By default, the pathnames are sorted in ascending ASCII order; this 269flag prevents that sorting (speeding up bsd_glob()). 270 271=back 272 273The FreeBSD extensions to the POSIX standard are the following flags: 274 275=over 4 276 277=item C<GLOB_BRACE> 278 279Pre-process the string to expand C<{pat,pat,...}> strings like csh(1). 280The pattern '{}' is left unexpanded for historical reasons (and csh(1) 281does the same thing to ease typing of find(1) patterns). 282 283=item C<GLOB_NOMAGIC> 284 285Same as C<GLOB_NOCHECK> but it only returns the pattern if it does not 286contain any of the special characters "*", "?" or "[". C<NOMAGIC> is 287provided to simplify implementing the historic csh(1) globbing 288behaviour and should probably not be used anywhere else. 289 290=item C<GLOB_QUOTE> 291 292Use the backslash ('\') character for quoting: every occurrence of a 293backslash followed by a character in the pattern is replaced by that 294character, avoiding any special interpretation of the character. 295(But see below for exceptions on DOSISH systems). 296 297=item C<GLOB_TILDE> 298 299Expand patterns that start with '~' to user name home directories. 300 301=item C<GLOB_CSH> 302 303For convenience, C<GLOB_CSH> is a synonym for 304C<GLOB_BRACE | GLOB_NOMAGIC | GLOB_QUOTE | GLOB_TILDE | GLOB_ALPHASORT>. 305 306=back 307 308The POSIX provided C<GLOB_APPEND>, C<GLOB_DOOFFS>, and the FreeBSD 309extensions C<GLOB_ALTDIRFUNC>, and C<GLOB_MAGCHAR> flags have not been 310implemented in the Perl version because they involve more complex 311interaction with the underlying C structures. 312 313The following flag has been added in the Perl implementation for 314csh compatibility: 315 316=over 4 317 318=item C<GLOB_ALPHASORT> 319 320If C<GLOB_NOSORT> is not in effect, sort filenames is alphabetical 321order (case does not matter) rather than in ASCII order. 322 323=back 324 325=head1 DIAGNOSTICS 326 327bsd_glob() returns a list of matching paths, possibly zero length. If an 328error occurred, &File::Glob::GLOB_ERROR will be non-zero and C<$!> will be 329set. &File::Glob::GLOB_ERROR is guaranteed to be zero if no error occurred, 330or one of the following values otherwise: 331 332=over 4 333 334=item C<GLOB_NOSPACE> 335 336An attempt to allocate memory failed. 337 338=item C<GLOB_ABEND> 339 340The glob was stopped because an error was encountered. 341 342=back 343 344In the case where bsd_glob() has found some matching paths, but is 345interrupted by an error, it will return a list of filenames B<and> 346set &File::Glob::ERROR. 347 348Note that bsd_glob() deviates from POSIX and FreeBSD glob(3) behaviour 349by not considering C<ENOENT> and C<ENOTDIR> as errors - bsd_glob() will 350continue processing despite those errors, unless the C<GLOB_ERR> flag is 351set. 352 353Be aware that all filenames returned from File::Glob are tainted. 354 355=head1 NOTES 356 357=over 4 358 359=item * 360 361If you want to use multiple patterns, e.g. C<bsd_glob "a* b*">, you should 362probably throw them in a set as in C<bsd_glob "{a*,b*}">. This is because 363the argument to bsd_glob() isn't subjected to parsing by the C shell. 364Remember that you can use a backslash to escape things. 365 366=item * 367 368On DOSISH systems, backslash is a valid directory separator character. 369In this case, use of backslash as a quoting character (via GLOB_QUOTE) 370interferes with the use of backslash as a directory separator. The 371best (simplest, most portable) solution is to use forward slashes for 372directory separators, and backslashes for quoting. However, this does 373not match "normal practice" on these systems. As a concession to user 374expectation, therefore, backslashes (under GLOB_QUOTE) only quote the 375glob metacharacters '[', ']', '{', '}', '-', '~', and backslash itself. 376All other backslashes are passed through unchanged. 377 378=item * 379 380Win32 users should use the real slash. If you really want to use 381backslashes, consider using Sarathy's File::DosGlob, which comes with 382the standard Perl distribution. 383 384=item * 385 386Mac OS (Classic) users should note a few differences. Since 387Mac OS is not Unix, when the glob code encounters a tilde glob (e.g. 388~user) and the C<GLOB_TILDE> flag is used, it simply returns that 389pattern without doing any expansion. 390 391Glob on Mac OS is case-insensitive by default (if you don't use any 392flags). If you specify any flags at all and still want glob 393to be case-insensitive, you must include C<GLOB_NOCASE> in the flags. 394 395The path separator is ':' (aka colon), not '/' (aka slash). Mac OS users 396should be careful about specifying relative pathnames. While a full path 397always begins with a volume name, a relative pathname should always 398begin with a ':'. If specifying a volume name only, a trailing ':' is 399required. 400 401The specification of pathnames in glob patterns adheres to the usual Mac 402OS conventions: The path separator is a colon ':', not a slash '/'. A 403full path always begins with a volume name. A relative pathname on Mac 404OS must always begin with a ':', except when specifying a file or 405directory name in the current working directory, where the leading colon 406is optional. If specifying a volume name only, a trailing ':' is 407required. Due to these rules, a glob like E<lt>*:E<gt> will find all 408mounted volumes, while a glob like E<lt>*E<gt> or E<lt>:*E<gt> will find 409all files and directories in the current directory. 410 411Note that updirs in the glob pattern are resolved before the matching begins, 412i.e. a pattern like "*HD:t?p::a*" will be matched as "*HD:a*". Note also, 413that a single trailing ':' in the pattern is ignored (unless it's a volume 414name pattern like "*HD:"), i.e. a glob like E<lt>:*:E<gt> will find both 415directories I<and> files (and not, as one might expect, only directories). 416You can, however, use the C<GLOB_MARK> flag to distinguish (without a file 417test) directory names from file names. 418 419If the C<GLOB_MARK> flag is set, all directory paths will have a ':' appended. 420Since a directory like 'lib:' is I<not> a valid I<relative> path on Mac OS, 421both a leading and a trailing colon will be added, when the directory name in 422question doesn't contain any colons (e.g. 'lib' becomes ':lib:'). 423 424=back 425 426=head1 AUTHOR 427 428The Perl interface was written by Nathan Torkington E<lt>gnat@frii.comE<gt>, 429and is released under the artistic license. Further modifications were 430made by Greg Bacon E<lt>gbacon@cs.uah.eduE<gt>, Gurusamy Sarathy 431E<lt>gsar@activestate.comE<gt>, and Thomas Wegner 432E<lt>wegner_thomas@yahoo.comE<gt>. The C glob code has the 433following copyright: 434 435 Copyright (c) 1989, 1993 The Regents of the University of California. 436 All rights reserved. 437 438 This code is derived from software contributed to Berkeley by 439 Guido van Rossum. 440 441 Redistribution and use in source and binary forms, with or without 442 modification, are permitted provided that the following conditions 443 are met: 444 445 1. Redistributions of source code must retain the above copyright 446 notice, this list of conditions and the following disclaimer. 447 2. Redistributions in binary form must reproduce the above copyright 448 notice, this list of conditions and the following disclaimer in the 449 documentation and/or other materials provided with the distribution. 450 3. Neither the name of the University nor the names of its contributors 451 may be used to endorse or promote products derived from this software 452 without specific prior written permission. 453 454 THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 455 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 456 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 457 ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 458 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 459 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 460 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 461 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 462 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 463 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 464 SUCH DAMAGE. 465 466=cut 467